Struct DynamicGaugeI64 

pub struct DynamicGaugeI64 { /* private fields */ }

Signed integer gauge keyed by runtime label sets.

Unlike DynamicCounter, this exports as a gauge (absolute value) rather than a counter (delta). Use for metrics like “active connections” that go up and down.

Uses sharded atomics internally for fast concurrent updates.

Implementations

impl DynamicGaugeI64

pub fn new(shard_count: usize) -> Self

Creates a new runtime-labeled i64 gauge.

pub fn with_max_series(shard_count: usize, max_series: usize) -> Self

Creates a new runtime-labeled i64 gauge with a series cardinality cap.

When the number of unique label sets approximately reaches max_series, new label sets are redirected into a single overflow series (__ft_overflow=true). The cap is checked via a lock-free atomic counter, so concurrent inserts may briefly overshoot by the number of in-flight writers before the overflow kicks in.

pub fn series(&self, labels: &[(&str, &str)]) -> DynamicGaugeI64Series

Resolve a reusable series handle for labels.

pub fn inc(&self, labels: &[(&str, &str)])

Increments the gauge identified by labels by 1.

pub fn dec(&self, labels: &[(&str, &str)])

Decrements the gauge identified by labels by 1.

pub fn add(&self, labels: &[(&str, &str)], value: i64)

Adds value to the gauge identified by labels (can be negative).

pub fn set(&self, labels: &[(&str, &str)], value: i64)

Sets the gauge identified by labels to an absolute value.

pub fn get(&self, labels: &[(&str, &str)]) -> i64

Gets the current value for the gauge identified by labels.

pub fn sum_all(&self) -> i64

Sums all series.

pub fn snapshot(&self) -> Vec<(DynamicLabelSet, i64)>

Returns a snapshot of all label-set/value pairs.

pub fn cardinality(&self) -> usize

Returns the current number of distinct label sets.

pub fn overflow_count(&self) -> u64

Returns the number of records routed to the overflow bucket.

A non-zero value indicates the cardinality cap was hit and label fidelity is being lost. Use this to alert on cardinality pressure.

pub fn evict_stale(&self, max_staleness: u32) -> usize

Evict series that haven’t been accessed for max_staleness cycles.

Call this after advance_cycle() in your exporter task. Series are marked as evicted (so cached handles see the tombstone), then removed from the index.

Protected series (Arc::strong_count > 1) are never evicted - someone holds a DynamicGaugeI64Series handle to them.

Returns the number of series evicted.

Trait Implementations

impl ClickHouseExport for DynamicGaugeI64

fn export_clickhouse( &self, batch: &mut ClickHouseMetricBatch, name: &str, description: &str, time_unix_nano: u64, )

impl DogStatsDExport for DynamicGaugeI64

fn export_dogstatsd( &self, output: &mut String, name: &str, tags: &[(&str, &str)], )

Export this metric to the output string in DogStatsD format.

impl OtlpExport for DynamicGaugeI64

fn export_otlp( &self, metrics: &mut Vec<Metric>, name: &str, description: &str, time_unix_nano: u64, )

impl PrometheusExport for DynamicGaugeI64

fn export_prometheus(&self, output: &mut String, name: &str, help: &str)

Export this metric to the output string.