Pass exemplar timestamp explicitly

bobrik · bobrik · commit 3a9225b19e53 · 2025-08-14T09:15:06.000-07:00
This allows having exemplars without timestamps, which are cheaper. It also
allows amortization of timestamping if multiple measurements share time.

Signed-off-by: Ivan Babrou &lt;github@ivan.computer&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,16 +15,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
    method avoids the risk of runtime deadlocks at the expense of creating an
    owned type. See [PR 244].
 
-- Exemplar timestamps, which are required for `convert_classic_histograms_to_nhcb: true`
-  in Prometheus scraping. See [PR 276].
-
 [PR 244]: https://github.com/prometheus/client_rust/pull/244
 [PR 257]: https://github.com/prometheus/client_rust/pull/257
-[PR 276]: https://github.com/prometheus/client_rust/pull/276
 
 ### Changed
 
 - `EncodeLabelSet::encode()` now accepts a mutable reference to its encoder parameter.
+- Exemplar timestamps, which are required for `convert_classic_histograms_to_nhcb: true`
+  in Prometheus scraping. See [PR 276].
+
+[PR 276]: https://github.com/prometheus/client_rust/pull/276
 
 ## [0.23.1]
 
diff --git a/benches/exemplars.rs b/benches/exemplars.rs
@@ -1,3 +1,5 @@
+use std::time::SystemTime;
+
 use criterion::{criterion_group, criterion_main, Criterion};
 use prometheus_client::metrics::exemplar::HistogramWithExemplars;
 use prometheus_client::metrics::histogram::Histogram;
@@ -19,7 +21,7 @@ pub fn exemplars(c: &mut Criterion) {
         let histogram = HistogramWithExemplars::<Exemplar>::new(BUCKETS.iter().copied());
 
         b.iter(|| {
-            histogram.observe(1.0, None);
+            histogram.observe(1.0, None, None);
         });
     });
 
@@ -28,7 +30,7 @@ pub fn exemplars(c: &mut Criterion) {
         let exemplar = vec![("TraceID".to_owned(), "deadfeed".to_owned())];
 
         b.iter(|| {
-            histogram.observe(1.0, Some(exemplar.clone()));
+            histogram.observe(1.0, Some(exemplar.clone()), Some(SystemTime::now()));
         });
     });
 }
diff --git a/src/encoding/protobuf.rs b/src/encoding/protobuf.rs
@@ -311,7 +311,7 @@ impl<S: EncodeLabelSet, V: EncodeExemplarValue> TryFrom<&Exemplar<S, V>>
 
         Ok(openmetrics_data_model::Exemplar {
             value,
-            timestamp: Some(exemplar.time.into()),
+            timestamp: exemplar.timestamp.map(Into::into),
             label: labels,
         })
     }
@@ -547,15 +547,7 @@ mod tests {
             counter_with_exemplar.clone(),
         );
 
-        counter_with_exemplar.inc_by(1.0, Some(vec![("user_id".to_string(), 42.0)]));
-
-        counter_with_exemplar
-            .inner
-            .write()
-            .exemplar
-            .as_mut()
-            .unwrap()
-            .time = now;
+        counter_with_exemplar.inc_by(1.0, Some(vec![("user_id".to_string(), 42.0)]), None);
 
         let metric_set = encode(&registry).unwrap();
 
@@ -577,7 +569,7 @@ mod tests {
                 let exemplar = value.exemplar.as_ref().unwrap();
                 assert_eq!(1.0, exemplar.value);
 
-                assert_eq!(&now_ts, exemplar.timestamp.as_ref().unwrap());
+                assert!(exemplar.timestamp.is_none());
 
                 let expected_label = {
                     openmetrics_data_model::Label {
@@ -589,6 +581,30 @@ mod tests {
             }
             _ => panic!("wrong value type"),
         }
+
+        counter_with_exemplar.inc_by(1.0, Some(vec![("user_id".to_string(), 99.0)]), Some(now));
+
+        match extract_metric_point_value(&encode(&registry).unwrap()) {
+            openmetrics_data_model::metric_point::Value::CounterValue(value) => {
+                // The counter should be encoded  as `DoubleValue`
+                let expected = openmetrics_data_model::counter_value::Total::DoubleValue(2.0);
+                assert_eq!(Some(expected), value.total);
+
+                let exemplar = value.exemplar.as_ref().unwrap();
+                assert_eq!(1.0, exemplar.value);
+
+                assert_eq!(&now_ts, exemplar.timestamp.as_ref().unwrap());
+
+                let expected_label = {
+                    openmetrics_data_model::Label {
+                        name: "user_id".to_string(),
+                        value: "99.0".to_string(),
+                    }
+                };
+                assert_eq!(vec![expected_label], exemplar.label);
+            }
+            _ => panic!("wrong value type"),
+        }
     }
 
     #[test]
@@ -806,16 +822,8 @@ mod tests {
         let mut registry = Registry::default();
         let histogram = HistogramWithExemplars::new(exponential_buckets(1.0, 2.0, 10));
         registry.register("my_histogram", "My histogram", histogram.clone());
-        histogram.observe(1.0, Some(vec![("user_id".to_string(), 42u64)]));
-
-        histogram
-            .inner
-            .write()
-            .exemplars
-            .get_mut(&0)
-            .as_mut()
-            .unwrap()
-            .time = now;
+
+        histogram.observe(1.0, Some(vec![("user_id".to_string(), 42u64)]), None);
 
         let metric_set = encode(&registry).unwrap();
 
@@ -833,7 +841,7 @@ mod tests {
                 let exemplar = value.buckets.first().unwrap().exemplar.as_ref().unwrap();
                 assert_eq!(1.0, exemplar.value);
 
-                assert_eq!(&now_ts, exemplar.timestamp.as_ref().unwrap());
+                assert!(exemplar.timestamp.is_none());
 
                 let expected_label = {
                     openmetrics_data_model::Label {
@@ -845,6 +853,26 @@ mod tests {
             }
             _ => panic!("wrong value type"),
         }
+
+        histogram.observe(2.0, Some(vec![("user_id".to_string(), 99u64)]), Some(now));
+
+        match extract_metric_point_value(&encode(&registry).unwrap()) {
+            openmetrics_data_model::metric_point::Value::HistogramValue(value) => {
+                let exemplar = value.buckets.get(1).unwrap().exemplar.as_ref().unwrap();
+                assert_eq!(2.0, exemplar.value);
+
+                assert_eq!(&now_ts, exemplar.timestamp.as_ref().unwrap());
+
+                let expected_label = {
+                    openmetrics_data_model::Label {
+                        name: "user_id".to_string(),
+                        value: "99".to_string(),
+                    }
+                };
+                assert_eq!(vec![expected_label], exemplar.label);
+            }
+            _ => panic!("wrong value type"),
+        }
     }
 
     #[test]
diff --git a/src/encoding/text.rs b/src/encoding/text.rs
@@ -460,13 +460,15 @@ impl MetricEncoder<'_> {
             }
             .into(),
         )?;
-        self.writer.write_char(' ')?;
-        exemplar.time.encode(
-            ExemplarValueEncoder {
-                writer: self.writer,
-            }
-            .into(),
-        )?;
+        if let Some(timestamp) = exemplar.timestamp {
+            self.writer.write_char(' ')?;
+            timestamp.encode(
+                ExemplarValueEncoder {
+                    writer: self.writer,
+                }
+                .into(),
+            )?;
+        }
         Ok(())
     }
 
@@ -797,15 +799,22 @@ mod tests {
             counter_with_exemplar.clone(),
         );
 
-        counter_with_exemplar.inc_by(1, Some(vec![("user_id".to_string(), 42)]));
+        counter_with_exemplar.inc_by(1, Some(vec![("user_id".to_string(), 42)]), None);
+
+        let mut encoded = String::new();
+        encode(&mut encoded, &registry).unwrap();
+
+        let expected = "# HELP my_counter_with_exemplar_seconds My counter with exemplar.\n"
+            .to_owned()
+            + "# TYPE my_counter_with_exemplar_seconds counter\n"
+            + "# UNIT my_counter_with_exemplar_seconds seconds\n"
+            + "my_counter_with_exemplar_seconds_total 1 # {user_id=\"42\"} 1.0\n"
+            + "# EOF\n";
+        assert_eq!(expected, encoded);
+
+        parse_with_python_client(encoded);
 
-        counter_with_exemplar
-            .inner
-            .write()
-            .exemplar
-            .as_mut()
-            .unwrap()
-            .time = now;
+        counter_with_exemplar.inc_by(1, Some(vec![("user_id".to_string(), 99)]), Some(now));
 
         let mut encoded = String::new();
         encode(&mut encoded, &registry).unwrap();
@@ -814,7 +823,7 @@ mod tests {
             .to_owned()
             + "# TYPE my_counter_with_exemplar_seconds counter\n"
             + "# UNIT my_counter_with_exemplar_seconds seconds\n"
-            + "my_counter_with_exemplar_seconds_total 1 # {user_id=\"42\"} 1.0 "
+            + "my_counter_with_exemplar_seconds_total 2 # {user_id=\"99\"} 1.0 "
             + dtoa::Buffer::new().format(now.duration_since(UNIX_EPOCH).unwrap().as_secs_f64())
             + "\n"
             + "# EOF\n";
@@ -978,37 +987,30 @@ mod tests {
         let mut registry = Registry::default();
         let histogram = HistogramWithExemplars::new(exponential_buckets(1.0, 2.0, 10));
         registry.register("my_histogram", "My histogram", histogram.clone());
-        histogram.observe(1.0, Some([("user_id".to_string(), 42u64)]));
 
-        histogram
-            .inner
-            .write()
-            .exemplars
-            .get_mut(&0)
-            .as_mut()
-            .unwrap()
-            .time = now;
+        histogram.observe(1.0, Some([("user_id".to_string(), 42u64)]), Some(now));
+        histogram.observe(2.0, Some([("user_id".to_string(), 99u64)]), None);
 
         let mut encoded = String::new();
         encode(&mut encoded, &registry).unwrap();
 
         let expected = "# HELP my_histogram My histogram.\n".to_owned()
             + "# TYPE my_histogram histogram\n"
-            + "my_histogram_sum 1.0\n"
-            + "my_histogram_count 1\n"
+            + "my_histogram_sum 3.0\n"
+            + "my_histogram_count 2\n"
             + "my_histogram_bucket{le=\"1.0\"} 1 # {user_id=\"42\"} 1.0 "
             + dtoa::Buffer::new().format(now.duration_since(UNIX_EPOCH).unwrap().as_secs_f64())
             + "\n"
-            + "my_histogram_bucket{le=\"2.0\"} 1\n"
-            + "my_histogram_bucket{le=\"4.0\"} 1\n"
-            + "my_histogram_bucket{le=\"8.0\"} 1\n"
-            + "my_histogram_bucket{le=\"16.0\"} 1\n"
-            + "my_histogram_bucket{le=\"32.0\"} 1\n"
-            + "my_histogram_bucket{le=\"64.0\"} 1\n"
-            + "my_histogram_bucket{le=\"128.0\"} 1\n"
-            + "my_histogram_bucket{le=\"256.0\"} 1\n"
-            + "my_histogram_bucket{le=\"512.0\"} 1\n"
-            + "my_histogram_bucket{le=\"+Inf\"} 1\n"
+            + "my_histogram_bucket{le=\"2.0\"} 2 # {user_id=\"99\"} 2.0\n"
+            + "my_histogram_bucket{le=\"4.0\"} 2\n"
+            + "my_histogram_bucket{le=\"8.0\"} 2\n"
+            + "my_histogram_bucket{le=\"16.0\"} 2\n"
+            + "my_histogram_bucket{le=\"32.0\"} 2\n"
+            + "my_histogram_bucket{le=\"64.0\"} 2\n"
+            + "my_histogram_bucket{le=\"128.0\"} 2\n"
+            + "my_histogram_bucket{le=\"256.0\"} 2\n"
+            + "my_histogram_bucket{le=\"512.0\"} 2\n"
+            + "my_histogram_bucket{le=\"+Inf\"} 2\n"
             + "# EOF\n";
         assert_eq!(expected, encoded);
 
diff --git a/src/metrics/exemplar.rs b/src/metrics/exemplar.rs
@@ -23,7 +23,7 @@ use std::time::SystemTime;
 pub struct Exemplar<S, V> {
     pub(crate) label_set: S,
     pub(crate) value: V,
-    pub(crate) time: SystemTime,
+    pub(crate) timestamp: Option<SystemTime>,
 }
 
 /////////////////////////////////////////////////////////////////////////////////
@@ -117,13 +117,13 @@ impl<S, N: Clone, A: counter::Atomic<N>> CounterWithExemplar<S, N, A> {
 
     /// Increase the [`CounterWithExemplar`] by `v`, updating the [`Exemplar`]
     /// if a label set is provided, returning the previous value.
-    pub fn inc_by(&self, v: N, label_set: Option<S>) -> N {
+    pub fn inc_by(&self, v: N, label_set: Option<S>, timestamp: Option<SystemTime>) -> N {
         let mut inner = self.inner.write();
 
         inner.exemplar = label_set.map(|label_set| Exemplar {
             label_set,
             value: v.clone(),
-            time: SystemTime::now(),
+            timestamp,
         });
 
         inner.counter.inc_by(v)
@@ -178,7 +178,7 @@ where
 /// # use prometheus_client::metrics::exemplar::HistogramWithExemplars;
 /// # use prometheus_client::metrics::histogram::exponential_buckets;
 /// let histogram = HistogramWithExemplars::new(exponential_buckets(1.0, 2.0, 10));
-/// histogram.observe(4.2, Some(vec![("user_id".to_string(), "42".to_string())]));
+/// histogram.observe(4.2, Some(vec![("user_id".to_string(), "42".to_string())]), None);
 /// ```
 /// You can also use exemplars with families. Just wrap the exemplar in a Family.
 /// ```
@@ -210,6 +210,7 @@ where
 ///         Some(TraceLabel {
 ///             trace_id: "3a2f90c9f80b894f".to_owned(),
 ///         }),
+///         None,
 ///     );
 /// ```
 #[derive(Debug)]
@@ -250,7 +251,7 @@ impl<S> HistogramWithExemplars<S> {
 
     /// Observe the given value, optionally providing a label set and thus
     /// setting the [`Exemplar`] value.
-    pub fn observe(&self, v: f64, label_set: Option<S>) {
+    pub fn observe(&self, v: f64, label_set: Option<S>, timestamp: Option<SystemTime>) {
         let mut inner = self.inner.write();
         let bucket = inner.histogram.observe_and_bucket(v);
         if let (Some(bucket), Some(label_set)) = (bucket, label_set) {
@@ -259,7 +260,7 @@ impl<S> HistogramWithExemplars<S> {
                 Exemplar {
                     label_set,
                     value: v,
-                    time: SystemTime::now(),
+                    timestamp,
                 },
             );
         }
