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 number of instructions the subnet accounted for when executing its blocks.

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; a free schedule waives resource charges only, such as instruction execution, memory usage, and HTTPS outcalls, while cycles burned via ic0.cycles_burn128, deleted canisters' remaining cycle balances, and the cycles of dropped messages or refunds are still lost) and nominal cycles (the normal-schedule amount for resource charges, and the amount lost for cycles that are lost under either schedule), and corrected descriptions of the four aggregates under /subnet/<subnet_id>/metrics (current values vs. counters, the 10-block refresh of canister_state_bytes, the full composition of consumed_cycles_total, as a list of its four summands), so the state tree and the method describe the same quantities.
• ic-interface-spec/changelog.md: version 0.69.0 entry covering the new endpoint, the new definitions, and the clarified state tree metrics (still the next version after merging the latest main, whose newest entry is 0.68.0).
• 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 every 10 blocks, at heights that are multiples of 10. 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 the canisters currently on the subnet, the historical consumption of the canisters deleted on the subnet plus their remaining cycle balances at deletion, the cycles charged at the subnet level for HTTPS outcalls, threshold signature requests, and vetKD requests, and the cycles lost when messages or refunds are dropped (for example, because their recipient no longer exists). 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. It counts the instructions accounted for when executing the subnet's blocks. 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.
• dfinity/ic: the million_round_instructions_total comment in rs/types/management_canister_types/tests/ic.did says "Unlike the four fields above", but five fields precede it and block_height also has no state tree path.

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

[mraszyk]

Feedback addressed (a100725), all ten suggestions from @eichhorl applied as proposed:

• changelog.md: entry now says nominal cycles, names the two fields without a state tree path, and has new bullets for the cost schedule / nominal cycles definitions and the clarified state tree metrics
• index.md: cost schedules name HTTPS outcalls and link ic0.cycles_burn128; nominal cycles cover explicitly burned and lost cycles; consumed_cycles_total in the state tree is a list of summands
• management-canister.md (spec): same consumed_cycles_total restructuring; million_round_instructions_total is described in terms of blocks; split long sentences
• references/management-canister.md: blocks instead of rounds, "never decrease", dropped the "up to 10 blocks behind" claim
• ic.did: reflowed the consumed_cycles_total comment; "Like block_height" instead of "Unlike the four fields above"

didc check public/references/ic.did and npm run build pass.