feat: Add canister_metrics endpoint on management canister (#6217)

* feat: Add subnet admins capabilities

* Update docs/references/ic-interface-spec.md

Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com>

* Review comments

* Revert some change

* Use or

* feat: Add canister_metrics endpoint on management canister

* Update docs/references/_attachments/ic.did

Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com>

* Review comments

* Drop one level of indirection

* Flatter structure

* Drop threshold signature metrics

* Review comments

* metrics as query call

* Update docs/references/ic-interface-spec.md

Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com>

* Merge master

* Clarify when canister_metrics can be called

* Move canister_metrics close to canister_status

* Move canister_metrics close to canister_status in main doc too

* Apply suggestions from code review

Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com>

* final touches

* Update docs/references/ic-interface-spec.md

* Update docs/references/ic-interface-spec.md

---------

Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com>

Author: dsarlis

docs/references/_attachments/ic.did

@@ -630,6 +630,30 @@ type upload_canister_snapshot_data_args = record {
     chunk : blob;
 };
 
+type cycles_consumed = record {
+  memory : nat;
+  compute_allocation : nat;
+  ingress_induction : nat;
+  instructions : nat;
+  request_and_response_transmission : nat;
+  // This metric applies to canisters that ran out of cycles. In particular,
+  // uninstalling code explicitly would not result in this metric being updated.
+  // In fact, others might be updated in that case, e.g. cycles for ingress induction
+  // if the uninstallation of the canister was requested via an ingress message.
+  uninstall : nat;
+  canister_creation : nat;
+  http_outcalls : nat;
+  burned_cycles : nat;
+};
+
+type canister_metrics_args = record {
+  canister_id : canister_id;
+};
+
+type canister_metrics_result = record {
+  cycles_consumed : cycles_consumed;
+};
+
 service ic : {
     create_canister : (create_canister_args) -> (create_canister_result);
     update_settings : (update_settings_args) -> ();
@@ -642,6 +666,8 @@ service ic : {
     start_canister : (start_canister_args) -> ();
     stop_canister : (stop_canister_args) -> ();
     canister_status : (canister_status_args) -> (canister_status_result) query;
+    // Returns canister related metrics
+    canister_metrics: (canister_metrics_args) -> (canister_metrics_result) query;
     delete_canister : (delete_canister_args) -> ();
     deposit_cycles : (deposit_cycles_args) -> ();
     raw_rand : () -> (raw_rand_result);

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

@@ -1,5 +1,8 @@
 ## Changelog {#changelog}
 
+### 0.61.0 (2025-05-18) {$0_61_0}
+* New management canister endpoint `canister_metrics`.
+
 ### 0.60.0 (2025-05-04) {$0_60_0}
 * Canister signatures from canisters on subnets of type `cloud_engine` are not valid.
 * New HTTP endpoints for update calls (to create a canister by subnet admins) and

docs/references/ic-interface-spec.md

@@ -2712,6 +2712,22 @@ Only the controllers of the canister or the canister itself or subnet admins can
 
 All sizes are expressed in bytes.
 
+### IC method `canister_metrics` {#ic-canister_metrics}
+
+This method can be called by canisters as well as by external users via ingress messages.
+This method can also be called by external users via non-replicated (query) calls, but it cannot be called from composite query calls.
+
+This method returns a set of canister related metrics for the requested canister, like cycles consumed by different use cases. These metrics should be counters (i.e. monotonically increasing values) that report the accumulated respective amount since the canister was created for new canisters or since the metrics introduction for existing canisters.
+
+Only controllers of the canister or subnet admins can call this method.
+
+:::warning
+
+The response of a query comes from a single replica, and is therefore not appropriate for security-sensitive applications.
+Replica-signed queries may improve security because the recipient can verify the response comes from the correct subnet.
+
+:::
+
 ### IC method `canister_info` {#ic-canister_info}
 
 This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.
@@ -4540,7 +4556,7 @@ liquid_balance(S, E.content.canister_id) ≥ 0
   E.content.arg = candid({canister_id = CanisterId, …})
   E.content.sender ∈ S.controllers[CanisterId] ∪ S.subnet_admins[S.canister_subnet[CanisterId]]
   E.content.method_name ∈
-    { "start_canister", "stop_canister", "uninstall_code", "delete_canister", "canister_status" }
+    { "start_canister", "stop_canister", "uninstall_code", "delete_canister", "canister_status", "canister_metrics" }
 ) ∨ (
   E.content.canister_id = ic_principal
   E.content.sender ∈ S.subnet_admins[S.canister_subnet[ECID]]
@@ -7466,6 +7482,82 @@ S with
 
 ```
 
+#### IC Management Canister: Canister metrics
+
+Only the controllers of the given canister or subnet admins can get metrics about it.
+
+```html
+
+S.messages = Older_messages · CallMessage M · Younger_messages
+(M.queue = Unordered) or (∀ msg ∈ Older_messages. msg.queue ≠ M.queue)
+M.callee = ic_principal
+M.method_name = 'canister_metrics'
+M.arg = candid(A)
+M.caller ∈ S.controllers[A.canister_id] ∪ S.subnet_admins[S.canister_subnet[A.canister_id]]
+
+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
+      }
+
+```
+
+The IC method `canister_metrics` can also be invoked via management canister query calls.
+They are calls to `/api/v3/canister/<ECID>/query`
+with CBOR content `Q` such that `Q.canister_id = ic_principal`.
+
+Submitted request to `/api/v3/canister/<ECID>/query`
+
+```html
+
+E : Envelope
+
+```
+
+Conditions
+
+```html
+
+E.content = CanisterQuery Q
+Q.canister_id = ic_principal
+Q.method_name = 'canister_metrics'
+|Q.nonce| <= 32
+is_effective_canister_id(E.content, ECID)
+S.system_time <= Q.ingress_expiry or Q.sender = anonymous_id
+Q.arg = candid(A)
+A.canister_id ∈ verify_envelope(E, Q.sender, S.system_time)
+Q.sender ∈ S.controllers[A.canister_id] ∪ S.subnet_admins[S.canister_subnet[A.canister_id]]
+
+```
+
+Query response `R`:
+
+```html
+
+{status: "replied"; reply: {arg: candid(<implementation-specific>)}, signatures: Sigs}
+
+```
+
+where the query `Q`, the response `R`, and a certificate `Cert` that is obtained by requesting the path `/subnet` in a **separate** read state request to `/api/v3/canister/<ECID>/read_state` satisfy the following:
+
+```html
+
+verify_response(Q, R, Cert) ∧ lookup(["time"], Cert) = Found S.system_time // or "recent enough"
+
+```
+
+
 #### Callback invocation
 
 When an inter-canister call has been responded to, we can queue the call to the callback.