Initial native histogram support

Author: howardjohn

src/encoding.rs

@@ -198,6 +198,37 @@ impl MetricEncoder<'_> {
         )
     }
 
+    /// Encode a native histogram.
+    pub fn encode_native_histogram(
+        &mut self,
+        sum: f64,
+        count: u64,
+        schema: i32,
+        zero_threshold: f64,
+        zero_count: u64,
+        negative_spans: &[(i32, u32)],
+        negative_deltas: &[i64],
+        positive_spans: &[(i32, u32)],
+        positive_deltas: &[i64],
+    ) -> Result<(), std::fmt::Error> {
+        for_both_mut!(
+            self,
+            MetricEncoderInner,
+            e,
+            e.encode_native_histogram(
+                sum,
+                count,
+                schema,
+                zero_threshold,
+                zero_count,
+                negative_spans,
+                negative_deltas,
+                positive_spans,
+                positive_deltas,
+            )
+        )
+    }
+
     /// Encode a metric family.
     pub fn encode_family<'s, S: EncodeLabelSet>(
         &'s mut self,

src/encoding/proto/openmetrics_data_model.proto

@@ -140,6 +140,29 @@ message HistogramValue {
   // Optional.
   repeated Bucket buckets = 5;
 
+  // Everything below here is for native histograms.
+  // Schema for standard exponential buckets (currently -4..8).
+  sint32 schema = 6;
+
+  // Breadth of the zero bucket.
+  double zero_threshold = 7;
+
+  // Count in zero bucket.
+  uint64 zero_count = 8;
+
+  // Negative buckets for the native histogram.
+  repeated BucketSpan negative_span = 9;
+  repeated sint64 negative_delta = 10;
+  repeated double negative_count = 11;
+
+  // Positive buckets for the native histogram.
+  repeated BucketSpan positive_span = 12;
+  repeated sint64 positive_delta = 13;
+  repeated double positive_count = 14;
+
+  // Native histogram exemplars. Must carry a timestamp.
+  repeated Exemplar exemplars = 15;
+
   // Bucket is the number of values for a bucket in the histogram
   // with an optional exemplar.
   message Bucket {  
@@ -152,6 +175,14 @@ message HistogramValue {
     // Optional.
     Exemplar exemplar = 3;
   }
+
+  // Consecutive run of sparse bucket indexes.
+  message BucketSpan {
+    // Gap to previous span, or starting point for first span.
+    sint32 offset = 1;
+    // Number of consecutive buckets in the span.
+    uint32 length = 2;
+  }
 }
 
 message Exemplar {

src/encoding/protobuf.rs

@@ -288,6 +288,68 @@ impl MetricEncoder<'_> {
 
         Ok(())
     }
+
+    pub fn encode_native_histogram(
+        &mut self,
+        sum: f64,
+        count: u64,
+        schema: i32,
+        zero_threshold: f64,
+        zero_count: u64,
+        negative_spans: &[(i32, u32)],
+        negative_deltas: &[i64],
+        positive_spans: &[(i32, u32)],
+        positive_deltas: &[i64],
+    ) -> Result<(), std::fmt::Error> {
+        let negative_span = negative_spans
+            .iter()
+            .map(
+                |(offset, length)| openmetrics_data_model::histogram_value::BucketSpan {
+                    offset: *offset,
+                    length: *length,
+                },
+            )
+            .collect();
+
+        let positive_span = positive_spans
+            .iter()
+            .map(
+                |(offset, length)| openmetrics_data_model::histogram_value::BucketSpan {
+                    offset: *offset,
+                    length: *length,
+                },
+            )
+            .collect();
+
+        self.family.push(openmetrics_data_model::Metric {
+            labels: self.labels.clone(),
+            metric_points: vec![openmetrics_data_model::MetricPoint {
+                value: Some(openmetrics_data_model::metric_point::Value::HistogramValue(
+                    openmetrics_data_model::HistogramValue {
+                        count,
+                        created: None,
+                        buckets: Vec::new(),
+                        sum: Some(openmetrics_data_model::histogram_value::Sum::DoubleValue(
+                            sum,
+                        )),
+                        schema,
+                        zero_threshold,
+                        zero_count,
+                        negative_span,
+                        negative_delta: negative_deltas.to_vec(),
+                        negative_count: Vec::new(),
+                        positive_span,
+                        positive_delta: positive_deltas.to_vec(),
+                        positive_count: Vec::new(),
+                        exemplars: Vec::new(),
+                    },
+                )),
+                ..Default::default()
+            }],
+        });
+
+        Ok(())
+    }
 }
 
 impl<S: EncodeLabelSet, V: EncodeExemplarValue> TryFrom<&Exemplar<S, V>>

src/encoding/text.rs

@@ -444,6 +444,23 @@ impl MetricEncoder<'_> {
         Ok(())
     }
 
+    pub fn encode_native_histogram(
+        &mut self,
+        _sum: f64,
+        _count: u64,
+        _schema: i32,
+        _zero_threshold: f64,
+        _zero_count: u64,
+        _negative_spans: &[(i32, u32)],
+        _negative_deltas: &[i64],
+        _positive_spans: &[(i32, u32)],
+        _positive_deltas: &[i64],
+    ) -> Result<(), std::fmt::Error> {
+        // Native histogram text exposition is not defined. Treat this as a
+        // no-op to avoid failing an entire scrape with mixed metric families.
+        Ok(())
+    }
+
     /// Encode an exemplar for the given metric.
     fn encode_exemplar<S: EncodeLabelSet, V: EncodeExemplarValue>(
         &mut self,

src/metrics.rs

@@ -6,6 +6,7 @@ pub mod family;
 pub mod gauge;
 pub mod histogram;
 pub mod info;
+pub mod native_histogram;
 
 /// A metric that is aware of its Open Metrics metric type.
 pub trait TypedMetric {