feat: [torrust#1403] add extendable-labeled metrics to http-tracker-core and expose in REST API

**URL:** http://0.0.0.0:1212/api/v1/metrics?token=MyAccessToken

**Sample response:**

```json
{
  "metrics":[
    {
      "kind":"counter",
      "name":"http_tracker_core_announce_requests_received_total",
      "samples":[
        {
          "value":1,
          "update_at":"2025-04-02T00:00:00+00:00",
          "labels":[
            {
              "name":"server_binding_ip",
              "value":"0.0.0.0"
            },
            {
              "name":"server_binding_port",
              "value":"7070"
            },
            {
              "name":"server_binding_protocol",
              "value":"http"
            }
          ]
        }
      ]
    },
    {
      "kind":"gauge",
      "name":"udp_tracker_server_performance_avg_announce_processing_time_ns",
      "samples":[
        {
          "value":1.0,
          "update_at":"2025-04-02T00:00:00+00:00",
          "labels":[
            {
              "name":"server_binding_ip",
              "value":"0.0.0.0"
            },
            {
              "name":"server_binding_port",
              "value":"7070"
            },
            {
              "name":"server_binding_protocol",
              "value":"http"
            }
          ]
        }
      ]
    }
  ]
}
```

**URL:** http://0.0.0.0:1212/api/v1/stats?token=MyAccessToken&format=prometheus

```
http_tracker_core_announce_requests_received_total{server_binding_ip="0.0.0.0",server_binding_port="7070",server_binding_protocol="http"} 1
udp_tracker_server_performance_avg_announce_processing_time_ns{server_binding_ip="0.0.0.0",server_binding_port="7070",server_binding_protocol="http"} 1
```

Author: josecelano

Cargo.lock

@@ -37,6 +37,7 @@ torrust-rest-tracker-api-core = { version = "3.0.0-develop", path = "../rest-tra
 torrust-server-lib = { version = "3.0.0-develop", path = "../server-lib" }
 torrust-tracker-clock = { version = "3.0.0-develop", path = "../clock" }
 torrust-tracker-configuration = { version = "3.0.0-develop", path = "../configuration" }
+torrust-tracker-metrics = { version = "3.0.0-develop", path = "../metrics" }
 torrust-tracker-primitives = { version = "3.0.0-develop", path = "../primitives" }
 torrust-udp-tracker-server = { version = "3.0.0-develop", path = "../udp-tracker-server" }
 tower = { version = "0", features = ["timeout"] }

packages/axum-rest-tracker-api-server/Cargo.toml

@@ -9,9 +9,9 @@ use bittorrent_tracker_core::torrent::repository::in_memory::InMemoryTorrentRepo
 use bittorrent_udp_tracker_core::services::banning::BanService;
 use serde::Deserialize;
 use tokio::sync::RwLock;
-use torrust_rest_tracker_api_core::statistics::services::get_metrics;
+use torrust_rest_tracker_api_core::statistics::services::{get_labeled_metrics, get_metrics};
 
-use super::responses::{metrics_response, stats_response};
+use super::responses::{labeled_metrics_response, labeled_stats_response, metrics_response, stats_response};
 
 #[derive(Deserialize, Debug, Default)]
 #[serde(rename_all = "lowercase")]
@@ -28,7 +28,7 @@ pub struct QueryParams {
     pub format: Option<Format>,
 }
 
-/// It handles the request to get the tracker statistics.
+/// It handles the request to get the tracker global metrics.
 ///
 /// By default it returns a `200` response with the stats in JSON format.
 ///
@@ -57,3 +57,30 @@ pub async fn get_stats_handler(
         None => stats_response(metrics),
     }
 }
+
+/// It handles the request to get the tracker extendable metrics.
+///
+/// By default it returns a `200` response with the stats in JSON format.
+///
+/// You can add the GET parameter `format=prometheus` to get the stats in
+/// Prometheus Text Exposition Format.
+#[allow(clippy::type_complexity)]
+pub async fn get_metrics_handler(
+    State(state): State<(
+        Arc<InMemoryTorrentRepository>,
+        Arc<RwLock<BanService>>,
+        Arc<bittorrent_http_tracker_core::statistics::repository::Repository>,
+        Arc<torrust_udp_tracker_server::statistics::repository::Repository>,
+    )>,
+    params: Query<QueryParams>,
+) -> Response {
+    let metrics = get_labeled_metrics(state.0.clone(), state.1.clone(), state.2.clone(), state.3.clone()).await;
+
+    match params.0.format {
+        Some(format) => match format {
+            Format::Json => labeled_stats_response(metrics),
+            Format::Prometheus => labeled_metrics_response(&metrics),
+        },
+        None => labeled_stats_response(metrics),
+    }
+}

packages/axum-rest-tracker-api-server/src/v1/context/stats/handlers.rs

@@ -1,7 +1,8 @@
 //! API resources for the [`stats`](crate::v1::context::stats)
 //! API context.
 use serde::{Deserialize, Serialize};
-use torrust_rest_tracker_api_core::statistics::services::TrackerMetrics;
+use torrust_rest_tracker_api_core::statistics::services::{TrackerLabeledMetrics, TrackerMetrics};
+use torrust_tracker_metrics::metric_collection::MetricCollection;
 
 /// It contains all the statistics generated by the tracker.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq)]
@@ -116,6 +117,21 @@ impl From<TrackerMetrics> for Stats {
     }
 }
 
+/// It contains all the statistics generated by the tracker.
+#[derive(Serialize, Debug, PartialEq)]
+pub struct LabeledStats {
+    metrics: MetricCollection,
+}
+
+impl From<TrackerLabeledMetrics> for LabeledStats {
+    #[allow(deprecated)]
+    fn from(metrics: TrackerLabeledMetrics) -> Self {
+        Self {
+            metrics: metrics.metrics,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use torrust_rest_tracker_api_core::statistics::metrics::Metrics;

packages/axum-rest-tracker-api-server/src/v1/context/stats/resources.rs

@@ -1,9 +1,21 @@
 //! API responses for the [`stats`](crate::v1::context::stats)
 //! API context.
 use axum::response::{IntoResponse, Json, Response};
-use torrust_rest_tracker_api_core::statistics::services::TrackerMetrics;
+use torrust_rest_tracker_api_core::statistics::services::{TrackerLabeledMetrics, TrackerMetrics};
+use torrust_tracker_metrics::prometheus::PrometheusSerializable;
 
-use super::resources::Stats;
+use super::resources::{LabeledStats, Stats};
+
+/// `200` response that contains the [`LabeledStats`] resource as json.
+#[must_use]
+pub fn labeled_stats_response(tracker_metrics: TrackerLabeledMetrics) -> Response {
+    Json(LabeledStats::from(tracker_metrics)).into_response()
+}
+
+#[must_use]
+pub fn labeled_metrics_response(tracker_metrics: &TrackerLabeledMetrics) -> Response {
+    tracker_metrics.metrics.to_prometheus().into_response()
+}
 
 /// `200` response that contains the [`Stats`] resource as json.
 #[must_use]

packages/axum-rest-tracker-api-server/src/v1/context/stats/responses.rs

@@ -9,17 +9,27 @@ use axum::routing::get;
 use axum::Router;
 use torrust_rest_tracker_api_core::container::TrackerHttpApiCoreContainer;
 
-use super::handlers::get_stats_handler;
+use super::handlers::{get_metrics_handler, get_stats_handler};
 
 /// It adds the routes to the router for the [`stats`](crate::v1::context::stats) API context.
 pub fn add(prefix: &str, router: Router, http_api_container: &Arc<TrackerHttpApiCoreContainer>) -> Router {
-    router.route(
-        &format!("{prefix}/stats"),
-        get(get_stats_handler).with_state((
-            http_api_container.tracker_core_container.in_memory_torrent_repository.clone(),
-            http_api_container.ban_service.clone(),
-            http_api_container.http_stats_repository.clone(),
-            http_api_container.udp_server_stats_repository.clone(),
-        )),
-    )
+    router
+        .route(
+            &format!("{prefix}/stats"),
+            get(get_stats_handler).with_state((
+                http_api_container.tracker_core_container.in_memory_torrent_repository.clone(),
+                http_api_container.ban_service.clone(),
+                http_api_container.http_stats_repository.clone(),
+                http_api_container.udp_server_stats_repository.clone(),
+            )),
+        )
+        .route(
+            &format!("{prefix}/metrics"),
+            get(get_metrics_handler).with_state((
+                http_api_container.tracker_core_container.in_memory_torrent_repository.clone(),
+                http_api_container.ban_service.clone(),
+                http_api_container.http_stats_repository.clone(),
+                http_api_container.udp_server_stats_repository.clone(),
+            )),
+        )
 }

packages/axum-rest-tracker-api-server/src/v1/context/stats/routes.rs

@@ -20,17 +20,21 @@ bittorrent-primitives = "0.1.0"
 bittorrent-tracker-core = { version = "3.0.0-develop", path = "../tracker-core" }
 criterion = { version = "0.5.1", features = ["async_tokio"] }
 futures = "0"
+serde = "1.0.219"
 thiserror = "2"
 tokio = { version = "1", features = ["macros", "net", "rt-multi-thread", "signal", "sync"] }
+torrust-tracker-clock = { version = "3.0.0-develop", path = "../clock" }
 torrust-tracker-configuration = { version = "3.0.0-develop", path = "../configuration" }
+torrust-tracker-metrics = { version = "3.0.0-develop", path = "../metrics" }
 torrust-tracker-primitives = { version = "3.0.0-develop", path = "../primitives" }
 tracing = "0"
 
 [dev-dependencies]
+formatjson = "0.3.1"
 mockall = "0"
+serde_json = "1.0.140"
 torrust-tracker-test-helpers = { version = "3.0.0-develop", path = "../test-helpers" }
 
 [[bench]]
 harness = false
 name = "http_tracker_core_benchmark"
-

packages/http-tracker-core/Cargo.toml

@@ -1,5 +1,6 @@
 use std::net::{IpAddr, SocketAddr};
 
+use torrust_tracker_metrics::label::{LabelName, LabelSet, LabelValue};
 use torrust_tracker_primitives::service_binding::ServiceBinding;
 
 pub mod sender;
@@ -59,3 +60,22 @@ pub struct ClientConnectionContext {
 pub struct ServerConnectionContext {
     service_binding: ServiceBinding,
 }
+
+impl From<ConnectionContext> for LabelSet {
+    fn from(connection_context: ConnectionContext) -> Self {
+        LabelSet::from([
+            (
+                LabelName::new("server_binding_protocol"),
+                LabelValue::new(&connection_context.server.service_binding.protocol().to_string()),
+            ),
+            (
+                LabelName::new("server_binding_ip"),
+                LabelValue::new(&connection_context.server.service_binding.bind_address().ip().to_string()),
+            ),
+            (
+                LabelName::new("server_binding_port"),
+                LabelValue::new(&connection_context.server.service_binding.bind_address().port().to_string()),
+            ),
+        ])
+    }
+}

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

@@ -1,8 +1,21 @@
+use torrust_tracker_clock::clock;
+
 pub mod container;
 pub mod event;
 pub mod services;
 pub mod statistics;
 
+/// This code needs to be copied into each crate.
+/// Working version, for production.
+#[cfg(not(test))]
+#[allow(dead_code)]
+pub(crate) type CurrentClock = clock::Working;
+
+/// Stopped version, for testing.
+#[cfg(test)]
+#[allow(dead_code)]
+pub(crate) type CurrentClock = clock::Stopped;
+
 #[cfg(test)]
 pub(crate) mod tests {
     use bittorrent_primitives::info_hash::InfoHash;

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

@@ -1,30 +1,62 @@
 use std::net::IpAddr;
 
+use torrust_tracker_metrics::label::LabelSet;
+use torrust_tracker_metrics::metric::MetricName;
+use torrust_tracker_primitives::DurationSinceUnixEpoch;
+
 use crate::event::Event;
 use crate::statistics::repository::Repository;
 
 /// # Panics
 ///
 /// This function panics if the client IP address is not the same as the IP
 /// version of the event.
-pub async fn handle_event(event: Event, stats_repository: &Repository) {
+pub async fn handle_event(event: Event, stats_repository: &Repository, now: DurationSinceUnixEpoch) {
     match event {
-        Event::TcpAnnounce { connection } => match connection.client_ip_addr() {
-            IpAddr::V4(_) => {
-                stats_repository.increase_tcp4_announces().await;
-            }
-            IpAddr::V6(_) => {
-                stats_repository.increase_tcp6_announces().await;
-            }
-        },
-        Event::TcpScrape { connection } => match connection.client_ip_addr() {
-            IpAddr::V4(_) => {
-                stats_repository.increase_tcp4_scrapes().await;
+        Event::TcpAnnounce { connection } => {
+            // Global fixed metrics
+
+            match connection.client_ip_addr() {
+                IpAddr::V4(_) => {
+                    stats_repository.increase_tcp4_announces().await;
+                }
+                IpAddr::V6(_) => {
+                    stats_repository.increase_tcp6_announces().await;
+                }
             }
-            IpAddr::V6(_) => {
-                stats_repository.increase_tcp6_scrapes().await;
+
+            // Extendable metrics
+
+            stats_repository
+                .increase_counter(
+                    &MetricName::new("http_tracker_core_announce_requests_received_total"),
+                    &LabelSet::from(connection),
+                    now,
+                )
+                .await;
+        }
+        Event::TcpScrape { connection } => {
+            // Global fixed metrics
+
+            match connection.client_ip_addr() {
+                IpAddr::V4(_) => {
+                    stats_repository.increase_tcp4_scrapes().await;
+                }
+                IpAddr::V6(_) => {
+                    stats_repository.increase_tcp6_scrapes().await;
+                }
             }
-        },
+
+            // Extendable metrics
+
+            stats_repository
+                .increase_counter(
+                    &MetricName::new("http_tracker_core_scrape_requests_received_total"),
+                    &LabelSet::from(connection),
+                    now,
+                )
+                .await;
+        }
     }
 
     tracing::debug!("stats: {:?}", stats_repository.get_stats().await);
@@ -34,11 +66,13 @@ pub async fn handle_event(event: Event, stats_repository: &Repository) {
 mod tests {
     use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
 
+    use torrust_tracker_clock::clock::Time;
     use torrust_tracker_primitives::service_binding::{Protocol, ServiceBinding};
 
     use crate::event::{ConnectionContext, Event};
     use crate::statistics::event::handler::handle_event;
     use crate::statistics::repository::Repository;
+    use crate::CurrentClock;
 
     #[tokio::test]
     async fn should_increase_the_tcp4_announces_counter_when_it_receives_a_tcp4_announce_event() {
@@ -53,6 +87,7 @@ mod tests {
                 ),
             },
             &stats_repository,
+            CurrentClock::now(),
         )
         .await;
 
@@ -74,6 +109,7 @@ mod tests {
                 ),
             },
             &stats_repository,
+            CurrentClock::now(),
         )
         .await;
 
@@ -95,6 +131,7 @@ mod tests {
                 ),
             },
             &stats_repository,
+            CurrentClock::now(),
         )
         .await;
 
@@ -116,6 +153,7 @@ mod tests {
                 ),
             },
             &stats_repository,
+            CurrentClock::now(),
         )
         .await;