feat: Add canister_metrics endpoint on management canister by dsarlis · Pull Request #6217 · dfinity/portal

dsarlis · 2026-04-07T07:35:51Z

This PR introduces a management canister API that will be used to report canister related metrics to canister controllers or subnet admins. The API currently only includes a set of cycles consumed by different use cases but is designed that it can be easily extended to include more metrics (whether cycles related or even calls processed etc).

Follows the developer docs style guide.
Follows the best practices and guidelines.
New documentation pages include document tags.
New documentation pages include SEO keywords.
New documents are in the .mdx file format to support the previous two components.
New documents are registered in /sidebars.js, otherwise, it will not appear in the
side navigation bar.
Make sure that the .github/CODEOWNERS file is
contains any new directories or specific documents that you added that should be reviewed by a specific teamm.

Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com>

mraszyk

LGTM modulo the note about query calls in the formal part of the spec

Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com>

Add counter versions of metrics for consumed cycles that are stored in `ReplicatedState`. The existing ones behave like gauges (so their values can go down when prepayments are made and up when refunds are issued) which makes it more challenging for consumers to build automated monitoring tools to perform aggregations over them. By having them monotonically increase, it's easier to calculate rates of change, show aggregates over time etc. The key idea is to introduce a second map of `<CyclesUseCase, NominalCycles>` in the `ReplicatedState` that will only be updated once per use case: either at the payment stage if we know the precise amount or only at refund stage if a prepayment is made with an expected refund later. The second map is quite similar to the existing in all other aspects (how they are stored in checkpoints or how they are exposed as prometheus metrics) besides how the values are updated. A new map is introduced to ease the transition as migrating from the old map to new is non-trivial given that a proper cutoff point needs to be introduced to handle outstanding callbacks that might have been created before the metric introduction. This is left for a follow-up if and when people decide to do it. The new map will be used in a follow up that will implement the [new management canister endpoint](dfinity/portal#6217) to retrieve canister level metrics. Additionally, the new metrics include the use case `HttpsOutcalls` in the canister level metrics as it's useful to determine how much each canister uses this feature. I've opted to not change existing metrics to do the same as it would make things less clean imo than the current approach -- a single specific API is used to perform this update in exactly one place where it's needed. The changes in the PR are mostly driven by the addition of the new map of metrics, updates in protobuf files to store the new metrics, the changes to support having the `HttpsOutcalls` use case additionally included as well as some changes in tests to support the new metrics.

mraszyk

This doesn't seem merged at the moment so not sure what kind of feedback/action is expected.

mraszyk · 2026-05-05T10:31:16Z

    list_canisters : () -> (list_canisters_result) query;
+
+    // Returns canister related metrics
+    canister_metrics: (canister_metrics_args) -> (canister_metrics_result) query;


let's move this close to canister_status since it belongs together

You mean only here or also in the main document? It's now listed as the last API, it seems we kinda follow chronological order there but I can move it, I don't have a strong opinion.

dsarlis · 2026-05-05T12:11:05Z

This doesn't seem merged at the moment so not sure what kind of feedback/action is expected.

Nothing more than what you already provided. I merged with master and had to fix some conflicts, so I just wanted to make sure it's ready (sans the changelog entry which will happen right before merging).

Implement the `canister_metrics` endpoint as described in dfinity/portal#6217 to allow controllers or subnet admins to retrieve canister level metrics for a target canister. The metrics currently contain some basic cycles related ones but can be extended in the future to contain more. The necessary boilerplate is added to wire the new endpoint through the code stack. As defined in the interface spec, the API is available both in replicated mode as well as a query call. A few tests are also added to ensure that the endpoint correctly returns the values that are present in the replicated state.

dsarlis and others added 12 commits February 18, 2026 11:29

feat: Add subnet admins capabilities

d354229

Update docs/references/ic-interface-spec.md

a9b6601

Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com>

Review comments

739dcc6

Revert some change

b984cb5

Use or

da30336

feat: Add canister_metrics endpoint on management canister

e92ec2c

Update docs/references/_attachments/ic.did

969fac8

Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com>

Review comments

3e58576

Drop one level of indirection

785bfea

Flatter structure

7e3dbae

Drop threshold signature metrics

dcead06

Merge branch 'master' into dimitris/management-canister-metrics

e968132

dsarlis requested review from a team as code owners April 7, 2026 07:35

github-actions Bot added the interface-spec Changes to the IC Interface Specification label Apr 7, 2026