Struct DynamicHistogram 

pub struct DynamicHistogram { /* private fields */ }

Histogram keyed by runtime label sets.

Uses sharded index for key->series lookup and per-series sharded counters for fast updates.

Implementations

impl DynamicHistogram

pub fn new(bounds: &[u64], shard_count: usize) -> Self

Creates a new runtime-labeled histogram with given bucket boundaries.

pub fn with_limits( bounds: &[u64], shard_count: usize, max_series: usize, ) -> Self

Creates a new runtime-labeled histogram 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 with_latency_buckets(shard_count: usize) -> Self

Creates a histogram with default latency buckets (in microseconds).

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

Resolve a reusable series handle for labels.

Preferred for hot paths when labels come from a finite active set.

pub fn record(&self, labels: &[(&str, &str)], value: u64)

Record a value for the series identified by labels.

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

Get cumulative bucket counts for the series identified by labels.

pub fn sum(&self, labels: &[(&str, &str)]) -> u64

Get sum for the series identified by labels.

pub fn count(&self, labels: &[(&str, &str)]) -> u64

Get count for the series identified by labels.

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

Returns a snapshot of all label-set with their histogram data.

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 DynamicHistogramSeries handle to them.

Returns the number of series evicted.

Trait Implementations

impl ClickHouseExport for DynamicHistogram

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

impl DogStatsDExport for DynamicHistogram

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 DynamicHistogram

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

impl PrometheusExport for DynamicHistogram

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

Export this metric to the output string.