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 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.

Changes

• ic-interface-spec/management-canister.md: new section for subnet_metrics with the full field semantics.
• ic-interface-spec/abstract-behavior.md: new transition for subnet_metrics; the metric values are implementation-specific and attached cycles are refunded.
• ic-interface-spec/index.md: new definitions of cost schedules (normal and free) and nominal cycles, and corrected descriptions of the four aggregates under /subnet/<subnet_id>/metrics, so the state tree and the method describe the same quantities.
• ic-interface-spec/changelog.md: version 0.69.0 entry.
• references/management-canister.md: condensed reference entry linking to the spec.
• public/references/ic.did: new types and method, with field comments.

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 (not via ingress), and subnet_id may name any subnet, not only the caller's.

Field semantics

• Only block_height describes the block in whose execution the call is processed. The other five are aggregates refreshed at block boundaries, so they describe an earlier block; they are not refreshed at the same rate, so they need not be mutually consistent.
• num_canisters and canister_state_bytes are current values, not counters. canister_state_bytes refreshes only at heights that are multiples of 10, so it can be up to 10 blocks behind block_height and up to 9 blocks behind the other aggregates. It reads 0 before the first refresh.
• consumed_cycles_total is measured in nominal cycles: resource charges are recorded at normal cost-schedule rates even on a subnet with a free cost schedule, where no cycles are deducted from canister balances. It sums the historical consumption of current canisters, the subnet's retained accounting for deleted canisters (including their remaining balances at deletion), the cycles charged at the subnet level for HTTPS outcalls, threshold signature requests, and vetKD requests, and the cycles attached to dropped best-effort responses. Refunds of prepaid charges reduce the total. Subnet splitting redistributes canisters' histories, so the total can decrease and can include consumption from before the receiving subnet was created. It is not a count of cycles actually burned on this subnet.
• update_transactions_total counts messages executed in replicated mode. It and million_round_instructions_total are monotonically non-decreasing counters covering the subnet's lifetime, or the period since each metric was introduced for subnets that predate it.
• million_round_instructions_total is reported in units of one million and rounded up: a value of 42 represents 41,000,001 through 42,000,000 instructions. 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.

Follow-ups outside this repo

• ic-cdk and Motoko management canister bindings.

🤖 Generated with Claude Code

[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.