feat: [torrust#1514] add unit and description to metrics

It's also shown in the JSON export format.

```json
{
  "metrics": [
    {
      "type": "counter",
      "name": "torrent_repository_torrents_downloads_total",
      "unit": "count",
      "description": "The total number of torrent downloads.",
      "samples": []
    }
}
```

todo: show them in the Prometheus export format.

Author: josecelano

packages/http-tracker-core/src/statistics/mod.rs

@@ -17,7 +17,7 @@ pub fn describe_metrics() -> Metrics {
     metrics.metric_collection.describe_counter(
         &metric_name!(HTTP_TRACKER_CORE_REQUESTS_RECEIVED_TOTAL),
         Some(Unit::Count),
-        Some(&MetricDescription::new("Total number of HTTP requests received")),
+        Some(MetricDescription::new("Total number of HTTP requests received")),
     );
 
     metrics

packages/metrics/src/metric/mod.rs

@@ -9,23 +9,38 @@ use super::label::LabelSet;
 use super::prometheus::PrometheusSerializable;
 use super::sample_collection::SampleCollection;
 use crate::gauge::Gauge;
+use crate::metric::description::MetricDescription;
 use crate::sample::Measurement;
+use crate::unit::Unit;
 
 pub type MetricName = name::MetricName;
 
 #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
 pub struct Metric<T> {
     name: MetricName,
 
+    #[serde(rename = "unit")]
+    opt_unit: Option<Unit>,
+
+    #[serde(rename = "description")]
+    opt_description: Option<MetricDescription>,
+
     #[serde(rename = "samples")]
     sample_collection: SampleCollection<T>,
 }
 
 impl<T> Metric<T> {
     #[must_use]
-    pub fn new(name: MetricName, samples: SampleCollection<T>) -> Self {
+    pub fn new(
+        name: MetricName,
+        opt_unit: Option<Unit>,
+        opt_description: Option<MetricDescription>,
+        samples: SampleCollection<T>,
+    ) -> Self {
         Self {
             name,
+            opt_unit,
+            opt_description,
             sample_collection: samples,
         }
     }
@@ -34,9 +49,11 @@ impl<T> Metric<T> {
     ///
     /// This function will panic if the empty sample collection cannot be created.
     #[must_use]
-    pub fn without_samples(name: MetricName) -> Self {
+    pub fn new_empty_with_name(name: MetricName) -> Self {
         Self {
             name,
+            opt_unit: None,
+            opt_description: None,
             sample_collection: SampleCollection::new(vec![]).expect("Empty sample collection creation should not fail"),
         }
     }
@@ -119,7 +136,7 @@ mod tests {
 
             let samples = SampleCollection::<Gauge>::default();
 
-            let metric = Metric::<Gauge>::new(name.clone(), samples);
+            let metric = Metric::<Gauge>::new(name.clone(), None, None, samples);
 
             assert!(metric.is_empty());
         }
@@ -133,7 +150,7 @@ mod tests {
 
             let samples = SampleCollection::new(vec![Sample::new(Counter::new(1), time, label_set.clone())]).unwrap();
 
-            Metric::<Counter>::new(name.clone(), samples)
+            Metric::<Counter>::new(name.clone(), None, None, samples)
         }
 
         #[test]
@@ -147,7 +164,7 @@ mod tests {
 
             let samples = SampleCollection::<Gauge>::default();
 
-            let metric = Metric::<Gauge>::new(name.clone(), samples);
+            let metric = Metric::<Gauge>::new(name.clone(), None, None, samples);
 
             assert_eq!(metric.number_of_samples(), 0);
         }
@@ -166,7 +183,7 @@ mod tests {
 
             let samples = SampleCollection::<Counter>::default();
 
-            let _metric = Metric::<Counter>::new(name, samples);
+            let _metric = Metric::<Counter>::new(name, None, None, samples);
         }
 
         #[test]
@@ -179,7 +196,7 @@ mod tests {
 
             let samples = SampleCollection::new(vec![Sample::new(Counter::new(1), time, label_set.clone())]).unwrap();
 
-            let metric = Metric::<Counter>::new(name.clone(), samples);
+            let metric = Metric::<Counter>::new(name.clone(), None, None, samples);
 
             assert_eq!(metric.get_sample_data(&label_set).unwrap().value().value(), 1);
         }
@@ -200,7 +217,7 @@ mod tests {
 
             let samples = SampleCollection::<Gauge>::default();
 
-            let _metric = Metric::<Gauge>::new(name, samples);
+            let _metric = Metric::<Gauge>::new(name, None, None, samples);
         }
 
         #[test]
@@ -213,7 +230,7 @@ mod tests {
 
             let samples = SampleCollection::new(vec![Sample::new(Gauge::new(1.0), time, label_set.clone())]).unwrap();
 
-            let metric = Metric::<Gauge>::new(name.clone(), samples);
+            let metric = Metric::<Gauge>::new(name.clone(), None, None, samples);
 
             assert_relative_eq!(metric.get_sample_data(&label_set).unwrap().value().value(), 1.0);
         }

packages/metrics/src/metric_collection.rs

@@ -10,6 +10,7 @@ use super::label::LabelSet;
 use super::metric::{Metric, MetricName};
 use super::prometheus::PrometheusSerializable;
 use crate::metric::description::MetricDescription;
+use crate::sample_collection::SampleCollection;
 use crate::unit::Unit;
 use crate::METRICS_TARGET;
 
@@ -56,12 +57,12 @@ impl MetricCollection {
 
     // Counter-specific methods
 
-    pub fn describe_counter(&mut self, name: &MetricName, opt_unit: Option<Unit>, opt_description: Option<&MetricDescription>) {
+    pub fn describe_counter(&mut self, name: &MetricName, opt_unit: Option<Unit>, opt_description: Option<MetricDescription>) {
         tracing::info!(target: METRICS_TARGET, type = "counter", name = name.to_string(), unit = ?opt_unit, description = ?opt_description);
 
-        let metric = Metric::<Counter>::without_samples(name.clone());
+        let metric = Metric::<Counter>::new(name.clone(), opt_unit, opt_description, SampleCollection::default());
 
-        self.counters.ensure_metric_exists(metric);
+        self.counters.insert(metric);
     }
 
     #[must_use]
@@ -123,12 +124,12 @@ impl MetricCollection {
 
     // Gauge-specific methods
 
-    pub fn describe_gauge(&mut self, name: &MetricName, opt_unit: Option<Unit>, opt_description: Option<&MetricDescription>) {
+    pub fn describe_gauge(&mut self, name: &MetricName, opt_unit: Option<Unit>, opt_description: Option<MetricDescription>) {
         tracing::info!(target: METRICS_TARGET, type = "gauge", name = name.to_string(), unit = ?opt_unit, description = ?opt_description);
 
-        let metric = Metric::<Gauge>::without_samples(name.clone());
+        let metric = Metric::<Gauge>::new(name.clone(), opt_unit, opt_description, SampleCollection::default());
 
-        self.gauges.ensure_metric_exists(metric);
+        self.gauges.insert(metric);
     }
 
     #[must_use]
@@ -333,11 +334,15 @@ impl<T> MetricKindCollection<T> {
         self.metrics.keys()
     }
 
-    pub fn ensure_metric_exists(&mut self, metric: Metric<T>) {
+    pub fn insert_if_absent(&mut self, metric: Metric<T>) {
         if !self.metrics.contains_key(metric.name()) {
-            self.metrics.insert(metric.name().clone(), metric);
+            self.insert(metric);
         }
     }
+
+    pub fn insert(&mut self, metric: Metric<T>) {
+        self.metrics.insert(metric.name().clone(), metric);
+    }
 }
 
 impl<T: Clone> MetricKindCollection<T> {
@@ -377,9 +382,9 @@ impl MetricKindCollection<Counter> {
     ///
     /// Panics if the metric does not exist.
     pub fn increment(&mut self, name: &MetricName, label_set: &LabelSet, time: DurationSinceUnixEpoch) {
-        let metric = Metric::<Counter>::without_samples(name.clone());
+        let metric = Metric::<Counter>::new_empty_with_name(name.clone());
 
-        self.ensure_metric_exists(metric);
+        self.insert_if_absent(metric);
 
         let metric = self.metrics.get_mut(name).expect("Counter metric should exist");
 
@@ -394,9 +399,9 @@ impl MetricKindCollection<Counter> {
     ///
     /// Panics if the metric does not exist.
     pub fn absolute(&mut self, name: &MetricName, label_set: &LabelSet, value: u64, time: DurationSinceUnixEpoch) {
-        let metric = Metric::<Counter>::without_samples(name.clone());
+        let metric = Metric::<Counter>::new_empty_with_name(name.clone());
 
-        self.ensure_metric_exists(metric);
+        self.insert_if_absent(metric);
 
         let metric = self.metrics.get_mut(name).expect("Counter metric should exist");
 
@@ -421,9 +426,9 @@ impl MetricKindCollection<Gauge> {
     ///
     /// Panics if the metric does not exist and it could not be created.
     pub fn set(&mut self, name: &MetricName, label_set: &LabelSet, value: f64, time: DurationSinceUnixEpoch) {
-        let metric = Metric::<Gauge>::without_samples(name.clone());
+        let metric = Metric::<Gauge>::new_empty_with_name(name.clone());
 
-        self.ensure_metric_exists(metric);
+        self.insert_if_absent(metric);
 
         let metric = self.metrics.get_mut(name).expect("Gauge metric should exist");
 
@@ -438,9 +443,9 @@ impl MetricKindCollection<Gauge> {
     ///
     /// Panics if the metric does not exist and it could not be created.
     pub fn increment(&mut self, name: &MetricName, label_set: &LabelSet, time: DurationSinceUnixEpoch) {
-        let metric = Metric::<Gauge>::without_samples(name.clone());
+        let metric = Metric::<Gauge>::new_empty_with_name(name.clone());
 
-        self.ensure_metric_exists(metric);
+        self.insert_if_absent(metric);
 
         let metric = self.metrics.get_mut(name).expect("Gauge metric should exist");
 
@@ -455,9 +460,9 @@ impl MetricKindCollection<Gauge> {
     ///
     /// Panics if the metric does not exist and it could not be created.
     pub fn decrement(&mut self, name: &MetricName, label_set: &LabelSet, time: DurationSinceUnixEpoch) {
-        let metric = Metric::<Gauge>::without_samples(name.clone());
+        let metric = Metric::<Gauge>::new_empty_with_name(name.clone());
 
-        self.ensure_metric_exists(metric);
+        self.insert_if_absent(metric);
 
         let metric = self.metrics.get_mut(name).expect("Gauge metric should exist");
 
@@ -523,11 +528,15 @@ mod tests {
             MetricCollection::new(
                 MetricKindCollection::new(vec![Metric::new(
                     metric_name!("http_tracker_core_announce_requests_received_total"),
+                    None,
+                    None,
                     SampleCollection::new(vec![Sample::new(Counter::new(1), time, label_set_1.clone())]).unwrap(),
                 )])
                 .unwrap(),
                 MetricKindCollection::new(vec![Metric::new(
                     metric_name!("udp_tracker_server_performance_avg_announce_processing_time_ns"),
+                    None,
+                    None,
                     SampleCollection::new(vec![Sample::new(Gauge::new(1.0), time, label_set_1.clone())]).unwrap(),
                 )])
                 .unwrap(),
@@ -541,6 +550,8 @@ mod tests {
                 {
                     "type":"counter",
                     "name":"http_tracker_core_announce_requests_received_total",
+                    "unit": null,
+                    "description": null,
                     "samples":[
                         {
                             "value":1,
@@ -565,6 +576,8 @@ mod tests {
                 {
                     "type":"gauge",
                     "name":"udp_tracker_server_performance_avg_announce_processing_time_ns",
+                    "unit": null,
+                    "description": null,
                     "samples":[
                         {
                             "value":1.0,
@@ -603,10 +616,20 @@ mod tests {
 
     #[test]
     fn it_should_not_allow_duplicate_names_across_types() {
-        let counters =
-            MetricKindCollection::new(vec![Metric::new(metric_name!("test_metric"), SampleCollection::default())]).unwrap();
-        let gauges =
-            MetricKindCollection::new(vec![Metric::new(metric_name!("test_metric"), SampleCollection::default())]).unwrap();
+        let counters = MetricKindCollection::new(vec![Metric::new(
+            metric_name!("test_metric"),
+            None,
+            None,
+            SampleCollection::default(),
+        )])
+        .unwrap();
+        let gauges = MetricKindCollection::new(vec![Metric::new(
+            metric_name!("test_metric"),
+            None,
+            None,
+            SampleCollection::default(),
+        )])
+        .unwrap();
 
         assert!(MetricCollection::new(counters, gauges).is_err());
     }
@@ -699,6 +722,8 @@ mod tests {
         let metric_collection = MetricCollection::new(
             MetricKindCollection::new(vec![Metric::new(
                 metric_name!("http_tracker_core_announce_requests_received_total"),
+                None,
+                None,
                 SampleCollection::new(vec![
                     Sample::new(Counter::new(1), time, label_set_1.clone()),
                     Sample::new(Counter::new(2), time, label_set_2.clone()),
@@ -730,11 +755,11 @@ mod tests {
         let mut counters = MetricKindCollection::default();
         let mut gauges = MetricKindCollection::default();
 
-        let counter = Metric::<Counter>::without_samples(metric_name!("test_counter"));
-        counters.ensure_metric_exists(counter);
+        let counter = Metric::<Counter>::new_empty_with_name(metric_name!("test_counter"));
+        counters.insert_if_absent(counter);
 
-        let gauge = Metric::<Gauge>::without_samples(metric_name!("test_gauge"));
-        gauges.ensure_metric_exists(gauge);
+        let gauge = Metric::<Gauge>::new_empty_with_name(metric_name!("test_gauge"));
+        gauges.insert_if_absent(gauge);
 
         let metric_collection = MetricCollection::new(counters, gauges).unwrap();
 
@@ -760,6 +785,8 @@ mod tests {
             let mut metric_collection = MetricCollection::new(
                 MetricKindCollection::new(vec![Metric::new(
                     metric_name!("test_counter"),
+                    None,
+                    None,
                     SampleCollection::new(vec![Sample::new(Counter::new(0), time, label_set.clone())]).unwrap(),
                 )])
                 .unwrap(),
@@ -819,10 +846,14 @@ mod tests {
             let result = MetricKindCollection::new(vec![
                 Metric::new(
                     metric_name!("test_counter"),
+                    None,
+                    None,
                     SampleCollection::new(vec![Sample::new(Counter::new(0), time, label_set.clone())]).unwrap(),
                 ),
                 Metric::new(
                     metric_name!("test_counter"),
+                    None,
+                    None,
                     SampleCollection::new(vec![Sample::new(Counter::new(0), time, label_set.clone())]).unwrap(),
                 ),
             ]);
@@ -849,6 +880,8 @@ mod tests {
                 MetricKindCollection::default(),
                 MetricKindCollection::new(vec![Metric::new(
                     metric_name!("test_gauge"),
+                    None,
+                    None,
                     SampleCollection::new(vec![Sample::new(Gauge::new(0.0), time, label_set.clone())]).unwrap(),
                 )])
                 .unwrap(),
@@ -901,10 +934,14 @@ mod tests {
             let result = MetricKindCollection::new(vec![
                 Metric::new(
                     metric_name!("test_gauge"),
+                    None,
+                    None,
                     SampleCollection::new(vec![Sample::new(Gauge::new(0.0), time, label_set.clone())]).unwrap(),
                 ),
                 Metric::new(
                     metric_name!("test_gauge"),
+                    None,
+                    None,
                     SampleCollection::new(vec![Sample::new(Gauge::new(0.0), time, label_set.clone())]).unwrap(),
                 ),
             ]);

packages/metrics/src/unit.rs

@@ -4,7 +4,11 @@
 //! The `Unit` enum is used to specify the unit of measurement for metrics.
 //!
 //! They were copied from the `metrics` crate, to allow future compatibility.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
 pub enum Unit {
     Count,
     Percent,