feat: Add canister_metrics endpoint on management canister

docs/references/_attachments/ic.did

@@ -621,6 +621,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) -> ();
@@ -683,4 +707,7 @@ service ic : {
 
     // canister logging
     fetch_canister_logs : (fetch_canister_logs_args) -> (fetch_canister_logs_result) query;
+
+    // Returns canister related metrics
+    canister_metrics: (canister_metrics_args) -> (canister_metrics_result) query;
 };

docs/references/ic-interface-spec.md

@@ -3272,6 +3272,15 @@ Replica-signed queries may improve security because the recipient can verify the
 
 :::
 
+### 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 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.
+
+
 ## The IC Bitcoin API {#ic-bitcoin-api}
 
 The Bitcoin API exposed by the management canister is DEPRECATED.
@@ -4402,7 +4411,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.method_name ∈
@@ -7262,6 +7271,38 @@ 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
+      }
+
+```
+
+
 #### Callback invocation
 
 When an inter-canister call has been responded to, we can queue the call to the callback.