Skip to main content

Logging

Beginner
Tutorial

Overview​

The canister logging feature is designed to provide developers with insight into their canister's behavior and assist with scenarios where their canister traps. This feature supports log messages for:

  • Heartbeats.

  • Timers.

  • Pre/post upgrade and canister_init.

  • Update calls.

  • Queries, only if called in replicated mode.

A canister's controller is able to retrieve the canister's logs, even when executions trap, using dfx canister logs:

dfx canister logs <canister-name>

Non-replicated calls are not currently supported for logging.

Log visibility​

By default, a canister's logs are only visible to the controllers of the canister. A canister's logs can be made public by updating the canister's settings with dfx canister update-settings command:

dfx canister update-settings <canister-name> --log-visibility public

Log viewer allow lists​

Canister log allow lists enable principals that are not controllers of the canister to view the logs without the logs being public. Log allow lists are supported in dfx versions 0.24.2 and newer.

To add a principal to the canister's log allow list, update the canister's settings with the flags:

  • dfx canister update-settings <canister-name> --set-log-viewer PRINCIPAL_ID: Set a single principal as a log viewer.

  • dfx canister update-settings <canister-name> --add-log-viewer PRINCIPAL_ID: Add a principal to a list of log viewers.

  • dfx canister update-settings <canister-name> --remove-log-viewer PRINCIPAL_ID: Remove a principal from the log viewer list.

You can also configure a principal as a log viewer when you create a canister:

dfx canister create <canister-name> --log-viewer PRINCIPAL_ID

Or, you can set the canisters[].initialization_values.log_visibility.allowed_viewers configuration setting in your project's dfx.json file.