Crate ic_analytics_sdk 

Rust SDK for sending metrics from any Internet Computer canister to an IC Metrics analytics canister.

Installation

[dependencies]
ic-analytics-sdk = "0.2.3"

Quick start

1. Initialise the client

AnalyticsClient holds the principal of your analytics canister. Create it once and store it in a thread_local!.

use ic_analytics_sdk::AnalyticsClient;
use candid::Principal;

thread_local! {
    static ANALYTICS: AnalyticsClient = AnalyticsClient::new(
        Principal::from_text("YOUR-ANALYTICS-CANISTER-ID").unwrap()
    );
}

Find your analytics canister ID on the IC Metrics dashboard after creating an analytics canister for your Dapp.

2. Record a metric

All recording is fire-and-forget — AnalyticsClient::record_metric enqueues a one-way inter-canister call that does not block your canister’s execution.

ANALYTICS.with(|a| {
    a.record_metric(Metric {
        key:   "user_signups".to_string(),
        name:  "User Sign-ups".to_string(),
        value: MetricValue::Counter(1),
    })
    .expect("record_metric failed");
});

Metric types

Variant	Payload	Behaviour
MetricValue::Counter	Delta (positive or negative)	Accumulated running total
MetricValue::Gauge	Absolute value	Overwritten on each call
MetricValue::Histogram	(x, y) data point	Appended with each call
MetricValue::TimeSeries	Measured value	Histogram with IC timestamp (ms) as x, set automatically
MetricValue::Log	Text entry	Appended with canister timestamp

The key field is the stable identifier for a metric. The name field is the human-readable label shown in the dashboard. The key is fixed on first write — changing the metric type for an existing key will trap.

Examples

Counter

Increment a running total. Pass a negative delta to decrement.

a.record_metric(Metric {
    key:   "transfers_total".to_string(),
    name:  "Total Transfers".to_string(),
    value: MetricValue::Counter(1),
})?;

Gauge

Store the latest absolute value. Useful for memory usage, queue depth, etc.

a.record_metric(Metric {
    key:   "heap_usage_mb".to_string(),
    name:  "Heap Usage (MB)".to_string(),
    value: MetricValue::Gauge(heap_mb),
})?;

TimeSeries

Append a data point timestamped automatically with the current IC time (milliseconds). Use this when x should always be the current time.

a.record_metric(Metric {
    key:   "response_latency_ms".to_string(),
    name:  "Response Latency (ms)".to_string(),
    value: MetricValue::TimeSeries(42.5),
})?;

Histogram

Append an (x, y) data point with explicit values. Useful when x is something other than the current time (e.g. request size vs latency).

a.record_metric(Metric {
    key:   "size_vs_latency".to_string(),
    name:  "Size vs Latency".to_string(),
    value: MetricValue::Histogram { x: request_bytes as f64, y: latency_ms },
})?;

Log

Append a timestamped text entry. Useful for events, errors, or audit trails.

a.record_metric(Metric {
    key:   "canister_events".to_string(),
    name:  "Canister Events".to_string(),
    value: MetricValue::Log("[INFO] Upgrade completed to v2.1.0".to_string()),
})?;

Structs

AnalyticsClient

Client for recording metrics to an IC Metrics analytics canister.

HistogramPage

A page of histogram data points returned by get_histogram_page.

LogPage

A page of log entries returned by get_log_page.

Metric

An incoming metric record.

TransformerInfo

Metadata returned when listing or fetching a transformer definition.

Enums

MetricValue

The value carried by an incoming metric record. Determines how the metric is stored and aggregated.

StoredMetric

The aggregated metric as stored in the canister, keyed by key.

TransformerOutput

The result produced by running a transformer script.