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/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) } } 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}" + ); +}