Merge branch 'master' into add-usize-isize-encode-impls

Signed-off-by: Max Inden <mail@max-inden.de>

Author: mxinden

CHANGELOG.md

@@ -6,16 +6,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.24.1]
 
+### Added
+
+- `EncodeGaugeValue` is implemented for `usize` and `isize`, and
+  `EncodeCounterValue` is implemented for `usize`. See [PR 282].
+
 ### Fixed
 
 - `EncodeGaugeValue`, `EncodeCounterValue` and `EncodeExemplarValue` now use
   fewer `as` casts in their implementation. This caught an issue where
   `EncodeGaugeValue` would not error when encoding some `u64`s that don't fit
   in a `i64`. See [PR 281].
-
-- `EncodeGaugeValue` is implemented for `usize` and `isize`, and
-  `EncodeCounterValue` is implemented for `usize`. See [PR 282].
-
+- Filter out empty metric families, to match the go client. See [PR 279].
+- `Histogram` now exposes `count()` and `sum()` methods when the `test-util`
+  feature is enabled. See [PR 242].
+- `Family` now exposes a `contains()` method when the `test-util` feature
+  is enabled. See [PR 245].
+- `Family` now exposes `len()` and `is_empty()` methods when the
+  `test-util` feature is enabled. See [PR 246].
+
+[PR 279]: https://github.com/prometheus/client_rust/pull/279
+[PR 281]: https://github.com/prometheus/client_rust/pull/281
+[PR 242]: https://github.com/prometheus/client_rust/pull/242
+[PR 245]: https://github.com/prometheus/client_rust/pull/245
+[PR 246]: https://github.com/prometheus/client_rust/pull/246
 [PR 281]: https://github.com/prometheus/client_rust/pull/281
 [PR 282]: https://github.com/prometheus/client_rust/pull/282
 

Cargo.toml

@@ -14,6 +14,13 @@ documentation = "https://docs.rs/prometheus-client"
 default = []
 protobuf = ["dep:prost", "dep:prost-types", "dep:prost-build"]
 
+# This feature provides additional APIs for testing downstream code using
+# `prometheus-client`.
+#
+# Note: Interfaces gated by this feature flag are not subject to stability
+# guarantees and may be changed or removed in patch releases.
+test-util = []
+
 [workspace]
 members = ["derive-encode"]
 
@@ -31,7 +38,7 @@ axum = "0.7"
 criterion = "0.5"
 futures = "0.3"
 http-types = "2"
-pyo3 = "0.22"
+pyo3 = "0.27"
 quickcheck = "1"
 rand = "0.8.4"
 tide = "0.16"

src/encoding.rs

@@ -50,6 +50,17 @@ pub trait EncodeMetric {
     // One can not use [`TypedMetric`] directly, as associated constants are not
     // object safe and thus can not be used with dynamic dispatching.
     fn metric_type(&self) -> MetricType;
+
+    /// Check if the metric is empty.
+    ///
+    /// An empty metric is a metric that has no data to encode, and thus should not have any
+    /// descriptor in the final output.
+    ///
+    /// By default, this returns `false`, ensuring the metric and its description is always
+    /// encoded.
+    fn is_empty(&self) -> bool {
+        false
+    }
 }
 
 impl EncodeMetric for Box<dyn EncodeMetric> {

src/encoding/text.rs

@@ -1251,21 +1251,21 @@ mod tests {
     }
 
     fn parse_with_python_client(input: String) {
-        pyo3::prepare_freethreaded_python();
+        pyo3::Python::initialize();
 
         println!("{input:?}");
-        Python::with_gil(|py| {
-            let parser = PyModule::from_code_bound(
+        Python::attach(|py| {
+            let parser = PyModule::from_code(
                 py,
-                r#"
+                c"
 from prometheus_client.openmetrics.parser import text_string_to_metric_families
 
 def parse(input):
     families = text_string_to_metric_families(input)
     list(families)
-"#,
-                "parser.py",
-                "parser",
+",
+                c"parser.py",
+                c"parser",
             )
             .map_err(|e| e.to_string())
             .unwrap();
@@ -1278,4 +1278,41 @@ def parse(input):
                 .unwrap();
         })
     }
+
+    #[test]
+    fn encode_omit_empty() {
+        let mut registry = Registry::default();
+        let counter1: Family<Vec<(&'static str, &'static str)>, Counter> = Default::default();
+        let counter2: Family<Vec<(&'static str, &'static str)>, Counter> = Default::default();
+        let counter3: Family<Vec<(&'static str, &'static str)>, Counter> = Default::default();
+
+        registry.register("counter1", "First counter", counter1.clone());
+        registry.register("counter2", "Second counter", counter2.clone());
+        registry.register("counter3", "Third counter", counter3.clone());
+
+        counter1.get_or_create(&vec![("label", "value")]).inc();
+
+        let mut encoded = String::new();
+        encode(&mut encoded, &registry).unwrap();
+
+        let expected = "# HELP counter1 First counter.\n".to_owned()
+            + "# TYPE counter1 counter\n"
+            + "counter1_total{label=\"value\"} 1\n"
+            + "# EOF\n";
+        assert_eq!(expected, encoded);
+
+        counter2.get_or_create(&vec![("label", "value")]).inc();
+
+        let mut encoded = String::new();
+        encode(&mut encoded, &registry).unwrap();
+
+        let expected = "# HELP counter1 First counter.\n".to_owned()
+            + "# TYPE counter1 counter\n"
+            + "counter1_total{label=\"value\"} 1\n"
+            + "# HELP counter2 Second counter.\n"
+            + "# TYPE counter2 counter\n"
+            + "counter2_total{label=\"value\"} 1\n"
+            + "# EOF\n";
+        assert_eq!(expected, encoded);
+    }
 }

src/lib.rs

@@ -77,6 +77,12 @@
 //! ```
 //! See [examples] directory for more.
 //!
+//! # Features
+//!
+//! The `test-util` gates additional APIs, such as accessors, to facilitate integration and unit
+//! testing of metrics. Note that APIs gated by this feature flag are not subject to stability
+//! guarantees and may be changed or removed in patch releases.
+//!
 //! [examples]: https://github.com/prometheus/client_rust/tree/master/examples
 
 pub mod collector;

src/metrics/counter.rs

@@ -265,7 +265,7 @@ mod tests {
                 // Map infinite, subnormal and NaN to 0.0.
                 .map(|f| if f.is_normal() { f } else { 0.0 })
                 .collect();
-            let sum = fs.iter().sum();
+            let sum: f64 = fs.iter().sum();
             let counter = Counter::<f64, AtomicU64>::default();
             for f in fs {
                 counter.inc_by(f);

src/metrics/family.rs

@@ -341,6 +341,56 @@ impl<S: Clone + std::hash::Hash + Eq, M, C: MetricConstructor<M>> Family<S, M, C
         self.metrics.write().clear()
     }
 
+    /// Returns `true` if the given label set exists within the metric family.
+    ///
+    /// ```
+    /// # use prometheus_client::metrics::counter::{Atomic, Counter};
+    /// # use prometheus_client::metrics::family::Family;
+    /// #
+    /// let family = Family::<Vec<(String, String)>, Counter>::default();
+    /// let get = vec![("method".to_owned(), "GET".to_owned())];
+    /// let post = vec![("method".to_owned(), "POST".to_owned())];
+    ///
+    /// // Create the metric with labels `method="GET"`.
+    /// family.get_or_create(&get).inc();
+    ///
+    /// assert!(family.contains(&get), "a `method=\"GET\"`-labeled metric exists");
+    /// assert!(!family.contains(&post), "a `method=\"POST\"`-labeled metric does NOT exist");
+    /// ```
+    #[cfg(any(test, feature = "test-util"))]
+    pub fn contains(&self, label_set: &S) -> bool {
+        self.metrics.read().get(label_set).is_some()
+    }
+
+    /// Returns the number of metrics in this family.
+    ///
+    /// ```
+    /// # use prometheus_client::metrics::counter::{Atomic, Counter};
+    /// # use prometheus_client::metrics::family::Family;
+    /// #
+    /// let family = Family::<Vec<(String, String)>, Counter>::default();
+    /// assert_eq!(family.len(), 0);
+    ///
+    /// // Will create the metric with label `method="GET"` on first call and
+    /// // return a reference.
+    /// family.get_or_create(&vec![("method".to_owned(), "GET".to_owned())]).inc();
+    /// assert_eq!(family.len(), 1);
+    ///
+    /// // Clear the family of all label sets.
+    /// family.clear();
+    /// assert_eq!(family.len(), 0);
+    /// ```
+    #[cfg(any(test, feature = "test-util"))]
+    pub fn len(&self) -> usize {
+        self.metrics.read().len()
+    }
+
+    /// Returns `true` if the family contains no metrics.
+    #[cfg(any(test, feature = "test-util"))]
+    pub fn is_empty(&self) -> bool {
+        self.metrics.read().is_empty()
+    }
+
     pub(crate) fn read(&self) -> RwLockReadGuard<'_, HashMap<S, M>> {
         self.metrics.read()
     }
@@ -377,6 +427,10 @@ where
     fn metric_type(&self) -> MetricType {
         M::TYPE
     }
+
+    fn is_empty(&self) -> bool {
+        self.metrics.read().is_empty()
+    }
 }
 
 #[cfg(test)]

src/metrics/histogram.rs

@@ -81,6 +81,18 @@ impl Histogram {
         self.observe_and_bucket(v);
     }
 
+    /// Returns the current sum of all observations.
+    #[cfg(any(test, feature = "test-util"))]
+    pub fn sum(&self) -> f64 {
+        self.inner.read().sum
+    }
+
+    /// Returns the current number of observations.
+    #[cfg(any(test, feature = "test-util"))]
+    pub fn count(&self) -> u64 {
+        self.inner.read().count
+    }
+
     /// Observes the given value, returning the index of the first bucket the
     /// value is added to.
     ///
@@ -212,4 +224,53 @@ mod tests {
         let res = exponential_buckets_range(0.0, 32.0, 6).collect::<Vec<_>>();
         assert!(res.is_empty());
     }
+
+    /// Checks that [`Histogram::count()`] works properly.
+    #[test]
+    fn count() {
+        let histogram = Histogram::new([1.0_f64, 2.0, 3.0, 4.0, 5.0]);
+        assert_eq!(
+            histogram.count(),
+            0,
+            "histogram has zero observations when instantiated"
+        );
+
+        histogram.observe(1.0);
+        assert_eq!(histogram.count(), 1, "histogram has one observation");
+
+        histogram.observe(2.5);
+        assert_eq!(histogram.count(), 2, "histogram has two observations");
+
+        histogram.observe(6.0);
+        assert_eq!(histogram.count(), 3, "histogram has three observations");
+    }
+
+    /// Checks that [`Histogram::sum()`] works properly.
+    #[test]
+    fn sum() {
+        const BUCKETS: [f64; 3] = [10.0, 100.0, 1000.0];
+        let histogram = Histogram::new(BUCKETS);
+        assert_eq!(
+            histogram.sum(),
+            0.0,
+            "histogram sum is zero when instantiated"
+        );
+
+        histogram.observe(3.0); // 3 + 4 + 15 + 101 = 123
+        histogram.observe(4.0);
+        histogram.observe(15.0);
+        histogram.observe(101.0);
+        assert_eq!(
+            histogram.sum(),
+            123.0,
+            "histogram sum records accurate sum of observations"
+        );
+
+        histogram.observe(1111.0);
+        assert_eq!(
+            histogram.sum(),
+            1234.0,
+            "histogram sum records accurate sum of observations"
+        );
+    }
 }

src/registry.rs

@@ -228,15 +228,15 @@ impl Registry {
     /// let subsystem_a_counter_2: Counter = Counter::default();
     ///
     /// let subsystem_a_registry = registry.sub_registry_with_prefix("subsystem_a");
-    /// registry.register("counter_1", "", subsystem_a_counter_1.clone());
-    /// registry.register("counter_2", "", subsystem_a_counter_2.clone());
+    /// subsystem_a_registry.register("counter_1", "", subsystem_a_counter_1.clone());
+    /// subsystem_a_registry.register("counter_2", "", subsystem_a_counter_2.clone());
     ///
     /// let subsystem_b_counter_1: Counter = Counter::default();
     /// let subsystem_b_counter_2: Counter = Counter::default();
     ///
-    /// let subsystem_a_registry = registry.sub_registry_with_prefix("subsystem_b");
-    /// registry.register("counter_1", "", subsystem_b_counter_1.clone());
-    /// registry.register("counter_2", "", subsystem_b_counter_2.clone());
+    /// let subsystem_b_registry = registry.sub_registry_with_prefix("subsystem_b");
+    /// subsystem_b_registry.register("counter_1", "", subsystem_b_counter_1.clone());
+    /// subsystem_b_registry.register("counter_2", "", subsystem_b_counter_2.clone());
     /// ```
     ///
     /// See [`Registry::sub_registry_with_label`] for the same functionality,
@@ -287,7 +287,7 @@ impl Registry {
     }
 
     pub(crate) fn encode(&self, encoder: &mut DescriptorEncoder) -> Result<(), std::fmt::Error> {
-        for (descriptor, metric) in self.metrics.iter() {
+        for (descriptor, metric) in self.metrics.iter().filter(|(_, m)| !m.is_empty()) {
             let mut descriptor_encoder =
                 encoder.with_prefix_and_labels(self.prefix.as_ref(), &self.labels);
             let metric_encoder = descriptor_encoder.encode_descriptor(