When generating # Help and # Type metadata be sure to update the

name to include the `_total` suffix if the type is a counter.

Signed-off-by: William Johnson <wjohnson@whamcloud.com>

Author: William Johnson

src/encoding.rs

@@ -108,12 +108,13 @@ impl DescriptorEncoder<'_> {
         help: &str,
         unit: Option<&'s Unit>,
         metric_type: MetricType,
+        auto_suffix: bool,
     ) -> Result<MetricEncoder<'s>, std::fmt::Error> {
         for_both_mut!(
             self,
             DescriptorEncoderInner,
             e,
-            Ok(e.encode_descriptor(name, help, unit, metric_type)?.into())
+            Ok(e.encode_descriptor(name, help, unit, metric_type, auto_suffix)?.into())
         )
     }
 }

src/encoding/protobuf.rs

@@ -98,6 +98,7 @@ impl DescriptorEncoder<'_> {
         help: &str,
         unit: Option<&Unit>,
         metric_type: MetricType,
+        auto_suffix: bool,
     ) -> Result<MetricEncoder<'s>, std::fmt::Error> {
         let family = openmetrics_data_model::MetricFamily {
             name: {
@@ -135,6 +136,7 @@ impl DescriptorEncoder<'_> {
                 .metrics,
             metric_type,
             labels,
+            auto_suffix,
         })
     }
 }
@@ -150,6 +152,7 @@ pub(crate) struct MetricEncoder<'f> {
     family: &'f mut Vec<openmetrics_data_model::Metric>,
     /// Labels to be added to each metric.
     labels: Vec<openmetrics_data_model::Label>,
+    auto_suffix: bool,
 }
 
 impl MetricEncoder<'_> {
@@ -245,6 +248,7 @@ impl MetricEncoder<'_> {
             metric_type: self.metric_type,
             family: self.family,
             labels,
+            auto_suffix: self.auto_suffix,
         })
     }
 

src/encoding/text.rs

@@ -221,6 +221,7 @@ impl DescriptorEncoder<'_> {
         help: &str,
         unit: Option<&'s Unit>,
         metric_type: MetricType,
+        auto_suffix: bool,
     ) -> Result<MetricEncoder<'s>, std::fmt::Error> {
         self.writer.write_str("# HELP ")?;
         if let Some(prefix) = self.prefix {
@@ -231,7 +232,10 @@ impl DescriptorEncoder<'_> {
         if let Some(unit) = unit {
             self.writer.write_str("_")?;
             self.writer.write_str(unit.as_str())?;
+        } else if metric_type == MetricType::Counter && auto_suffix {
+            self.writer.write_str("_total")?;
         }
+
         self.writer.write_str(" ")?;
         self.writer.write_str(help)?;
         self.writer.write_str("\n")?;
@@ -245,7 +249,10 @@ impl DescriptorEncoder<'_> {
         if let Some(unit) = unit {
             self.writer.write_str("_")?;
             self.writer.write_str(unit.as_str())?;
+        } else if metric_type == MetricType::Counter && auto_suffix {
+            self.writer.write_str("_total")?;
         }
+
         self.writer.write_str(" ")?;
         self.writer.write_str(metric_type.as_str())?;
         self.writer.write_str("\n")?;
@@ -271,6 +278,7 @@ impl DescriptorEncoder<'_> {
             unit,
             const_labels: self.labels,
             family_labels: None,
+            auto_suffix,
         })
     }
 }
@@ -291,6 +299,7 @@ pub(crate) struct MetricEncoder<'a> {
     unit: Option<&'a Unit>,
     const_labels: &'a [(Cow<'static, str>, Cow<'static, str>)],
     family_labels: Option<&'a dyn super::EncodeLabelSet>,
+    auto_suffix: bool,
 }
 
 impl std::fmt::Debug for MetricEncoder<'_> {
@@ -307,6 +316,7 @@ impl std::fmt::Debug for MetricEncoder<'_> {
             .field("unit", &self.unit)
             .field("const_labels", &self.const_labels)
             .field("labels", &labels.as_str())
+            .field("auto_suffix", &self.auto_suffix)
             .finish()
     }
 }
@@ -323,7 +333,9 @@ impl MetricEncoder<'_> {
     ) -> Result<(), std::fmt::Error> {
         self.write_prefix_name_unit()?;
 
-        self.write_suffix("total")?;
+        if self.auto_suffix {
+            self.write_suffix("total")?;
+        }
 
         self.encode_labels::<NoLabelSet>(None)?;
 
@@ -393,6 +405,7 @@ impl MetricEncoder<'_> {
             unit: self.unit,
             const_labels: self.const_labels,
             family_labels: Some(label_set),
+            auto_suffix: self.auto_suffix,
         })
     }
 
@@ -1082,6 +1095,7 @@ mod tests {
                     "some help",
                     None,
                     counter.metric_type(),
+                    false,
                 )?;
                 counter.encode(metric_encoder)?;
                 Ok(())

src/metrics.rs

@@ -14,7 +14,7 @@ pub trait TypedMetric {
 }
 
 /// OpenMetrics metric type.
-#[derive(Clone, Copy, Debug)]
+#[derive(Clone, Copy, Debug, PartialEq)]
 #[allow(missing_docs)]
 pub enum MetricType {
     Counter,

src/registry.rs

@@ -126,7 +126,39 @@ impl Registry {
         help: H,
         metric: impl Metric,
     ) {
-        self.priv_register(name, help, metric, None)
+        self.priv_register(name, help, metric, None, true)
+    }
+
+    /// Register a metric with the [`Registry`].
+    ///
+    /// Note: In the Open Metrics text exposition format some metric types have
+    /// a special suffix, e.g. the
+    /// [`Counter`](crate::metrics::counter::Counter`) metric with `_total`.
+    /// These suffixes are inferred through the metric type and must not be
+    /// appended to the metric name manually by the user.
+    ///
+    /// Note: A full stop punctuation mark (`.`) is automatically added to the
+    /// passed help text.
+    ///
+    /// Use [`Registry::register_with_unit`] whenever a unit for the given
+    /// metric is known.
+    ///
+    /// ```
+    /// # use prometheus_client::metrics::counter::{Atomic as _, Counter};
+    /// # use prometheus_client::registry::{Registry, Unit};
+    /// #
+    /// let mut registry = Registry::default();
+    /// let counter: Counter = Counter::default();
+    ///
+    /// registry.register_without_auto_suffix("my_counter", "This is my counter", counter.clone());
+    /// ```
+    pub fn register_without_auto_suffix<N: Into<String>, H: Into<String>>(
+        &mut self,
+        name: N,
+        help: H,
+        metric: impl Metric,
+    ) {
+        self.priv_register(name, help, metric, None, false)
     }
 
     /// Register a metric with the [`Registry`] specifying the metric's unit.
@@ -158,7 +190,7 @@ impl Registry {
         unit: Unit,
         metric: impl Metric,
     ) {
-        self.priv_register(name, help, metric, Some(unit))
+        self.priv_register(name, help, metric, Some(unit), false)
     }
 
     fn priv_register<N: Into<String>, H: Into<String>>(
@@ -167,8 +199,9 @@ impl Registry {
         help: H,
         metric: impl Metric,
         unit: Option<Unit>,
+        auto_suffix: bool,
     ) {
-        let descriptor = Descriptor::new(name, help, unit);
+        let descriptor = Descriptor::new(name, help, unit, auto_suffix);
         self.metrics.push((descriptor, Box::new(metric)));
     }
 
@@ -295,6 +328,7 @@ impl Registry {
                 &descriptor.help,
                 descriptor.unit.as_ref(),
                 EncodeMetric::metric_type(metric.as_ref()),
+                descriptor.auto_suffix,
             )?;
             metric.encode(metric_encoder)?;
         }
@@ -335,15 +369,17 @@ struct Descriptor {
     name: String,
     help: String,
     unit: Option<Unit>,
+    auto_suffix: bool,
 }
 
 impl Descriptor {
     /// Create new [`Descriptor`].
-    fn new<N: Into<String>, H: Into<String>>(name: N, help: H, unit: Option<Unit>) -> Self {
+    fn new<N: Into<String>, H: Into<String>>(name: N, help: H, unit: Option<Unit>, auto_suffix: bool) -> Self {
         Self {
             name: name.into(),
             help: help.into() + ".",
             unit,
+            auto_suffix,
         }
     }
 }