Merge #1577: Overhaul stats: Refactor metrics, use label metrics to calculate global metrics

dcfb5d5 refactor: [#1446] Calculate global metrics from labeled metrics (Jose Celano)
3f5216e fix: [#1446] clippy error (Jose Celano)
96bae36 feat: [#1446] add new metric label server_binding_address_ip_type (Jose Celano)
1376a7c refactor: [#1446] rename AddressType to IpType (Jose Celano)
476ece4 refactor: [#1446] WIP. Calculate global metrics from labeled metrics (Jose Celano)
0d13439 test: [#1446] add more tests to metrics package (Jose Celano)
4da4f83 refactor: [#1446] rename vars (Jose Celano)
64be847 feat: [#1446] add aggregate function sum to metric collection (Jose Celano)

Pull request description:

  The idea is to continue exposing the `stats` endpoint but removing the internal code to calculate them. Instead, we calculate the metrics from the labeled metrics.

  That will **simplify** the event listeners and **avoid duplicate code** to calculate the same data.

  ### Endpoints for statistics

  `stats` (simple predefined global metrics)

  - http://localhost:1212/api/v1/stats?token=MyAccessToken&format=json
  - http://localhost:1212/api/v1/stats?token=MyAccessToken&format=prometheus

  `metrics` (extendable-labelled metrics)

  - http://localhost:1212/api/v1/metrics?token=MyAccessToken&format=json
  - http://localhost:1212/api/v1/metrics?token=MyAccessToken&format=prometheus

  ### Subtasks

  - [x] Add a new method to `MetricCollection` to sum the metric's samples.
  - [x] Review test coverage.
  - [x] Use the new method to calculate metrics in the `stats` endpoint.

  ### After merging this PR

  - Deploy to the tracker demo and verify that both Grafana dashboards appear identical.
  - Delete unused code to calculate the metrics in the `stats` endpoint directly in the event listeners.
  - Redeploy to the tracker demo and re-verify.

  **NOTICE:** We have two Grafana dashboards, one collecting data from the `stats` endpoint and another collecting data from `metrics`, and they look identical now. If there is a bug in the way we calculate aggregate values in the `MetricCollection`, we should see different graphs in the dashboards.

  Both dashboards (built from stats on the left, built from metrics on the right):

  ![image](https://github.com/user-attachments/assets/638b35af-ca46-4e21-b601-780588a3ba1e)

  **NOTICE:** Also, the new methods will be helpful for external users once we publish the metrics crate. Consumers of the Torrust Tracker API (`metrics` endpoint) will be able to deserialize and calculate aggregate values from the response.

ACKs for top commit:
  josecelano:
    ACK dcfb5d5

Tree-SHA512: 3de4e41817b4b3ceeb5c501ed0bbe9d47c4ab7feb06fe3b5c472c4482b221d7ec360995bf381f0e519c5856d83b2aafe92fce22b53ea3e60517db26ac3a3a300

Author: josecelano

Cargo.lock

@@ -87,8 +87,12 @@ impl From<ConnectionContext> for LabelSet {
                 LabelValue::new(&connection_context.server.service_binding.bind_address().ip().to_string()),
             ),
             (
-                label_name!("server_binding_address_type"),
-                LabelValue::new(&connection_context.server.service_binding.bind_address_type().to_string()),
+                label_name!("server_binding_address_ip_type"),
+                LabelValue::new(&connection_context.server.service_binding.bind_address_ip_type().to_string()),
+            ),
+            (
+                label_name!("server_binding_address_ip_family"),
+                LabelValue::new(&connection_context.server.service_binding.bind_address_ip_family().to_string()),
             ),
             (
                 label_name!("server_binding_port"),

packages/http-tracker-core/src/event.rs

@@ -32,7 +32,12 @@ pub async fn handle_event(event: Event, stats_repository: &Arc<Repository>, now:
                 .increase_counter(&metric_name!(HTTP_TRACKER_CORE_REQUESTS_RECEIVED_TOTAL), &label_set, now)
                 .await
             {
-                Ok(()) => {}
+                Ok(()) => {
+                    tracing::debug!(
+                        "Successfully increased the counter for HTTP announce requests received: {}",
+                        label_set
+                    );
+                }
                 Err(err) => tracing::error!("Failed to increase the counter: {}", err),
             };
         }
@@ -57,7 +62,12 @@ pub async fn handle_event(event: Event, stats_repository: &Arc<Repository>, now:
                 .increase_counter(&metric_name!(HTTP_TRACKER_CORE_REQUESTS_RECEIVED_TOTAL), &label_set, now)
                 .await
             {
-                Ok(()) => {}
+                Ok(()) => {
+                    tracing::debug!(
+                        "Successfully increased the counter for HTTP scrape requests received: {}",
+                        label_set
+                    );
+                }
                 Err(err) => tracing::error!("Failed to increase the counter: {}", err),
             };
         }

packages/http-tracker-core/src/statistics/event/handler.rs

@@ -33,7 +33,7 @@ impl Metrics {
         labels: &LabelSet,
         now: DurationSinceUnixEpoch,
     ) -> Result<(), Error> {
-        self.metric_collection.increase_counter(metric_name, labels, now)
+        self.metric_collection.increment_counter(metric_name, labels, now)
     }
 
     /// # Errors

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

@@ -8,7 +8,7 @@ use torrust_tracker_metrics::metric::description::MetricDescription;
 use torrust_tracker_metrics::metric_name;
 use torrust_tracker_metrics::unit::Unit;
 
-const HTTP_TRACKER_CORE_REQUESTS_RECEIVED_TOTAL: &str = "http_tracker_core_requests_received_total";
+pub const HTTP_TRACKER_CORE_REQUESTS_RECEIVED_TOTAL: &str = "http_tracker_core_requests_received_total";
 
 #[must_use]
 pub fn describe_metrics() -> Metrics {

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

@@ -1 +1 @@
-./.coverage
+.coverage

packages/metrics/.gitignore

@@ -6,6 +6,28 @@ A library with the metrics types used by the [Torrust Tracker](https://github.co
 
 [Crate documentation](https://docs.rs/torrust-tracker-metrics).
 
+## Testing
+
+Run coverage report:
+
+```console
+cargo llvm-cov --package torrust-tracker-metrics 
+```
+
+Generate LCOV report with `llvm-cov` (for Visual Studio Code extension):
+
+```console
+mkdir -p ./.coverage
+cargo llvm-cov --package torrust-tracker-metrics  --lcov --output-path=./.coverage/lcov.info
+```
+
+Generate HTML report with `llvm-cov`:
+
+```console
+mkdir -p ./.coverage
+cargo llvm-cov --package torrust-tracker-metrics  --html --output-dir ./.coverage
+```
+
 ## Acknowledgements
 
 We copied some parts like units or function names and signatures from the crate [metrics](https://crates.io/crates/metrics) because we wanted to make it compatible as much as possible with it. In the future, we may consider using the `metrics` crate directly instead of maintaining our own version.

packages/metrics/README.md

@@ -0,0 +1,19 @@
+{
+    "words": [
+        "cloneable",
+        "formatjson",
+        "Gibibytes",
+        "Kibibytes",
+        "Mebibytes",
+        "ñaca",
+        "rstest",
+        "subsec",
+        "Tebibytes",
+        "thiserror"
+    ],
+    "enableFiletypes": [
+        "dockerfile",
+        "shellscript",
+        "toml"
+    ]
+}

packages/metrics/cSpell.json

@@ -0,0 +1,143 @@
+use derive_more::Display;
+
+#[derive(Debug, Display, Clone, Copy, PartialEq, Default)]
+pub struct AggregateValue(f64);
+
+impl AggregateValue {
+    #[must_use]
+    pub fn new(value: f64) -> Self {
+        Self(value)
+    }
+
+    #[must_use]
+    pub fn value(&self) -> f64 {
+        self.0
+    }
+}
+
+impl From<f64> for AggregateValue {
+    fn from(value: f64) -> Self {
+        Self(value)
+    }
+}
+
+impl From<AggregateValue> for f64 {
+    fn from(value: AggregateValue) -> Self {
+        value.0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use approx::assert_relative_eq;
+
+    use super::*;
+
+    #[test]
+    fn it_should_be_created_with_new() {
+        let value = AggregateValue::new(42.5);
+        assert_relative_eq!(value.value(), 42.5);
+    }
+
+    #[test]
+    fn it_should_return_the_inner_value() {
+        let value = AggregateValue::new(123.456);
+        assert_relative_eq!(value.value(), 123.456);
+    }
+
+    #[test]
+    fn it_should_handle_zero_value() {
+        let value = AggregateValue::new(0.0);
+        assert_relative_eq!(value.value(), 0.0);
+    }
+
+    #[test]
+    fn it_should_handle_negative_values() {
+        let value = AggregateValue::new(-42.5);
+        assert_relative_eq!(value.value(), -42.5);
+    }
+
+    #[test]
+    fn it_should_handle_infinity() {
+        let value = AggregateValue::new(f64::INFINITY);
+        assert_relative_eq!(value.value(), f64::INFINITY);
+    }
+
+    #[test]
+    fn it_should_handle_nan() {
+        let value = AggregateValue::new(f64::NAN);
+        assert!(value.value().is_nan());
+    }
+
+    #[test]
+    fn it_should_be_created_from_f64() {
+        let value: AggregateValue = 42.5.into();
+        assert_relative_eq!(value.value(), 42.5);
+    }
+
+    #[test]
+    fn it_should_convert_to_f64() {
+        let value = AggregateValue::new(42.5);
+        let f64_value: f64 = value.into();
+        assert_relative_eq!(f64_value, 42.5);
+    }
+
+    #[test]
+    fn it_should_be_displayable() {
+        let value = AggregateValue::new(42.5);
+        assert_eq!(value.to_string(), "42.5");
+    }
+
+    #[test]
+    fn it_should_be_debuggable() {
+        let value = AggregateValue::new(42.5);
+        let debug_string = format!("{value:?}");
+        assert_eq!(debug_string, "AggregateValue(42.5)");
+    }
+
+    #[test]
+    fn it_should_be_cloneable() {
+        let value = AggregateValue::new(42.5);
+        let cloned_value = value;
+        assert_eq!(value, cloned_value);
+    }
+
+    #[test]
+    fn it_should_be_copyable() {
+        let value = AggregateValue::new(42.5);
+        let copied_value = value;
+        assert_eq!(value, copied_value);
+    }
+
+    #[test]
+    fn it_should_support_equality_comparison() {
+        let value1 = AggregateValue::new(42.5);
+        let value2 = AggregateValue::new(42.5);
+        let value3 = AggregateValue::new(43.0);
+
+        assert_eq!(value1, value2);
+        assert_ne!(value1, value3);
+    }
+
+    #[test]
+    fn it_should_handle_special_float_values_in_equality() {
+        let nan1 = AggregateValue::new(f64::NAN);
+        let nan2 = AggregateValue::new(f64::NAN);
+        let infinity = AggregateValue::new(f64::INFINITY);
+        let neg_infinity = AggregateValue::new(f64::NEG_INFINITY);
+
+        // NaN is not equal to itself in IEEE 754
+        assert_ne!(nan1, nan2);
+        assert_eq!(infinity, AggregateValue::new(f64::INFINITY));
+        assert_eq!(neg_infinity, AggregateValue::new(f64::NEG_INFINITY));
+        assert_ne!(infinity, neg_infinity);
+    }
+
+    #[test]
+    fn it_should_handle_conversion_roundtrip() {
+        let original_value = 42.5;
+        let aggregate_value = AggregateValue::from(original_value);
+        let converted_back: f64 = aggregate_value.into();
+        assert_relative_eq!(original_value, converted_back);
+    }
+}