diff --git a/docs/references/ic-interface-spec/abstract-behavior.md b/docs/references/ic-interface-spec/abstract-behavior.md index 3cf4d5d..5932b61 100644 --- a/docs/references/ic-interface-spec/abstract-behavior.md +++ b/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 = + +``` + +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. diff --git a/docs/references/ic-interface-spec/changelog.md b/docs/references/ic-interface-spec/changelog.md index 8ea791e..242b5bd 100644 --- a/docs/references/ic-interface-spec/changelog.md +++ b/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//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, diff --git a/docs/references/ic-interface-spec/management-canister.md b/docs/references/ic-interface-spec/management-canister.md index 21a83f3..fcd34f2 100644 --- a/docs/references/ic-interface-spec/management-canister.md +++ b/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//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. diff --git a/docs/references/management-canister.md b/docs/references/management-canister.md index b33270f..82e5b97 100644 --- a/docs/references/management-canister.md +++ b/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//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. diff --git a/public/references/ic.did b/public/references/ic.did index 23c9e10..b628f49 100644 --- a/public/references/ic.did +++ b/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);