Skip to content
This repository has been archived by the owner on Nov 19, 2024. It is now read-only.

Commit

Permalink
specify IC management method for retrieving metrics (#215)
Browse files Browse the repository at this point in the history
  • Loading branch information
mraszyk authored Dec 5, 2023
1 parent 41c0332 commit b263379
Show file tree
Hide file tree
Showing 3 changed files with 74 additions and 0 deletions.
15 changes: 15 additions & 0 deletions spec/_attachments/ic.did
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,12 @@ type send_transaction_request = record {

type millisatoshi_per_byte = nat64;

type node_metrics = record {
node_id : principal;
num_blocks_total : nat64;
num_block_failures_total : nat64;
};

service ic : {
create_canister : (record {
settings : opt canister_settings;
Expand Down Expand Up @@ -215,6 +221,15 @@ service ic : {
bitcoin_send_transaction: (send_transaction_request) -> ();
bitcoin_get_current_fee_percentiles: (get_current_fee_percentiles_request) -> (vec millisatoshi_per_byte);

// metrics interface
node_metrics_history : (record {
subnet_id : principal;
start_at_timestamp_nanos: nat64;
}) -> (vec record {
timestamp_nanos : nat64;
node_metrics : vec node_metrics;
});

// provisional interfaces for the pre-ledger world
provisional_create_canister_with_cycles : (record {
amount: opt nat;
Expand Down
1 change: 1 addition & 0 deletions spec/_attachments/interface-spec-changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
* Update specification of responses from the endpoint `/api/v2/status`.
* Stop canister calls might be rejected upon timeout.
* The IC sends a `user-agent` header with the value `ic/1.0` in canister HTTPS outcalls if the canister does not provide one.
* Add a management canister method for retrieving node metrics.

### 0.22.0 (2023-11-15) {#0_22_0}
* Add metrics on subnet usage into the certified state tree and a new HTTP endpoint `/api/v2/subnet/<subnet_id>/read_state` for retrieving them.
Expand Down
58 changes: 58 additions & 0 deletions spec/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2190,6 +2190,26 @@ If you do not specify the `max_response_bytes` parameter, the maximum of a `2MB`

:::

### IC method `node_metrics_history` {#ic-node-metrics-history}

:::note

The node 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 time series of node metrics (field `node_metrics`). The timestamps are represented as nanoseconds since 1970-01-01 (field `timestamp_nanos`) at which the metrics were sampled. The returned timestamps are all timestamps after (and including) the provided timestamp (field `start_at_timestamp_nanos`) for which node metrics are available. The maximum number of returned timestamps is 60 and no two returned timestamps belong to the same UTC day.

Note that a sample will only include metrics for nodes whose metrics changed compared to the previous sample. This means that if a node disappears in one sample and later reappears its metrics will restart from 0 and consumers of this API need to adjust for these resets when aggregating over multiple samples.

A single metric entry is a record with the following fields:

- `node_id` (`principal`): the principal characterizing a node;

- `num_blocks_total` (`nat64`): the number of blocks proposed by this node;

- `num_block_failures_total` (`nat64`): the number of failed block proposals by this node.

### IC method `provisional_create_canister_with_cycles` {#ic-provisional_create_canister_with_cycles}

As a provisional method on development instances, the `provisional_create_canister_with_cycles` method is provided. It behaves as `create_canister`, but initializes the canister's balance with `amount` fresh cycles (using `DEFAULT_PROVISIONAL_CYCLES_BALANCE` if `amount = null`). If `specified_id` is provided, the canister is created under this id. Note that canister creation using `create_canister` or `provisional_create_canister_with_cycles` with `specified_id = null` can fail after calling `provisional_create_canister_with_cycles` with provided `specified_id`. In that case, canister creation should be retried.
Expand Down Expand Up @@ -4709,6 +4729,44 @@ S with

```

#### IC Management Canister: Node Metrics

:::note

The node 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 metrics for nodes on 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 = 'node_metrics_history'
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: Canister creation with cycles

This is a variant of `create_canister`, which sets the initial cycle balance based on the `amount` argument.
Expand Down

0 comments on commit b263379

Please sign in to comment.