spec: add subnet_metrics management canister endpoint

[Dfinity-Bjoern]

Summary

Draft for discussion, not ready to merge. Proposes a new EXPERIMENTAL management canister endpoint subnet_metrics that returns subnet-wide metrics to canisters.

Motivating request: move more dashboard data collection on chain, starting with the subnet block height and the total cycles burned on a subnet.

What already exists

• Cycles burned: already in the certified state tree, as consumed_cycles_total at /subnet/<subnet_id>/metrics, alongside num_canisters, canister_state_bytes, and update_transactions_total. But that path is readable only by external users via read_state at /api/v2|v3/subnet/<subnet_id>/read_state, and only when the effective subnet id matches. There is no way for a canister to read it, since no System API or management canister method exposes state tree paths to canister code.
• Height: not exposed anywhere in the spec. subnet_info returns only replica_version and registry_version. update_transactions_total counts messages, not blocks. Summing num_blocks_proposed_total from node_metrics_history is at best an approximation: counted only since the metric was introduced, sampled at most daily, capped at 60 samples, and documented as resetting to 0 when a node disappears and reappears. The /api/v2/status endpoint lists block height explicitly as a possible future addition.

So the endpoint adds one genuinely new value (the block height) and makes four existing values reachable from canisters, which is why all five are bundled rather than just the two originally requested.

Proposed 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, subnet_id may be any subnet.

Resolved in review

• Any subnet, no restriction. An earlier revision required subnet_id to be the caller's own subnet. Removed: cross-subnet calls are carried by the existing message routing protocol, so the request reaches the target subnet and its response comes back without any special handling. The abstract-behavior condition tying subnet_id to the caller's subnet is gone too.
• Current block height. block_height is the height of the block in whose execution the call is processed. Since a call naming a remote subnet is routed there and processed there, this is the target subnet's current height, not the caller's. Certified height was considered and rejected.
• No cycle fee and no explicit PocketIC support needed. Both follow-ups dropped.
• nat throughout. nat64 was preferred for consistency with node_metrics and for fixed-width parsing, but consumed_cycles_total is u128 in the implementation (which is exactly why the state tree splits it into a low nat plus an optional high nat under CBOR), so it cannot be nat64. Rather than mix widths or reproduce the CBOR low/high workaround in a format that has unbounded nat natively, all five fields are nat. This also matches canister_status and canister_metrics, which use nat throughout.
• Kept separate from subnet_info. Folding the metrics in as a nested metrics field was considered. Against it: 0.61.0 added canister_metrics as a new endpoint rather than extending canister_status, which is the same situation; and subnet_info is not EXPERIMENTAL, so nesting an evolving record inside it means the caveat either leaks onto the whole endpoint or hides in a per-field note. Merging later remains backward compatible if we change our minds; splitting later would not be.

Still open

• Gauge vs counter. num_canisters and canister_state_bytes are documented as current values; consumed_cycles_total and update_transactions_total as counters. The existing state tree description of canister_state_bytes in index.md says "since this subnet was created", which reads as a counter and is probably imprecise wording. If so it should be fixed there too. Marked in the diff.
• First consensus-level concept in the interface spec. "Block height" appears nowhere else in the specification; the abstract behavior models no blocks at all. The new section therefore defines the term locally and notes that heights of different subnets are unrelated. Worth a sanity check that we are comfortable introducing this vocabulary here.

Files changed

• public/references/ic.did - new subnet_metrics_args / subnet_metrics_result types and the service method. didc check passes.
• docs/references/ic-interface-spec/management-canister.md - new normative IC method subnet_metrics section.
• docs/references/ic-interface-spec/abstract-behavior.md - new IC Management Canister: Subnet Metrics semantics block.
• docs/references/ic-interface-spec/changelog.md - 0.65.0 entry. Version and date need confirming at merge time.
• docs/references/management-canister.md - non-normative reference page entry.

No changes needed to the ingress authorization list, Effective canister id, or Effective subnet id, because the method is not callable via ingress messages.

Follow-ups outside this repo

• ic-cdk and Motoko management canister bindings.
• Optionally add the block height to /subnet/<subnet_id>/metrics in the state tree as well, so external users get it in certified form without deploying a canister.

npm run build passes.

[github-actions]

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

[mraszyk]

this should be updated before merging

[mraszyk]

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