specify IC management method for retrieving metrics

spec/_attachments/ic.did

@@ -111,6 +111,15 @@ type send_transaction_request = record {
 
 type millisatoshi_per_byte = nat64;
 
+type metrics = variant {
+  node_metrics : record {
+    node_id : principal;
+    start_timestamp_nanos : nat64;
+    end_timestamp_nanos : nat64;
+    num_proposed_blocks : nat;
+  }
+};
+
 service ic : {
   create_canister : (record {
     settings : opt canister_settings;
@@ -184,6 +193,13 @@ service ic : {
   bitcoin_send_transaction: (send_transaction_request) -> ();
   bitcoin_get_current_fee_percentiles: (get_current_fee_percentiles_request) -> (vec millisatoshi_per_byte);
 
+  // metrics interface
+  metrics : (record {
+    subnet_id : principal;
+  }) -> (record {
+    metrics : vec metrics;
+  });
+
   // provisional interfaces for the pre-ledger world
   provisional_create_canister_with_cycles : (record {
     amount: opt nat;

spec/index.md

@@ -2113,6 +2113,16 @@ This function returns fee percentiles, measured in millisatoshi/vbyte (1000 mill
 
 The [standard nearest-rank estimation method](https://en.wikipedia.org/wiki/Percentile#The_nearest-rank_method), inclusive, with the addition of a 0th percentile is used. Concretely, for any i from 1 to 100, the ith percentile is the fee with rank `⌈i * 100⌉`. The 0th percentile is defined as the smallest fee (excluding coinbase transactions).
 
+### IC method `metrics` {#ic-metrics}
+
+Given a subnet ID as input, this method returns a collection of metrics for the given subnet.
+
+A single metric entry is of an enumeration type with a single variant (in the future, more variants might be added):
+
+- `node_metrics`: provides metrics for a node characterized by its principal (field `node_id`), for a period of time characterized by start and end timestamps in nanoseconds since 1970-01-01 (fields `start_timestamp_nanos` and `end_timestamp_nanos`), and the actual metrics values:
+
+  - `num_proposed_blocks` (`nat`): the number of blocks proposed by this node.
+
 ## Certification {#certification}
 
 Some parts of the IC state are exposed to users in a tamperproof way via certification: the IC can reveal a *partial state tree* which includes just the data of interest, together with a signature on the root hash of the state tree. This means that a user can be sure that the response is correct, even if the user happens to be communicating with a malicious node, or has received the certificate via some other untrusted way.
@@ -4140,6 +4150,38 @@ S with
 
 ```
 
+#### IC Management Canister: Metrics
+
+The management canister can returns metrics for a given subnet. 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 (∀ msg ∈ Older_messages. msg.queue ≠ M.queue)
+M.callee = ic_principal
+M.method_name = 'metrics'
+M.arg = candid()
+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: Canister creation with cycles
 
 This is a variant of `create_canister`, which sets the initial cycle balance based on the `amount` argument.