spec: add subnet_metrics management canister endpoint

docs/references/ic-interface-spec/abstract-behavior.md

@@ -3096,6 +3096,44 @@ S with
 
 ```
 
+#### IC Management Canister: Subnet Metrics
+
+:::note
+
+The subnet metrics management canister API is considered EXPERIMENTAL. Canister developers must be aware that the API may evolve in a non-backward-compatible way.
+
+:::
+
+The management canister returns subnet-wide metrics given a subnet ID. The definition of the metrics values
+is not captured in this formal semantics.
+
+Conditions
+
+```html
+
+S.messages = Older_messages · CallMessage M · Younger_messages
+(M.queue = Unordered) or (∀ CallMessage M' | FuncMessage M' ∈ Older_messages. M'.queue ≠ M.queue)
+M.callee = ic_principal
+M.method_name = 'subnet_metrics'
+M.arg = candid(A)
+R = <implementation-specific>
+
+```
+
+State after
+
+```html
+
+S with
+    messages = Older_messages · Younger_messages ·
+      ResponseMessage {
+        origin = M.origin
+        response = Reply (candid(R))
+        refunded_cycles = M.transferred_cycles
+      }
+
+```
+
 #### IC Management Canister: Subnet information
 
 The management canister returns subnet metadata given a subnet ID.

docs/references/ic-interface-spec/changelog.md

@@ -8,6 +8,13 @@ sidebar:
 
 ## Changelog {#changelog}
 
+### 0.66.0 (2026-08-17) {$0_66_0}
+* New management canister endpoint `subnet_metrics` returning subnet-wide metrics for a
+  given subnet: the current block height, the number of canisters, the total canister
+  state size, the total cycles consumed, and the total number of processed transactions.
+  All fields except the block height were previously only readable by external users via
+  the certified state tree path `/subnet/<subnet_id>/metrics`. The API is EXPERIMENTAL.
+
 ### 0.65.0 (2026-08-03) {$0_65_0}
 * New canister setting `status_visibility` controlling who can read a canister's status via the
   `canister_status` endpoint: `controllers` (default) restricts access to the canister's controllers,

docs/references/ic-interface-spec/management-canister.md

@@ -768,6 +768,38 @@ A single metric entry is a record with the following fields:
 
 - `num_block_failures_total` (`nat64`): the number of failed block proposals by this node.
 
+### IC method `subnet_metrics` {#ic-subnet_metrics}
+
+This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.
+
+:::note
+
+The subnet metrics management canister API is considered EXPERIMENTAL. Canister developers must be aware that the API may evolve in a non-backward-compatible way.
+
+:::
+
+Given a subnet ID as input, this method returns a record of subnet-wide metrics describing that subnet's resource usage and performance.
+
+All fields except `block_height` report the same quantities that the certified state tree exposes at the path `/subnet/<subnet_id>/metrics` (see [Subnet information](./index.md#state-tree-subnet)). This method makes them available to canisters, which cannot read the state tree.
+
+In the following, *the subnet* refers to the subnet identified by the `subnet_id` argument. The fields returned are:
+
+- `block_height` (`nat`): the current block height of the subnet, i.e., the height of the block in whose execution this call is processed.
+
+    Heights are consecutive numbers identifying the successive blocks of a subnet. This specification does not otherwise model block heights, and heights of different subnets are unrelated, so this value is only meaningful when compared against other values for the same subnet.
+
+    The value is monotonically non-decreasing for a given subnet.
+
+- `num_canisters` (`nat`): the number of canisters currently on the subnet. This is a current value, not a counter, so it decreases when canisters are deleted.
+
+- `canister_state_bytes` (`nat`): the total size in bytes of the state currently taken by canisters on the subnet. This is a current value, not a counter.
+
+- `consumed_cycles_total` (`nat`): the total number of cycles removed from circulation on the subnet by all current and deleted canisters. Note that this aggregate is not the same quantity as the `burned_cycles` field of [`canister_metrics`](#ic-canister_metrics), which only reports cycles a canister burned explicitly via `ic0.cycles_burn`.
+
+- `update_transactions_total` (`nat`): the total number of transactions processed on the subnet, i.e., the total number of messages executed in the replicated mode.
+
+The counter fields `consumed_cycles_total` and `update_transactions_total` accumulate since the subnet was created, or since the respective metric was introduced for subnets that predate it.
+
 ### IC method `subnet_info` {#ic-subnet_info}
 
 This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

docs/references/management-canister.md

@@ -562,6 +562,24 @@ Returns a time series of node metrics for a given subnet. Returns up to 60 times
   - `num_blocks_proposed_total` (`nat64`)
   - `num_block_failures_total` (`nat64`)
 
+### `subnet_metrics`
+
+> This API is **experimental** and may change in a non-backward-compatible way.
+
+Returns subnet-wide metrics for a given subnet, which does not have to be the subnet hosting the caller. Every field except `block_height` reports the same quantity that the certified state tree exposes at `/subnet/<subnet_id>/metrics`; this method makes those quantities available to canisters, which cannot read the state tree.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `subnet_id` (`principal`): any subnet
+- **Returns:**
+  - `block_height` (`nat`): the target subnet's current block height, i.e. the height of the block in whose execution the call is processed
+  - `num_canisters` (`nat`): canisters currently on the subnet
+  - `canister_state_bytes` (`nat`): current total size of canister state in bytes
+  - `consumed_cycles_total` (`nat`): total cycles removed from circulation on the subnet
+  - `update_transactions_total` (`nat`): total transactions processed on the subnet
+
+`consumed_cycles_total` and `update_transactions_total` are counters; `num_canisters` and `canister_state_bytes` are current values.
+
 ### `subnet_info`
 
 Returns metadata about a subnet.

public/references/ic.did

@@ -444,6 +444,25 @@ type node_metrics_history_result = vec record {
     node_metrics : vec node_metrics;
 };
 
+type subnet_metrics_args = record {
+    subnet_id : principal;
+};
+
+type subnet_metrics_result = record {
+    // Current block height of the subnet, i.e. the height of the block in
+    // whose execution this call is processed.
+    block_height : nat;
+    // Current number of canisters on the subnet.
+    num_canisters : nat;
+    // Current total size in bytes of the state taken by canisters on the subnet.
+    canister_state_bytes : nat;
+    // Total cycles removed from circulation on the subnet by all current and
+    // deleted canisters.
+    consumed_cycles_total : nat;
+    // Total number of transactions processed on the subnet.
+    update_transactions_total : nat;
+};
+
 type subnet_info_args = record {
     subnet_id : principal;
 };
@@ -708,6 +727,7 @@ service ic : {
 
     // metrics interface
     node_metrics_history : (node_metrics_history_args) -> (node_metrics_history_result);
+    subnet_metrics : (subnet_metrics_args) -> (subnet_metrics_result);
 
     // subnet info
     subnet_info : (subnet_info_args) -> (subnet_info_result);