Struct TimerMetrics 

pub struct TimerMetrics;

TimerMetrics

Volatile counters for timers 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 scheduling events have occurred for a given timer key?

   • Use [increment] when you explicitly want to count scheduling operations.

Note that this type does not count executions/ticks of interval timers. Execution counts should be tracked separately (e.g., via perf records or a dedicated “timer runs” metric), 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 scheduling 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 been scheduled.

This uses saturating arithmetic to avoid overflow.

pub fn snapshot() -> TimerMetricsSnapshot

Snapshot all timer scheduling 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.