diff --git a/CHANGELOG.md b/CHANGELOG.md index 4afd4ff..fa46522 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,9 +13,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 `EncodeGaugeValue` would not error when encoding some `u64`s that don't fit in a `i64`. See [PR 281]. - 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]. [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 ## [0.24.0] diff --git a/Cargo.toml b/Cargo.toml index a35d145..13a7e3b 100644 --- a/Cargo.toml +++ b/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"] diff --git a/src/lib.rs b/src/lib.rs index cfff623..9aab12f 100644 --- a/src/lib.rs +++ b/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; diff --git a/src/metrics/histogram.rs b/src/metrics/histogram.rs index 1f5e4d9..8a4a28a 100644 --- a/src/metrics/histogram.rs +++ b/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::>(); 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" + ); + } }