feat: allow describing metrics

Author: josecelano

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

@@ -2,7 +2,9 @@ use std::sync::Arc;
 
 use tokio::sync::{RwLock, RwLockReadGuard};
 use torrust_tracker_metrics::label::LabelSet;
+use torrust_tracker_metrics::metric::description::MetricDescription;
 use torrust_tracker_metrics::metric::MetricName;
+use torrust_tracker_metrics::unit::Unit;
 use torrust_tracker_primitives::DurationSinceUnixEpoch;
 
 use super::metrics::Metrics;
@@ -22,9 +24,9 @@ impl Default for Repository {
 impl Repository {
     #[must_use]
     pub fn new() -> Self {
-        Self {
-            stats: Arc::new(RwLock::new(Metrics::default())),
-        }
+        let stats = Arc::new(RwLock::new(Self::describe_metrics()));
+
+        Self { stats }
     }
 
     pub async fn get_stats(&self) -> RwLockReadGuard<'_, Metrics> {
@@ -60,4 +62,22 @@ impl Repository {
         stats_lock.increase_counter(metric_name, labels, now);
         drop(stats_lock);
     }
+
+    fn describe_metrics() -> Metrics {
+        let mut metrics = Metrics::default();
+
+        metrics.metric_collection.describe_counter(
+            &MetricName::new("http_tracker_core_announce_requests_received_total"),
+            Some(Unit::Count),
+            Some(MetricDescription::new("Total number of announce requests received")),
+        );
+
+        metrics.metric_collection.describe_counter(
+            &MetricName::new("http_tracker_core_scrape_requests_received_total"),
+            Some(Unit::Count),
+            Some(MetricDescription::new("Total number of scrape requests received")),
+        );
+
+        metrics
+    }
 }

packages/metrics/src/metric/description.rs

@@ -0,0 +1,12 @@
+use derive_more::Display;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Display, Clone, Eq, PartialEq, Default, Deserialize, Serialize, Hash, Ord, PartialOrd)]
+pub struct MetricDescription(String);
+
+impl MetricDescription {
+    #[must_use]
+    pub fn new(name: &str) -> Self {
+        Self(name.to_owned())
+    }
+}

packages/metrics/src/metric/mod.rs

@@ -1,3 +1,4 @@
+pub mod description;
 pub mod name;
 
 use serde::{Deserialize, Serialize};

packages/metrics/src/metric_collection.rs

@@ -10,7 +10,9 @@ use super::gauge::Gauge;
 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;
 
 #[derive(Debug, Default)]
 pub struct Metrics {
@@ -27,6 +29,16 @@ impl Metrics {
 
     // Counter-specific methods
 
+    /// # Panics
+    ///
+    /// Panics if it can't get write access to the inner collection.
+    pub fn describe_counter(&mut self, name: &MetricName, _opt_unit: Option<Unit>, _opt_description: Option<MetricDescription>) {
+        self.inner.write().unwrap().counters.ensure_metric_exists(name);
+    }
+
+    /// It allows to describe a counter metric so the metrics appear in the JSON
+    /// response even if there are no samples yet.
+    ///
     /// # Panics
     ///
     /// Panics if it can't get read access to the inner collection.
@@ -44,6 +56,16 @@ impl Metrics {
 
     // Gauge-specific methods
 
+    /// It allows to describe a gauge metric so the metrics appear in the JSON
+    /// response even if there are no samples yet.
+    ///
+    /// # Panics
+    ///
+    /// Panics if it can't get write access to the inner collection.
+    pub fn describe_gauge(&mut self, name: &MetricName, _opt_unit: Option<Unit>, _opt_description: Option<MetricDescription>) {
+        self.inner.write().unwrap().gauges.ensure_metric_exists(name);
+    }
+
     /// # Panics
     ///
     /// Panics if it can't get read access to the inner collection.
@@ -89,6 +111,10 @@ impl MetricCollection {
 
     // Counter-specific methods
 
+    pub fn describe_counter(&mut self, name: &MetricName, _opt_unit: Option<Unit>, _opt_description: Option<MetricDescription>) {
+        self.counters.ensure_metric_exists(name);
+    }
+
     #[must_use]
     pub fn get_counter_value(&self, name: &MetricName, labels: &LabelSet) -> Counter {
         self.counters.get_value(name, labels)
@@ -108,6 +134,10 @@ impl MetricCollection {
 
     // Gauge-specific methods
 
+    pub fn describe_gauge(&mut self, name: &MetricName, _opt_unit: Option<Unit>, _opt_description: Option<MetricDescription>) {
+        self.gauges.ensure_metric_exists(name);
+    }
+
     #[must_use]
     pub fn get_gauge_value(&self, name: &MetricName, labels: &LabelSet) -> Gauge {
         self.gauges.get_value(name, labels)