docs: canister logs guide

[marc0olo]

Summary

• Covers writing log messages in Rust (ic_cdk::println!) and Motoko (Debug.print from mo:core/Debug)
• Explains log persistence behavior: captured even on trap, survives mid-execution failures, available to controllers
• Documents how to retrieve logs via icp canister logs <id> CLI command
• Covers log streaming, log size limits, and canister query statistics API
• Includes guidance on structured logging patterns and log levels using log metadata

Sync recommendation

Informed by dfinity/icskills — skills/icp-cli/SKILL.md; informed by dfinity/portal — docs/building-apps/canister-management/logs.mdx; informed by dfinity/icp-cli — command reference

[marc0olo]

Review: Canister Logs

Must fix

• Wrong CLI command throughout: The page uses icp canister update-settings in 7 places (lines 118, 124, 132, 139, 146, 180, and the "Next steps" section at line 403). The correct command is icp canister settings update — verified against .sources/icp-cli/docs/reference/cli.md. The update-settings subcommand does not exist in icp-cli; it was the dfx equivalent. Every icp canister update-settings occurrence must be replaced with icp canister settings update.

• Contradictory query stats reset claim: Lines 254 and 321 contradict each other. Line 254 says stats are "cumulative since the canister was last installed or upgraded" but line 321 says "These cumulative totals reset to zero when the canister is reinstalled or upgraded." These two statements are mutually exclusive. No source material in .sources/ documents the reset behavior. Suggested fix: verify whether upgrades reset query stats. If they do not reset on upgrade (the more common behavior), change line 321 to "reset to zero when the canister is reinstalled" — drop "or upgraded." If they do reset on upgrade, change line 254 to "since the canister was last installed or reinstalled."

• Unused import in Rust query stats code: The Rust snippet (lines 259-278) imports both CanisterStatusArgs and CanisterIdRecord but only uses CanisterIdRecord in the struct literal. Since CanisterStatusArgs = CanisterIdRecord (a type alias), this produces an unused import warning. Fix by using CanisterStatusArgs { canister_id: ic_cdk::id() } consistently (clearest intent, matches the function's declared parameter type), or remove the CanisterStatusArgs import.

Suggestions

• Deprecated API path in backtrace example: The Rust backtrace illustration (lines 205-209) calls ic_cdk::api::stable::stable_write(...). The api::stable module is deprecated since ic-cdk 0.18.0 — moved to crate root ic_cdk::stable. The code is used only to illustrate a trap scenario, not as a code template, but a short comment noting the deprecation would prevent developers from copying the deprecated import path.

• Access log format table omits several fields from portal source: The portal source (building-apps/advanced/canister-access-logs.mdx) lists 14+ fields. The page's table covers 9 fields and the example JSON omits ic_node_id, ic_subnet_id, request_id, request_size, http_version, and others present in the portal's canonical example. The intro already says "Key fields" — this framing is acceptable. Consider whether ic_node_id and ic_subnet_id should be added since they are useful for routing/debugging.

• Query stats epoch frequency is unverified: The claim "approximately once per epoch (roughly every 10 minutes)" at line 255 is not found in any .sources/ material. If this is accurate, a <\!-- Needs human verification: epoch duration for query stats --> flag should be added per project policy on unverified claims.

• Backtrace section missing ic-wasm metadata example: The portal backtraces source (building-apps/canister-management/backtraces.mdx) mentions that ic-wasm metadata also requires --keep-name-section. The page at lines 229-231 shows shrink and optimize examples but omits metadata. Minor gap worth addressing for completeness.

Verified

• icp canister logs command and all flags (--follow, --interval, --since, --until, --since-index, --until-index, --json) verified against .sources/icp-cli/docs/reference/cli.md. All flags exist and all descriptions are accurate.
• ic_cdk::println\! macro verified in .sources/cdk-rs/ic-cdk/src/lib.rs. The fallback to std::println\! outside Wasm is correctly documented.
• Debug.print from mo:core/Debug verified in .sources/motoko-core/src/Debug.mo.
• QueryStats struct fields (num_calls_total, num_instructions_total, request_payload_bytes_total, response_payload_bytes_total) verified in .sources/cdk-rs/ic-management-canister-types/src/lib.rs.
• ic_cdk::management_canister::canister_status signature verified in .sources/cdk-rs/ic-cdk/src/management_canister.rs. Return type is CallResult<CanisterStatusResult> — correct for the new non-deprecated API path (not a tuple unlike the old api::management_canister API).
• Both CanisterStatusArgs and CanisterIdRecord are re-exported from ic_cdk::management_canister — confirmed. CanisterStatusArgs is a type alias for CanisterIdRecord.
• icp.yaml log_visibility values (controllers, public, allowed_viewers object) verified against .sources/icp-cli/docs/reference/canister-settings.md.
• log_memory_limit default (4096 bytes), max (2 MiB), and unit suffixes verified against CLI reference and canister-settings reference.
• Access log WebSocket URL format (wss://{api_bn_domain}/logs/canister/{canister_id}) and dfinity/ic-bn-logs link match portal source exactly.
• fetch_api_boundary_nodes_by_subnet_id function and subnet ID tdb26-jop6k-aogll-7ltgs-eruif-6kk7m-qpktf-gdiqx-mxtrf-vb5e6-eqe verified in .sources/portal/docs/building-apps/advanced/canister-access-logs.mdx.
• Backtrace output text and function names verified against .sources/portal/docs/building-apps/canister-management/backtraces.mdx.
• ic-wasm --keep-name-section requirement and version >= 0.8.6 verified against portal backtraces source.
• Principal.fromActor in Motoko verified in .sources/motoko-core/src/Principal.mo.
• Internal link ../testing/strategies.md resolves — file exists at docs/guides/testing/strategies.md.
• Internal link ../../reference/management-canister.md resolves — file exists at docs/reference/management-canister.md.
• lifecycle.md link in "Next steps" — Astro resolves .md links to .mdx; lifecycle.mdx exists at docs/guides/canister-management/lifecycle.mdx.
• wasm-objdump link https://github.com/WebAssembly/wabt matches portal source.
• Frontmatter is complete (title, description, sidebar order present).
• <\!-- Upstream: --> comment present at end of file listing all consulted sources.
• No dfx references in content.
• No .mdx/JSX syntax used (correct — page is .md).
• All code snippets are under 30 lines inline.

[marc0olo]

Feedback addressed:

• Replaced all 5 occurrences of icp canister update-settings with icp canister settings update (the correct icp-cli command; update-settings is the deprecated dfx equivalent)
• Resolved query stats reset contradiction: per IC interface spec, query_stats is only initialized on canister creation (create_canister), not on install_code (upgrade or reinstall). Updated description to "cumulative since the canister was created"; added TODO flags for human verification of exact reset behavior
• Removed unused CanisterStatusArgs import from Rust query stats snippet (it's a type alias for CanisterIdRecord; the literal already uses CanisterIdRecord)
• Added deprecation note to backtrace api::stable example (deprecated since ic-cdk 0.18.0; current path is ic_cdk::stable)
• Added <!-- TODO: verify epoch duration for query stats --> flag for the unverified "roughly every 10 minutes" claim