Add native histogram support (#304)

* Add native histogram support

Add native-only histograms and histograms that expose both classic and native buckets. Encode native sparse bucket spans and deltas through the Prometheus protobuf encoder while keeping text and OpenMetrics protobuf behavior on the classic representation when available.

Signed-off-by: John Howard <john.howard@solo.io>

* Address comments

Signed-off-by: John Howard <john.howard@solo.io>

* Revert version/notes

Signed-off-by: John Howard <john.howard@solo.io>

* Address comments around tests

Signed-off-by: John Howard <john.howard@solo.io>

* Lint

Signed-off-by: John Howard <john.howard@solo.io>

---------

Signed-off-by: John Howard <john.howard@solo.io>

Author: howardjohn

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unrelreased]
+
+### Added
+
+- Added native histogram support, including native-only histograms and
+  histograms with both classic and native buckets.
+
 ## [0.25.0]
 
 ### Added

Cargo.toml

@@ -67,6 +67,10 @@ harness = false
 name = "family"
 harness = false
 
+[[bench]]
+name = "histogram"
+harness = false
+
 [[bench]]
 name = "text"
 path = "benches/encoding/text.rs"

benches/histogram.rs

@@ -0,0 +1,42 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use prometheus_client::metrics::histogram::{
+    exponential_buckets, Histogram, NativeHistogramConfig,
+};
+
+const OBSERVATION: f64 = 64.0;
+
+pub fn histogram(c: &mut Criterion) {
+    let mut group = c.benchmark_group("observe");
+
+    group.bench_function("histogram", |b| {
+        let histogram = Histogram::new(exponential_buckets(1.0, 2.0, 10));
+
+        b.iter(|| {
+            histogram.observe(black_box(OBSERVATION));
+        })
+    });
+
+    group.bench_function("native histogram", |b| {
+        let histogram = Histogram::new_native(NativeHistogramConfig::with_schema(0));
+
+        b.iter(|| {
+            histogram.observe(black_box(OBSERVATION));
+        })
+    });
+
+    group.bench_function("classic and native histogram", |b| {
+        let histogram = Histogram::new_classic_and_native(
+            exponential_buckets(1.0, 2.0, 10),
+            NativeHistogramConfig::with_schema(0),
+        );
+
+        b.iter(|| {
+            histogram.observe(black_box(OBSERVATION));
+        })
+    });
+
+    group.finish();
+}
+
+criterion_group!(benches, histogram);
+criterion_main!(benches);

src/encoding.rs

@@ -33,6 +33,32 @@ pub mod text;
 #[deprecated(note = "Use openmetrics_protobuf instead.")]
 pub use openmetrics_protobuf as protobuf;
 
+/// Native histogram fields shared by encoders.
+#[derive(Clone, Copy, Debug)]
+pub struct NativeHistogram<'a> {
+    /// Native histogram schema.
+    pub schema: i32,
+    /// Breadth of the zero bucket.
+    pub zero_threshold: f64,
+    /// Count in the zero bucket.
+    pub zero_count: u64,
+    /// Negative sparse buckets.
+    pub negative: NativeHistogramBuckets<'a>,
+    /// Positive sparse buckets.
+    pub positive: NativeHistogramBuckets<'a>,
+    /// Native histogram creation timestamp.
+    pub created: Option<SystemTime>,
+}
+
+/// Sparse bucket span and delta encoding for one side of a native histogram.
+#[derive(Clone, Copy, Debug)]
+pub struct NativeHistogramBuckets<'a> {
+    /// Bucket spans.
+    pub spans: &'a [(i32, u32)],
+    /// Bucket count deltas.
+    pub deltas: &'a [i64],
+}
+
 macro_rules! for_both_mut {
     ($self:expr, $inner:ident, $pattern:pat, $fn:expr) => {
         match &mut $self.0 {
@@ -237,6 +263,26 @@ impl MetricEncoder<'_> {
         )
     }
 
+    /// Encode a histogram that may have native buckets.
+    ///
+    /// Encoders without native histogram support encode the classic buckets when
+    /// present and reject native-only histograms.
+    pub fn encode_histogram_with_native<S: EncodeLabelSet>(
+        &mut self,
+        sum: f64,
+        count: u64,
+        buckets: &[(f64, u64)],
+        exemplars: Option<&HashMap<usize, Exemplar<S, f64>>>,
+        native: NativeHistogram<'_>,
+    ) -> Result<(), std::fmt::Error> {
+        for_both_mut!(
+            self,
+            MetricEncoderInner,
+            e,
+            e.encode_histogram_with_native(sum, count, buckets, exemplars, native)
+        )
+    }
+
     /// Encode a metric family.
     pub fn encode_family<'s, S: EncodeLabelSet>(
         &'s mut self,

src/encoding/openmetrics_protobuf.rs

@@ -36,7 +36,9 @@ use crate::metrics::MetricType;
 use crate::registry::{Registry, Unit};
 use crate::{metrics::exemplar::Exemplar, registry::Prefix};
 
-use super::{EncodeCounterValue, EncodeExemplarValue, EncodeGaugeValue, EncodeLabelSet};
+use super::{
+    EncodeCounterValue, EncodeExemplarValue, EncodeGaugeValue, EncodeLabelSet, NativeHistogram,
+};
 
 /// Encode the metrics registered with the provided [`Registry`] into MetricSet
 /// using the OpenMetrics protobuf format.
@@ -288,6 +290,21 @@ impl MetricEncoder<'_> {
 
         Ok(())
     }
+
+    pub fn encode_histogram_with_native<S: EncodeLabelSet>(
+        &mut self,
+        sum: f64,
+        count: u64,
+        buckets: &[(f64, u64)],
+        exemplars: Option<&HashMap<usize, Exemplar<S, f64>>>,
+        _native: NativeHistogram<'_>,
+    ) -> Result<(), std::fmt::Error> {
+        if buckets.is_empty() {
+            return Err(std::fmt::Error);
+        }
+
+        self.encode_histogram(sum, count, buckets, exemplars)
+    }
 }
 
 impl<S: EncodeLabelSet, V: EncodeExemplarValue> TryFrom<&Exemplar<S, V>>
@@ -454,7 +471,7 @@ mod tests {
     use crate::metrics::exemplar::{CounterWithExemplar, HistogramWithExemplars};
     use crate::metrics::family::Family;
     use crate::metrics::gauge::Gauge;
-    use crate::metrics::histogram::{exponential_buckets, Histogram};
+    use crate::metrics::histogram::{exponential_buckets, Histogram, NativeHistogramConfig};
     use crate::metrics::info::Info;
     use crate::registry::Unit;
     use std::borrow::Cow;
@@ -819,6 +836,16 @@ mod tests {
         }
     }
 
+    #[test]
+    fn encode_native_only_histogram_errors() {
+        let mut registry = Registry::default();
+        let histogram = Histogram::new_native(NativeHistogramConfig::with_schema(0));
+        registry.register("my_histogram", "My histogram", histogram.clone());
+        histogram.observe(1.0);
+
+        assert!(encode(&registry).is_err());
+    }
+
     #[test]
     fn encode_histogram_with_exemplars() {
         let now = SystemTime::now();