From 6e49728d62ebb42b94fa6e4099b2e4ef22604d9d Mon Sep 17 00:00:00 2001 From: Anthony Ramine Date: Wed, 18 Nov 2026 10:07:06 +0100 Subject: [PATCH 1/2] refactor(metrics): Share classic histogram bounds `ClassicHistogramBounds` now owns fixed-bucket normalization, bucket lookup, and snapshot construction. `Histogram` retains its existing mutex-protected sum, count, and bucket counters while using the shared immutable bounds representation. This separates classic bucket semantics from their synchronization model so other histogram storage strategies can reuse them without changing rendering or public behavior. --- foundations-metrics/src/metrics/histogram.rs | 80 +++++++++++++++----- 1 file changed, 63 insertions(+), 17 deletions(-) diff --git a/foundations-metrics/src/metrics/histogram.rs b/foundations-metrics/src/metrics/histogram.rs index ccaed49d..d6475182 100644 --- a/foundations-metrics/src/metrics/histogram.rs +++ b/foundations-metrics/src/metrics/histogram.rs @@ -35,9 +35,63 @@ pub struct Histogram { #[derive(Debug)] struct HistogramState { + bounds: ClassicHistogramBounds, sum: f64, count: u64, - buckets: Vec<(f64, u64)>, + buckets: Box<[u64]>, +} + +#[derive(Debug)] +pub(super) struct ClassicHistogramBounds { + upper_bounds: Box<[f64]>, +} + +impl ClassicHistogramBounds { + pub(super) fn new(bounds: impl IntoIterator) -> Self { + let mut upper_bounds: Vec<_> = bounds.into_iter().collect(); + upper_bounds.push(f64::INFINITY); + upper_bounds.sort_by(f64::total_cmp); + + Self { + upper_bounds: upper_bounds.into(), + } + } + + pub(super) fn len(&self) -> usize { + self.upper_bounds.len() + } + + pub(super) fn bucket_index(&self, value: f64) -> Option { + if value.is_nan() { + return None; + } + + let index = self + .upper_bounds + .partition_point(|upper_bound| *upper_bound < value); + (index < self.len()).then_some(index) + } + + pub(super) fn snapshot( + &self, + sum: f64, + count: u64, + bucket_counts: &[u64], + ) -> HistogramSnapshot { + debug_assert_eq!(bucket_counts.len(), self.len()); + let buckets: Vec<_> = self + .upper_bounds + .iter() + .copied() + .zip(bucket_counts.iter().copied()) + .collect(); + + HistogramSnapshot { + sum, + count, + buckets, + } + } } /// A point-in-time view of a histogram's sum, count, and buckets. @@ -54,12 +108,12 @@ impl Histogram { /// 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 buckets: Vec<_> = bounds.into_iter().map(|bound| (bound, 0)).collect(); - buckets.push((f64::INFINITY, 0)); - buckets.sort_by(|(a, _), (b, _)| a.total_cmp(b)); + let bounds = ClassicHistogramBounds::new(bounds); + let buckets = vec![0; bounds.len()].into_boxed_slice(); Self { state: Arc::new(Mutex::new(HistogramState { + bounds, sum: 0.0, count: 0, buckets, @@ -77,15 +131,9 @@ impl Histogram { state.sum += value; state.count = state.count.wrapping_add(1); - if value.is_nan() { - return None; - } - - let index = state - .buckets - .partition_point(|(upper_bound, _)| *upper_bound < value); + let index = state.bounds.bucket_index(value)?; - if let Some((_, count)) = state.buckets.get_mut(index) { + if let Some(count) = state.buckets.get_mut(index) { *count = count.wrapping_add(1); Some(index) } else { @@ -97,11 +145,9 @@ impl Histogram { /// buckets. pub fn snapshot(&self) -> HistogramSnapshot { let state = self.state.lock(); - HistogramSnapshot { - sum: state.sum, - count: state.count, - buckets: state.buckets.clone(), - } + state + .bounds + .snapshot(state.sum, state.count, &state.buckets) } } From 6c801a9f2415d11c7f6fcecc9512918bb9e11a94 Mon Sep 17 00:00:00 2001 From: Anthony Ramine Date: Wed, 18 Nov 2026 10:07:18 +0100 Subject: [PATCH 2/2] feat(metrics): Add thread-local histograms `ThreadLocalHistogram` keeps independent per-thread fixed-bucket state and aggregates it into a standard classic histogram during collection. Thread slots are reused after threads exit, while accumulated values remain visible. The `thread_local` crate provides runtime-owned storage, and boxed shard state avoids false sharing between threads. `HistogramBuilder` constructs the metric, making it compatible with metric macros and families. The implementation reuses `ClassicHistogramBounds`, `HistogramSnapshot`, and the existing histogram encoder. The type is available from `foundations-metrics` and its backend-gated `foundations` facade. Exemplar support remains deferred because sharing exemplar storage across thread-local values requires additional ownership and conflict semantics. --- foundations-metrics/src/lib.rs | 2 +- foundations-metrics/src/metrics/mod.rs | 2 + .../src/metrics/tls_histogram.rs | 264 ++++++++++++++++++ foundations/src/telemetry/metrics/mod.rs | 4 +- foundations/tests/thread_local_histogram.rs | 33 +++ 5 files changed, 302 insertions(+), 3 deletions(-) create mode 100644 foundations-metrics/src/metrics/tls_histogram.rs create mode 100644 foundations/tests/thread_local_histogram.rs diff --git a/foundations-metrics/src/lib.rs b/foundations-metrics/src/lib.rs index 5692e00c..d8d566f0 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, + ThreadLocalCounter, ThreadLocalHistogram, TimeHistogram, WithExemplar, }; pub use registered::NamedMetric; pub use validation::{NAME_REQUIREMENT, is_valid_name}; diff --git a/foundations-metrics/src/metrics/mod.rs b/foundations-metrics/src/metrics/mod.rs index d7d20658..30400425 100644 --- a/foundations-metrics/src/metrics/mod.rs +++ b/foundations-metrics/src/metrics/mod.rs @@ -42,6 +42,7 @@ mod histogram; mod low_cardinality; mod native_histogram; mod tls_counter; +mod tls_histogram; pub use counter::{Counter, CounterAtomic}; pub use exemplar::WithExemplar; @@ -53,6 +54,7 @@ pub use histogram::{ pub use low_cardinality::{LowCardinalityFamily, LowCardinalityLabel}; pub use native_histogram::{NativeHistogram, NativeHistogramBuilder, NativeTimeHistogram}; pub use tls_counter::ThreadLocalCounter; +pub use tls_histogram::ThreadLocalHistogram; fn update_f64(atomic: &AtomicU64, f: impl Fn(f64) -> f64) -> f64 { let mut old_bits = atomic.load(Ordering::Relaxed); diff --git a/foundations-metrics/src/metrics/tls_histogram.rs b/foundations-metrics/src/metrics/tls_histogram.rs new file mode 100644 index 00000000..be1ab1d4 --- /dev/null +++ b/foundations-metrics/src/metrics/tls_histogram.rs @@ -0,0 +1,264 @@ +use std::fmt; +use std::sync::Arc; +use std::sync::atomic::{AtomicU64, Ordering}; + +use thread_local::ThreadLocal; + +use crate::{EncodeMetricValue, MetricFamily}; + +use super::MetricConstructor; +use super::histogram::{ + ClassicHistogramBounds, HistogramBuilder, HistogramSnapshot, encode_snapshot, +}; + +/// A classic fixed-bucket histogram with thread-local storage. +/// +/// Each thread records independently using relaxed atomics stored in a +/// [`ThreadLocal`]. Collection iterates over the thread-local values and emits +/// one ordinary classic Prometheus histogram. Values belonging to exited +/// threads remain part of the aggregate, and their storage can be reused by +/// later threads. +/// +/// # Examples +/// +/// ``` +/// use foundations_metrics::{EncodeMetric, NamedMetric, ThreadLocalHistogram}; +/// +/// // ThreadLocalHistogram is an ordinary runtime-created value. +/// let histogram = ThreadLocalHistogram::new([0.1, 1.0, 10.0]); +/// +/// std::thread::scope(|scope| { +/// for value in [0.5, 2.0] { +/// let histogram = histogram.clone(); +/// scope.spawn(move || histogram.observe(value)); +/// } +/// }); +/// +/// let registered = NamedMetric::new( +/// "request_duration_seconds", +/// "Request duration.", +/// histogram, +/// ); +/// assert_eq!(registered.encode()[0].name.as_deref(), Some("request_duration_seconds")); +/// ``` +#[derive(Clone)] +pub struct ThreadLocalHistogram { + state: Arc, +} + +struct ThreadLocalHistogramState { + bounds: ClassicHistogramBounds, + shards: ThreadLocal>, +} + +struct ShardState { + sum: AtomicU64, + count: AtomicU64, + buckets: Box<[AtomicU64]>, +} + +impl ThreadLocalHistogram { + /// Creates a thread-local 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 { + Self { + state: Arc::new(ThreadLocalHistogramState { + bounds: ClassicHistogramBounds::new(bounds), + shards: ThreadLocal::new(), + }), + } + } + + /// Records an observed value in the current thread's histogram storage. + #[inline] + pub fn observe(&self, value: f64) { + let shard = self.state.shards.get_or(|| { + Box::new(ShardState { + sum: AtomicU64::new(0.0_f64.to_bits()), + count: AtomicU64::new(0), + buckets: (0..self.state.bounds.len()) + .map(|_| AtomicU64::new(0)) + .collect(), + }) + }); + + let sum = f64::from_bits(shard.sum.load(Ordering::Relaxed)); + shard.sum.store((sum + value).to_bits(), Ordering::Relaxed); + let count = shard.count.load(Ordering::Relaxed); + shard.count.store(count.wrapping_add(1), Ordering::Relaxed); + + let Some(index) = self.state.bounds.bucket_index(value) else { + return; + }; + if let Some(bucket) = shard.buckets.get(index) { + let count = bucket.load(Ordering::Relaxed); + bucket.store(count.wrapping_add(1), Ordering::Relaxed); + } + } + + /// Returns a point-in-time aggregate snapshot of all thread-local values. + pub fn snapshot(&self) -> HistogramSnapshot { + let mut sum = 0.0; + let mut count = 0_u64; + let mut buckets = vec![0_u64; self.state.bounds.len()]; + + for shard in self.state.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)); + } + } + + self.state.bounds.snapshot(sum, count, &buckets) + } +} + +impl fmt::Debug for ThreadLocalHistogram { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let snapshot = self.snapshot(); + f.debug_struct("ThreadLocalHistogram") + .field("sum", &snapshot.sum()) + .field("count", &snapshot.count()) + .field("buckets", &snapshot.buckets()) + .finish() + } +} + +impl EncodeMetricValue for ThreadLocalHistogram { + fn encode_metric_value(&self) -> Vec { + encode_snapshot(self.snapshot()) + } +} + +impl MetricConstructor for HistogramBuilder { + fn new_metric(&self) -> ThreadLocalHistogram { + ThreadLocalHistogram::new(self.buckets.iter().copied()) + } +} + +#[cfg(test)] +mod tests { + use std::sync::{Arc, Barrier}; + + use foundations_metrics_registry::proto::MetricType; + + use super::*; + use crate::{EncodeMetric, NamedMetric}; + + #[test] + fn clones_share_storage() { + let histogram = ThreadLocalHistogram::new([1.0]); + let clone = histogram.clone(); + + histogram.observe(0.25); + clone.observe(0.75); + + assert_eq!(histogram.snapshot().count(), 2); + assert_eq!( + histogram.snapshot().buckets(), + &[(1.0, 2), (f64::INFINITY, 0)] + ); + } + + #[test] + fn aggregates_values_from_multiple_threads() { + let histogram = ThreadLocalHistogram::new([1.0, 2.0]); + let barrier = Arc::new(Barrier::new(5)); + let threads: Vec<_> = (0..4) + .map(|_| { + let histogram = histogram.clone(); + let barrier = Arc::clone(&barrier); + std::thread::spawn(move || { + barrier.wait(); + for _ in 0..1_000 { + histogram.observe(1.5); + } + barrier.wait(); + }) + }) + .collect(); + + barrier.wait(); + barrier.wait(); + for thread in threads { + thread.join().expect("histogram 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 = ThreadLocalHistogram::new([2.0, 1.0]); + + for value in [0.5, 1.0, 1.5, 2.0, 3.0, f64::NAN] { + histogram.observe(value); + } + + 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 histogram_builder_constructs_thread_local_histograms() { + let histogram: ThreadLocalHistogram = HistogramBuilder { + buckets: &[0.5, 1.0], + } + .new_metric(); + + histogram.observe(0.75); + assert_eq!(histogram.snapshot().buckets()[1], (1.0, 1)); + } + + #[test] + fn encodes_one_classic_histogram_with_cumulative_buckets() { + let histogram = ThreadLocalHistogram::new([1.0, 2.0]); + histogram.observe(0.5); + histogram.observe(1.5); + histogram.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..5f094dbd 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, ThreadLocalCounter, + ThreadLocalHistogram, TimeHistogram, WithExemplar, }; // Everything needed to define, register, and label a custom metric. The diff --git a/foundations/tests/thread_local_histogram.rs b/foundations/tests/thread_local_histogram.rs new file mode 100644 index 00000000..20f16f53 --- /dev/null +++ b/foundations/tests/thread_local_histogram.rs @@ -0,0 +1,33 @@ +#![cfg(feature = "foundations-metrics-backend")] + +use foundations::telemetry::metrics::{HistogramBuilder, ThreadLocalHistogram, metrics}; +use foundations::telemetry::settings::{MetricsSettings, ServiceNameFormat}; + +mod common; +use common::collect_text; + +#[metrics] +mod generated { + /// Request duration. + #[ctor = HistogramBuilder { + buckets: &[1.0, 2.0], + }] + pub fn request_duration_seconds() -> ThreadLocalHistogram; +} + +#[test] +fn a_thread_local_histogram_works_with_the_metrics_macro() { + let histogram = generated::request_duration_seconds(); + histogram.observe(0.5); + histogram.observe(1.5); + + let text = collect_text(&MetricsSettings { + service_name_format: ServiceNameFormat::MetricPrefix, + report_optional: false, + }); + + assert!( + text.contains("undefined_generated_request_duration_seconds_count 2"), + "collected output was: {text}" + ); +}