From be3de2fcb857940c1e8ae2b0ddc1a5ad1ed1e334 Mon Sep 17 00:00:00 2001 From: Anthony Ramine Date: Fri, 13 Nov 2026 11:36:01 +0100 Subject: [PATCH] feat(metrics): Add explicitly sharded histograms `SplitHistogram` collects explicitly registered `SplitHistogramShard` handles into a standard classic histogram while observations use per-shard relaxed atomics. The parent retains shard ownership, and cloned shard handles share their underlying counters. The implementation reuses `HistogramSnapshot` and the existing histogram encoder, preserving standard text and protobuf rendering. Caller-managed thread-local storage is documented without adding TLS policy to the metrics backend. Both types are available from `foundations-metrics` and its backend-gated `foundations` facade. Exemplar support remains deferred because sharing exemplar storage across explicit shards requires additional ownership and conflict semantics. --- foundations-metrics/src/lib.rs | 2 +- foundations-metrics/src/metrics/histogram.rs | 8 + foundations-metrics/src/metrics/mod.rs | 2 + .../src/metrics/split_histogram.rs | 268 ++++++++++++++++++ foundations/src/telemetry/metrics/mod.rs | 4 +- 5 files changed, 281 insertions(+), 3 deletions(-) create mode 100644 foundations-metrics/src/metrics/split_histogram.rs diff --git a/foundations-metrics/src/lib.rs b/foundations-metrics/src/lib.rs index 5692e00c..fc4872c2 100644 --- a/foundations-metrics/src/lib.rs +++ b/foundations-metrics/src/lib.rs @@ -38,7 +38,7 @@ pub use metrics::{ Counter, CounterAtomic, Family, FamilyMetricGuard, Gauge, GaugeAtomic, GaugeGuard, Histogram, HistogramBuilder, HistogramSnapshot, HistogramTimer, LowCardinalityFamily, LowCardinalityLabel, MetricConstructor, NativeHistogram, NativeHistogramBuilder, NativeTimeHistogram, RangeGauge, - ThreadLocalCounter, TimeHistogram, WithExemplar, + SplitHistogram, SplitHistogramShard, ThreadLocalCounter, TimeHistogram, WithExemplar, }; pub use registered::NamedMetric; pub use validation::{NAME_REQUIREMENT, is_valid_name}; diff --git a/foundations-metrics/src/metrics/histogram.rs b/foundations-metrics/src/metrics/histogram.rs index ccaed49d..bec77885 100644 --- a/foundations-metrics/src/metrics/histogram.rs +++ b/foundations-metrics/src/metrics/histogram.rs @@ -426,6 +426,14 @@ impl TimeHistogram { } impl HistogramSnapshot { + pub(super) fn from_parts(sum: f64, count: u64, buckets: Vec<(f64, u64)>) -> Self { + Self { + sum, + count, + buckets, + } + } + /// Returns the sum of all observations. pub fn sum(&self) -> f64 { self.sum diff --git a/foundations-metrics/src/metrics/mod.rs b/foundations-metrics/src/metrics/mod.rs index d7d20658..dce55bf9 100644 --- a/foundations-metrics/src/metrics/mod.rs +++ b/foundations-metrics/src/metrics/mod.rs @@ -41,6 +41,7 @@ mod gauge; mod histogram; mod low_cardinality; mod native_histogram; +mod split_histogram; mod tls_counter; pub use counter::{Counter, CounterAtomic}; @@ -52,6 +53,7 @@ pub use histogram::{ }; pub use low_cardinality::{LowCardinalityFamily, LowCardinalityLabel}; pub use native_histogram::{NativeHistogram, NativeHistogramBuilder, NativeTimeHistogram}; +pub use split_histogram::{SplitHistogram, SplitHistogramShard}; pub use tls_counter::ThreadLocalCounter; fn update_f64(atomic: &AtomicU64, f: impl Fn(f64) -> f64) -> f64 { diff --git a/foundations-metrics/src/metrics/split_histogram.rs b/foundations-metrics/src/metrics/split_histogram.rs new file mode 100644 index 00000000..6524822d --- /dev/null +++ b/foundations-metrics/src/metrics/split_histogram.rs @@ -0,0 +1,268 @@ +use std::sync::Arc; +use std::sync::atomic::{AtomicU64, Ordering}; + +use parking_lot::RwLock; + +use crate::{EncodeMetricValue, MetricFamily}; + +use super::histogram::{HistogramSnapshot, encode_snapshot}; +use super::update_f64; + +/// A classic fixed-bucket histogram aggregated from explicitly created shards. +/// +/// Each shard records independently using relaxed atomics. Collection sums all +/// shards registered through [`SplitHistogram::shard`] and emits one ordinary +/// classic Prometheus histogram. +/// +/// # Examples +/// +/// ``` +/// use std::sync::LazyLock; +/// +/// use foundations_metrics::{ +/// EncodeMetric, NamedMetric, SplitHistogram, SplitHistogramShard, +/// }; +/// +/// static HISTOGRAM: LazyLock = +/// LazyLock::new(|| SplitHistogram::new([0.1, 1.0, 10.0])); +/// +/// std::thread_local! { +/// static HISTOGRAM_SHARD: SplitHistogramShard = HISTOGRAM.shard(); +/// } +/// +/// HISTOGRAM_SHARD.with(|shard| shard.observe(0.5)); +/// +/// // Register a clone of the collecting metric. The clone shares its shard list. +/// let registered = NamedMetric::new( +/// "request_duration_seconds", +/// "Request duration.", +/// (*HISTOGRAM).clone(), +/// ); +/// assert_eq!(registered.encode()[0].name.as_deref(), Some("request_duration_seconds")); +/// ``` +#[derive(Clone, Debug)] +pub struct SplitHistogram { + state: Arc, +} + +#[derive(Debug)] +struct SplitHistogramState { + bounds: Arc<[f64]>, + shards: RwLock>>, +} + +/// A cloneable handle to one shard of a [`SplitHistogram`]. +/// +/// Create shards with [`SplitHistogram::shard`]. Clones share the same +/// per-shard counters, and the parent histogram retains the shard for its +/// lifetime so observations remain collectable after handles are dropped. +#[derive(Clone, Debug)] +pub struct SplitHistogramShard { + state: Arc, +} + +#[derive(Debug)] +struct ShardState { + bounds: Arc<[f64]>, + sum: AtomicU64, + count: AtomicU64, + buckets: Box<[AtomicU64]>, +} + +impl SplitHistogram { + /// Creates a split histogram with the provided inclusive upper bounds. + /// + /// Bounds may be given in any order; they are sorted ascending. A terminal + /// `f64::INFINITY` bucket is appended automatically. + pub fn new(bounds: impl IntoIterator) -> Self { + let mut bounds: Vec<_> = bounds.into_iter().collect(); + bounds.push(f64::INFINITY); + bounds.sort_by(f64::total_cmp); + + Self { + state: Arc::new(SplitHistogramState { + bounds: bounds.into(), + shards: RwLock::new(Vec::new()), + }), + } + } + + /// Creates and registers a compatible shard with this histogram. + pub fn shard(&self) -> SplitHistogramShard { + let state = Arc::new(ShardState { + bounds: Arc::clone(&self.state.bounds), + sum: AtomicU64::new(0.0_f64.to_bits()), + count: AtomicU64::new(0), + buckets: (0..self.state.bounds.len()) + .map(|_| AtomicU64::new(0)) + .collect(), + }); + + self.state.shards.write().push(Arc::clone(&state)); + SplitHistogramShard { state } + } + + /// Returns a point-in-time aggregate snapshot of all registered shards. + pub fn snapshot(&self) -> HistogramSnapshot { + let shards = self.state.shards.read(); + let mut sum = 0.0; + let mut count = 0_u64; + let mut buckets = vec![0_u64; self.state.bounds.len()]; + + for shard in shards.iter() { + sum += f64::from_bits(shard.sum.load(Ordering::Relaxed)); + count = count.wrapping_add(shard.count.load(Ordering::Relaxed)); + + for (total, shard_count) in buckets.iter_mut().zip(shard.buckets.iter()) { + *total = total.wrapping_add(shard_count.load(Ordering::Relaxed)); + } + } + + HistogramSnapshot::from_parts( + sum, + count, + self.state.bounds.iter().copied().zip(buckets).collect(), + ) + } +} + +impl SplitHistogramShard { + /// Records an observed value in this shard. + #[inline] + pub fn observe(&self, value: f64) { + update_f64(&self.state.sum, |sum| sum + value); + self.state.count.fetch_add(1, Ordering::Relaxed); + + if value.is_nan() { + return; + } + + let index = self + .state + .bounds + .partition_point(|upper_bound| *upper_bound < value); + if let Some(bucket) = self.state.buckets.get(index) { + bucket.fetch_add(1, Ordering::Relaxed); + } + } +} + +impl EncodeMetricValue for SplitHistogram { + fn encode_metric_value(&self) -> Vec { + encode_snapshot(self.snapshot()) + } +} + +#[cfg(test)] +mod tests { + use foundations_metrics_registry::proto::MetricType; + + use super::*; + use crate::{EncodeMetric, NamedMetric}; + + #[test] + fn shard_clones_share_storage() { + let histogram = SplitHistogram::new([1.0]); + let shard = histogram.shard(); + let clone = shard.clone(); + + shard.observe(0.25); + clone.observe(0.75); + drop(shard); + drop(clone); + + let parent_clone = histogram.clone(); + assert_eq!(parent_clone.snapshot().count(), 2); + assert_eq!( + parent_clone.snapshot().buckets(), + &[(1.0, 2), (f64::INFINITY, 0)] + ); + } + + #[test] + fn aggregates_shards_updated_by_multiple_threads() { + let histogram = SplitHistogram::new([1.0, 2.0]); + let shards: Vec<_> = (0..4).map(|_| histogram.shard()).collect(); + let threads: Vec<_> = shards + .into_iter() + .map(|shard| { + std::thread::spawn(move || { + for _ in 0..1_000 { + shard.observe(1.5); + } + }) + }) + .collect(); + + for thread in threads { + thread.join().expect("shard thread should not panic"); + } + + let snapshot = histogram.snapshot(); + assert_eq!(snapshot.count(), 4_000); + assert_eq!(snapshot.sum(), 6_000.0); + assert_eq!( + snapshot.buckets(), + &[(1.0, 0), (2.0, 4_000), (f64::INFINITY, 0)] + ); + } + + #[test] + fn sorts_bounds_and_uses_inclusive_bucket_boundaries() { + let histogram = SplitHistogram::new([2.0, 1.0]); + let first = histogram.shard(); + let second = histogram.shard(); + + for value in [0.5, 1.0, 1.5, 2.0, 3.0] { + first.observe(value); + } + second.observe(f64::NAN); + + let snapshot = histogram.snapshot(); + assert_eq!(snapshot.count(), 6); + assert!(snapshot.sum().is_nan()); + assert_eq!( + snapshot.buckets(), + &[(1.0, 2), (2.0, 2), (f64::INFINITY, 1)] + ); + } + + #[test] + fn encodes_one_classic_histogram_with_cumulative_buckets() { + let histogram = SplitHistogram::new([1.0, 2.0]); + let first = histogram.shard(); + let second = histogram.shard(); + first.observe(0.5); + first.observe(1.5); + second.observe(3.0); + + let families = + NamedMetric::new("request_duration_seconds", "Request duration.", histogram).encode(); + assert_eq!(families.len(), 1); + assert_eq!( + families[0].name.as_deref(), + Some("request_duration_seconds") + ); + assert_eq!(families[0].help.as_deref(), Some("Request duration.")); + assert_eq!(families[0].r#type, Some(MetricType::Histogram as i32)); + + let encoded = families[0].metric[0] + .histogram + .as_ref() + .expect("encoded histogram should be present"); + assert_eq!(encoded.sample_count, Some(3)); + assert_eq!(encoded.sample_sum, Some(5.0)); + assert_eq!( + encoded + .bucket + .iter() + .map(|bucket| (bucket.upper_bound, bucket.cumulative_count)) + .collect::>(), + vec![ + (Some(1.0), Some(1)), + (Some(2.0), Some(2)), + (Some(f64::INFINITY), Some(3)), + ] + ); + } +} diff --git a/foundations/src/telemetry/metrics/mod.rs b/foundations/src/telemetry/metrics/mod.rs index 766c8237..74aeabd4 100644 --- a/foundations/src/telemetry/metrics/mod.rs +++ b/foundations/src/telemetry/metrics/mod.rs @@ -64,8 +64,8 @@ mod backend { pub use foundations_metrics::{ Counter, Family, Gauge, GaugeGuard, Histogram, HistogramBuilder, HistogramTimer, InfoMetric, LowCardinalityFamily, LowCardinalityLabel, MetricConstructor, NativeHistogram, - NativeHistogramBuilder, NativeTimeHistogram, RangeGauge, ThreadLocalCounter, TimeHistogram, - WithExemplar, + NativeHistogramBuilder, NativeTimeHistogram, RangeGauge, SplitHistogram, + SplitHistogramShard, ThreadLocalCounter, TimeHistogram, WithExemplar, }; // Everything needed to define, register, and label a custom metric. The