Merge branch 'master' into ftorres/utf-8

Author: fedetorres93

CHANGELOG.md

@@ -4,8 +4,16 @@ 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).
 
-## [0.23.0] - unreleased
+## [0.23.1] - unreleased
 
+### Changed
+
+- `Histogram::new` now accepts an `IntoIterator` argument, rather than an `Iterator`.
+  See [PR 243].
+
+[PR 243]: https://github.com/prometheus/client_rust/pull/243
+
+## [0.23.0]
 
 ### Changed
 
@@ -34,12 +42,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Supoort `Arc<String>` for `EncodeLabelValue`.
   See [PR 217].
 
+- Add `histogram::exponential_buckets_range`.
+  See [PR 233].
+
 - Added `get` method to `Family`.
   See [PR 234].
 
 [PR 173]: https://github.com/prometheus/client_rust/pull/173
 [PR 216]: https://github.com/prometheus/client_rust/pull/216
 [PR 217]: https://github.com/prometheus/client_rust/pull/217
+[PR 233]: https://github.com/prometheus/client_rust/pull/233
 [PR 234]: https://github.com/prometheus/client_rust/pull/234
 
 ### Fixed

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "prometheus-client"
-version = "0.23.0"
+version = "0.23.1"
 authors = ["Max Inden <[email protected]>"]
 edition = "2021"
 description = "Open Metrics client library allowing users to natively instrument applications."

src/encoding/protobuf.rs

@@ -14,7 +14,7 @@
 //! #   counter.clone(),
 //! # );
 //! # counter.inc();
-//! // Returns `MetricSet`, the top-level container type. Please refer to [openmetrics_data_model.proto](https://github.com/OpenObservability/OpenMetrics/blob/main/proto/openmetrics_data_model.proto) for details.
+//! // Returns `MetricSet`, the top-level container type. Please refer to [openmetrics_data_model.proto](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/proto/openmetrics_data_model.proto) for details.
 //! let metric_set = encode(&registry).unwrap();
 //!
 //! let family = metric_set.metric_families.first().unwrap();

src/encoding/text.rs

@@ -56,7 +56,7 @@ use std::fmt::Write;
 ///
 /// Use [`encode_registry`] or [`encode_eof`] if partial encoding is needed.
 ///
-/// See [OpenMetrics exposition format](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#text-format)
+/// See [OpenMetrics exposition format](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#text-format)
 /// for additional details.
 ///
 /// # Examples

src/metrics/histogram.rs

@@ -28,7 +28,7 @@ use std::sync::Arc;
 /// let custom_buckets = [
 ///    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0,
 /// ];
-/// let histogram = Histogram::new(custom_buckets.into_iter());
+/// let histogram = Histogram::new(custom_buckets);
 /// histogram.observe(4.2);
 /// ```
 // TODO: Consider using atomics. See
@@ -57,7 +57,12 @@ pub(crate) struct Inner {
 
 impl Histogram {
     /// Create a new [`Histogram`].
-    pub fn new(buckets: impl Iterator<Item = f64>) -> Self {
+    ///
+    /// ```rust
+    /// # use prometheus_client::metrics::histogram::Histogram;
+    /// let histogram = Histogram::new([10.0, 100.0, 1_000.0]);
+    /// ```
+    pub fn new(buckets: impl IntoIterator<Item = f64>) -> Self {
         Self {
             inner: Arc::new(RwLock::new(Inner {
                 sum: Default::default(),
@@ -122,6 +127,30 @@ pub fn exponential_buckets(start: f64, factor: f64, length: u16) -> impl Iterato
         .take(length.into())
 }
 
+/// Exponential bucket distribution within a range
+///
+/// Creates `length` buckets, where the lowest bucket is `min` and the highest bucket is `max`.
+///
+/// If `length` is less than 1, or `min` is less than or equal to 0, an empty iterator is returned.
+pub fn exponential_buckets_range(min: f64, max: f64, length: u16) -> impl Iterator<Item = f64> {
+    let mut len_observed = length;
+    let mut min_bucket = min;
+    // length needs a positive length and min needs to be greater than 0
+    // set len_observed to 0 and min_bucket to 1.0
+    // this will return an empty iterator in the result
+    if length < 1 || min <= 0.0 {
+        len_observed = 0;
+        min_bucket = 1.0;
+    }
+    // We know max/min and highest bucket. Solve for growth_factor.
+    let growth_factor = (max / min_bucket).powf(1.0 / (len_observed as f64 - 1.0));
+
+    iter::repeat(())
+        .enumerate()
+        .map(move |(i, _)| min_bucket * growth_factor.powf(i as f64))
+        .take(len_observed.into())
+}
+
 /// Linear bucket distribution.
 pub fn linear_buckets(start: f64, width: f64, length: u16) -> impl Iterator<Item = f64> {
     iter::repeat(())
@@ -166,4 +195,21 @@ mod tests {
             linear_buckets(0.0, 1.0, 10).collect::<Vec<_>>()
         );
     }
+
+    #[test]
+    fn exponential_range() {
+        assert_eq!(
+            vec![1.0, 2.0, 4.0, 8.0, 16.0, 32.0],
+            exponential_buckets_range(1.0, 32.0, 6).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn exponential_range_incorrect() {
+        let res = exponential_buckets_range(1.0, 32.0, 0).collect::<Vec<_>>();
+        assert!(res.is_empty());
+
+        let res = exponential_buckets_range(0.0, 32.0, 6).collect::<Vec<_>>();
+        assert!(res.is_empty());
+    }
 }