Struct DynamicCounterSet 

pub struct DynamicCounterSet { /* private fields */ }

Runtime-label grouped counters.

Use DynamicCounterSet when label values are discovered at runtime and one logical operation updates several related counters for the same label set. Resolve and cache a DynamicCounterSetSeries once per active label set, then use pre-resolved counter indexes on the hot path.

use fast_telemetry::DynamicCounterSet;

let counters = DynamicCounterSet::with_shards(
    4,
    ["requests", "bytes", "errors"],
);
let requests = counters.counter_index("requests").unwrap();
let bytes = counters.counter_index("bytes").unwrap();

let series = counters.get_or_create(&[
    ("org", "eden"),
    ("endpoint", "ingest"),
]);
series.add_index_values(&[(requests, 1), (bytes, 4096)]);

assert_eq!(series.get("requests"), 1);
assert_eq!(series.get("bytes"), 4096);

Implementations

impl DynamicCounterSet

pub fn new<I, S>(counter_names: I) -> Self

where I: IntoIterator<Item = S>, S: AsRef<str>,

Creates a new dynamic grouped counter with a default shard count.

Prefer DynamicCounterSet::with_shards in services that already know the desired shard count.

pub fn with_shards<I, S>(shard_count: usize, counter_names: I) -> Self

where I: IntoIterator<Item = S>, S: AsRef<str>,

Creates a new dynamic grouped counter with shard_count shards.

pub fn with_max_series<I, S>( shard_count: usize, max_series: usize, counter_names: I, ) -> Self

where I: IntoIterator<Item = S>, S: AsRef<str>,

Creates a new dynamic grouped counter 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). A max_series of 0 disables the cap.

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

Resolve a reusable grouped series handle for labels.

pub fn get_or_create(&self, labels: &[(&str, &str)]) -> DynamicCounterSetSeries

Resolve a reusable grouped series handle for labels.

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

Increment one named counter for the series identified by labels.

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

Add value to one named counter for the series identified by labels.

pub fn add_index( &self, labels: &[(&str, &str)], counter_idx: usize, value: isize, )

Add value to one pre-resolved counter index for labels.

pub fn add_values(&self, labels: &[(&str, &str)], updates: &[(&str, isize)])

Add named counter values in one grouped call.

pub fn add_index_values( &self, labels: &[(&str, &str)], updates: &[(usize, isize)], )

Add pre-resolved (counter_idx, value) updates in one grouped call.

pub fn add_all_values(&self, labels: &[(&str, &str)], values: &[isize])

Add one value for every counter in index order.

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

Get one named counter for labels.

pub fn get_index(&self, labels: &[(&str, &str)], counter_idx: usize) -> isize

Get one pre-resolved counter index for labels.

pub fn values(&self, labels: &[(&str, &str)]) -> Vec<isize>

Get all values for labels in counter index order.

pub fn sum_all(&self) -> isize

Sums all counters across all dynamic series.

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

Return a cumulative snapshot of all dynamic label sets.

pub fn snapshot_and_reset(&self) -> Vec<(DynamicLabelSet, Vec<isize>)>

Return a snapshot of all dynamic label sets and reset counters to zero.

Writes that occur concurrently with this method may be attributed to the next snapshot window rather than the current one. No counts are lost.

pub fn sum_and_reset(&self, counter_idx: usize) -> isize

Reset one counter index for all dynamic label sets and return its total.

pub fn visit_series(&self, f: impl FnMut(&str, &[(String, String)], isize))

Iterate all counter values without cloning label sets.

Calls f(counter_name, labels, value) for every counter in every dynamic label set. The callback runs while a shard read lock is held; it must be fast and must not call back into this metric.

pub fn counter_names(&self) -> &[String]

Returns counter names in index order.

pub fn counter_index(&self, counter: &str) -> Option<usize>

Return the index for counter, if it exists.

pub fn cardinality(&self) -> usize

Returns the current number of distinct dynamic label sets.

pub fn overflow_count(&self) -> u64

Returns the number of records routed to the overflow bucket.

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

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

Protected series (Arc::strong_count > 1) are never evicted because a caller still holds a DynamicCounterSetSeries handle.