feat: add summary metrics type

Reference:
[1] prometheus#254

Author: codefever

Cargo.toml

@@ -11,8 +11,9 @@ homepage = "https://github.com/prometheus/client_rust"
 documentation = "https://docs.rs/prometheus-client"
 
 [features]
-default = []
+default = ["summary"]
 protobuf = ["dep:prost", "dep:prost-types", "dep:prost-build"]
+summary = ["dep:quanta", "dep:quantiles"]
 
 [workspace]
 members = ["derive-encode"]
@@ -24,6 +25,8 @@ parking_lot = "0.12"
 prometheus-client-derive-encode = { version = "0.5.0", path = "derive-encode" }
 prost = { version = "0.12.0", optional = true }
 prost-types = { version = "0.12.0", optional = true }
+quanta = { version = "0.12.6", optional = true }
+quantiles = { version = "0.7.1", optional = true }
 
 [dev-dependencies]
 async-std = { version = "1", features = ["attributes"] }

src/encoding.rs

@@ -186,6 +186,22 @@ impl MetricEncoder<'_> {
         )
     }
 
+    /// Encode a summary.
+    #[cfg(feature = "summary")]
+    pub fn encode_summary<S: EncodeLabelSet>(
+        &mut self,
+        sum: f64,
+        count: u64,
+        quantiles: &[(f64, f64)],
+    ) -> Result<(), std::fmt::Error> {
+        for_both_mut!(
+            self,
+            MetricEncoderInner,
+            e,
+            e.encode_summary::<S>(sum, count, quantiles)
+        )
+    }
+
     /// Encode a metric family.
     pub fn encode_family<'s, S: EncodeLabelSet>(
         &'s mut self,

src/encoding/protobuf.rs

@@ -53,6 +53,8 @@ impl From<MetricType> for openmetrics_data_model::MetricType {
             MetricType::Counter => openmetrics_data_model::MetricType::Counter,
             MetricType::Gauge => openmetrics_data_model::MetricType::Gauge,
             MetricType::Histogram => openmetrics_data_model::MetricType::Histogram,
+            #[cfg(feature = "summary")]
+            MetricType::Summary => openmetrics_data_model::MetricType::Summary,
             MetricType::Info => openmetrics_data_model::MetricType::Info,
             MetricType::Unknown => openmetrics_data_model::MetricType::Unknown,
         }
@@ -288,6 +290,42 @@ impl MetricEncoder<'_> {
 
         Ok(())
     }
+
+    #[cfg(feature = "summary")]
+    pub fn encode_summary<S: EncodeLabelSet>(
+        &mut self,
+        sum: f64,
+        count: u64,
+        quantiles: &[(f64, f64)],
+    ) -> Result<(), std::fmt::Error> {
+        let quantile = quantiles
+            .iter()
+            .enumerate()
+            .map(|(_, (quantile, value))| {
+                Ok(openmetrics_data_model::summary_value::Quantile {
+                    quantile: *quantile,
+                    value: *value,
+                })
+            })
+            .collect::<Result<Vec<_>, std::fmt::Error>>()?;
+
+        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::SummaryValue(
+                    openmetrics_data_model::SummaryValue {
+                        count,
+                        created: None,
+                        quantile,
+                        sum: Some(openmetrics_data_model::summary_value::Sum::DoubleValue(sum)),
+                    },
+                )),
+                ..Default::default()
+            }],
+        });
+
+        Ok(())
+    }
 }
 
 impl<S: EncodeLabelSet, V: EncodeExemplarValue> TryFrom<&Exemplar<S, V>>
@@ -817,6 +855,45 @@ mod tests {
         }
     }
 
+    #[cfg(feature = "summary")]
+    #[test]
+    fn encode_summary() {
+        use crate::metrics::summary::Summary;
+
+        let mut registry = Registry::default();
+        let summary = Summary::new(std::time::Duration::from_secs(5), 10, vec![0.5, 0.9, 0.99], 0.01);
+        registry.register("my_summary", "My summary", summary.clone());
+        summary.observe(0.10);
+        summary.observe(0.20);
+        summary.observe(0.30);
+
+        let metric_set = encode(&registry).unwrap();
+
+        let family = metric_set.metric_families.first().unwrap();
+        assert_eq!("my_summary", family.name);
+        assert_eq!("My summary.", family.help);
+
+        assert_eq!(
+            openmetrics_data_model::MetricType::Summary as i32,
+            extract_metric_type(&metric_set)
+        );
+
+        match extract_metric_point_value(&metric_set) {
+            openmetrics_data_model::metric_point::Value::SummaryValue(value) => {
+                assert_eq!(
+                    "Some(DoubleValue(0.6000000000000001))",
+                    format!("{:?}", value.sum),
+                );
+                assert_eq!(3, value.count);
+                assert_eq!(
+                    "[Quantile { quantile: 0.5, value: 0.2 }, Quantile { quantile: 0.9, value: 0.3 }, Quantile { quantile: 0.99, value: 0.3 }]",
+                    format!("{:?}", value.quantile),
+                );
+            }
+            _ => panic!("wrong value type"),
+        }
+    }
+
     #[test]
     fn encode_family_counter_histogram() {
         let mut registry = Registry::default();

src/encoding/text.rs

@@ -444,6 +444,40 @@ impl MetricEncoder<'_> {
         Ok(())
     }
 
+    #[cfg(feature = "summary")]
+    pub fn encode_summary<S: EncodeLabelSet>(
+        &mut self,
+        sum: f64,
+        count: u64,
+        quantiles: &[(f64, f64)],
+    ) -> Result<(), std::fmt::Error> {
+        self.write_prefix_name_unit()?;
+        self.write_suffix("sum")?;
+        self.encode_labels::<NoLabelSet>(None)?;
+        self.writer.write_str(" ")?;
+        self.writer.write_str(dtoa::Buffer::new().format(sum))?;
+        self.newline()?;
+
+        self.write_prefix_name_unit()?;
+        self.write_suffix("count")?;
+        self.encode_labels::<NoLabelSet>(None)?;
+        self.writer.write_str(" ")?;
+        self.writer.write_str(itoa::Buffer::new().format(count))?;
+        self.newline()?;
+
+        for (_, (quantile, result)) in quantiles.iter().enumerate() {
+            self.write_prefix_name_unit()?;
+            self.encode_labels(Some(&[("quantile", *quantile)]))?;
+
+            self.writer.write_str(" ")?;
+            self.writer.write_str(result.to_string().as_str())?;
+
+            self.newline()?;
+        }
+
+        Ok(())
+    }
+
     /// Encode an exemplar for the given metric.
     fn encode_exemplar<S: EncodeLabelSet, V: EncodeExemplarValue>(
         &mut self,
@@ -982,6 +1016,34 @@ mod tests {
         parse_with_python_client(encoded);
     }
 
+    #[cfg(feature = "summary")]
+    #[test]
+    fn encode_summary() {
+        use crate::metrics::summary::Summary;
+
+        let mut registry = Registry::default();
+        let summary = Summary::new(std::time::Duration::from_secs(3), 10, vec![0.5, 0.9, 0.99], 0.0);
+        registry.register("my_summary", "My summary", summary.clone());
+        summary.observe(0.10);
+        summary.observe(0.20);
+        summary.observe(0.30);
+
+        let mut encoded = String::new();
+        encode(&mut encoded, &registry).unwrap();
+
+        let expected = "# HELP my_summary My summary.\n".to_owned()
+            + "# TYPE my_summary summary\n"
+            + "my_summary_sum 0.6000000000000001\n"
+            + "my_summary_count 3\n"
+            + "my_summary{quantile=\"0.5\"} 0.2\n"
+            + "my_summary{quantile=\"0.9\"} 0.3\n"
+            + "my_summary{quantile=\"0.99\"} 0.3\n"
+            + "# EOF\n";
+        assert_eq!(expected, encoded);
+
+        parse_with_python_client(encoded);
+    }
+
     #[test]
     fn sub_registry_with_prefix_and_label() {
         let top_level_metric_name = "my_top_level_metric";

src/metrics.rs

@@ -6,6 +6,8 @@ pub mod family;
 pub mod gauge;
 pub mod histogram;
 pub mod info;
+#[cfg(feature = "summary")]
+pub mod summary;
 
 /// A metric that is aware of its Open Metrics metric type.
 pub trait TypedMetric {
@@ -21,6 +23,8 @@ pub enum MetricType {
     Gauge,
     Histogram,
     Info,
+    #[cfg(feature = "summary")]
+    Summary,
     Unknown,
     // Not (yet) supported metric types.
     //
@@ -37,6 +41,8 @@ impl MetricType {
             MetricType::Gauge => "gauge",
             MetricType::Histogram => "histogram",
             MetricType::Info => "info",
+            #[cfg(feature = "summary")]
+            MetricType::Summary => "summary",
             MetricType::Unknown => "unknown",
         }
     }