spec: add subnet_metrics management canister endpoint

[Dfinity-Bjoern]

Summary

Specifies the EXPERIMENTAL management canister endpoint subnet_metrics, which returns subnet-wide metrics to canisters: the subnet block height, the four aggregates the certified state tree already exposes at /subnet/<subnet_id>/metrics, and the total round instructions.

The block height is genuinely new; the four aggregates exist in the state tree but are unreachable from canister code, since no System API or management canister method exposes state tree paths. That is why they are bundled rather than only the block height and consumed_cycles_total originally requested.

Covers two replica PRs:

• feat: Add subnet_metrics management canister endpoint ic#11032 - the endpoint and its first five fields.
• feat: Export million_round_instructions_total in subnet_metrics ic#11587 - the sixth field million_round_instructions_total.

Interface

type subnet_metrics_args = record { subnet_id : principal };

type subnet_metrics_result = record {
    block_height : nat;
    num_canisters : nat;
    canister_state_bytes : nat;
    consumed_cycles_total : nat;
    update_transactions_total : nat;
    million_round_instructions_total : nat;
};

Callable by canisters only, replicated calls only, no cycle fee, and subnet_id may name any subnet (the call is routed there and answered by that subnet).

Field semantics

• Only block_height is current: it is the height of the block in whose execution the call is processed. The other five are end-of-round aggregates, so a call in round N sees round N-1, and they are not refreshed at the same rate, so they need not be mutually consistent.
• canister_state_bytes refreshes only at heights that are multiples of 10, so it can lag the other fields by up to 10 blocks and reads 0 before the first refresh.
• consumed_cycles_total is not a counter: its per-canister part is a gauge that prepayment raises and refund lowers, so the total can decrease. update_transactions_total and million_round_instructions_total are true counters.
• million_round_instructions_total is reported in units of one million and rounded up. Besides the executed Wasm instructions it covers the fixed per-execution and per-canister overheads charged by the scheduler and the charges for work performed outside of Wasm execution (compilation, chunk assembly, snapshots), so it is not a Wasm instruction meter.
• block_height and million_round_instructions_total are the two fields with no path under /subnet/<subnet_id>/metrics, so they are available only through this method and cannot be verified against a certificate.

The state tree description in index.md covers the same four aggregates, so it gets the same corrections.

Verification

Every claim was checked field by field against the implementation. The first five fields were checked against 7360f8f3, the revision running on all 42 subnets (implementing PR dfinity/ic#11032, first release release-2026-09-03_04-41-base, rollout completed 2026-09-14). million_round_instructions_total was checked against dfinity/ic#11587 at its merge commit 2788b2b1. Candid shape, names, types and order match rs/types/management_canister_types/tests/ic.did; didc check public/references/ic.did passes.

Files changed

• public/references/ic.did - new arg/result types and service method.
• docs/references/ic-interface-spec/management-canister.md - normative subnet_metrics section.
• docs/references/ic-interface-spec/abstract-behavior.md - semantics block.
• docs/references/ic-interface-spec/index.md - corrected descriptions of the same aggregates under /subnet/<subnet_id>/metrics.
• docs/references/ic-interface-spec/changelog.md - 0.69.0 (2026-09-17) entry (renumbered from 0.68.0, which main now uses for the flexible outcalls release).
• docs/references/management-canister.md - non-normative reference entry.

The ingress authorization list, Effective canister id and Effective subnet id need no changes, since the method is not callable via ingress.

Open questions

• First consensus-level concept in the spec. "Block height" appears nowhere else, and the abstract behavior models no blocks, so the new section defines the term locally and notes that heights of different subnets are unrelated. Worth confirming we are comfortable introducing this vocabulary here.
• The 10-block interval is stated as a concrete constant. If the spec should not pin it, that sentence can go back to a hedge.

Follow-ups outside this repo

• ic-cdk and Motoko management canister bindings.
• Optionally expose the block height at /subnet/<subnet_id>/metrics too, so external users get it in certified form without deploying a canister.

[github-actions]

🤖 Here's your preview: https://hada6-4yaaa-aaaam-abaha-cai.icp0.io

[mraszyk]

LGTM now, I'll approve once this is rolled out to all subnets to prevent accidental merge before that

[mraszyk]

Merged origin/main into the branch and folded in dfinity/ic#11587, which adds a sixth field to this endpoint.

Conflict resolution: the only conflict was in changelog.md. Main took 0.68.0 (2026-09-14) for the flexible outcalls release, so this entry is renumbered to 0.69.0 (2026-09-17).

New field, million_round_instructions_total (nat): the total instructions the subnet accounted for across the execution phases of all rounds, in units of one million and rounded up. Besides the executed Wasm instructions it covers the fixed per-execution and per-canister overheads charged by the scheduler and the charges for work performed outside of Wasm execution (compilation, chunk assembly, snapshots), so it is not a Wasm instruction meter. It is a true counter and, like the other counters, covers the subnet's whole lifetime or the period since the metric was introduced for subnets that predate it.

Claims adjusted, because the field breaks the previous four-plus-one split:

• "All fields except block_height report the same quantities that the certified state tree exposes" is now false. The four aggregates are named explicitly, and block_height and million_round_instructions_total are called out as having no path under /subnet/<subnet_id>/metrics, so they are available only through this method.
• "The other four fields are aggregates refreshed at block boundaries" becomes five, in the spec section, the non-normative reference, and the ic.did type comment.
• The lifetime-coverage sentence now lists all three counters.

didc check public/references/ic.did passes. The abstract behavior block needs no change: it leaves the metrics values implementation-specific.

The endpoint was verified against 7360f8f3 as before; the new field against 2788b2b1, the merge commit of dfinity/ic#11587.