Struct TimerMetrics 

pub struct TimerMetrics;

TimerMetrics

Volatile counters for timer executions keyed by (mode, delay_ms, label).

What this measures

TimerMetrics is intended to answer two related questions:

1. Which timers have been scheduled?

   • Use [ensure] at scheduling time to guarantee the timer appears in snapshots, even if it has not fired yet (e.g., newly-created interval timers).

2. How many times has a given timer fired?

   • Use [increment] when a timer fires (one-shot completion or interval tick).

Note that this type does count executions/ticks of interval timers. Scheduling counts are tracked separately (e.g., via SystemMetricKind::TimerScheduled), and instruction costs are tracked via perf counters, because scheduling and execution are different signals.

Cardinality and labels

Labels are used as metric keys. Keep labels stable and low-cardinality (avoid embedding principals, IDs, or other high-variance values).

Thread safety / runtime model

This uses thread_local! storage. On the IC, this is the standard way to maintain mutable global state without unsafe.

Implementations

impl TimerMetrics

pub fn ensure(mode: TimerMode, delay: Duration, label: &str)

Ensure a timer key exists in the metrics table with an initial count of 0.

This is used at schedule time to make timers visible in snapshots before they have fired (particularly important for interval timers).

Idempotent: calling ensure repeatedly for the same key does not change the count.

pub fn increment(mode: TimerMode, delay: Duration, label: &str)

Increment the execution counter for a timer key.

Use this when you want to count how many times a given timer (identified by (mode, delay_ms, label)) has fired.

This uses saturating arithmetic to avoid overflow.

pub fn snapshot() -> TimerMetricsSnapshot

Snapshot all timer execution metrics.

Returns the current contents of the metrics table as a vector of entries. Callers may sort or page the results as needed at the API layer.