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 plus the four aggregates the certified state tree already exposes at /subnet/<subnet_id>/metrics.

The block height is genuinely new; the other four 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 all five are bundled rather than only the block height and consumed_cycles_total originally requested.

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;
};

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 four 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 is a true counter.

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

Verification

Every claim was checked field by field 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). 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.68.0 (2026-09-14) entry.
• 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