Merge #1414: New API endpoint with extendable metrics

e3b84a4 feat: [#1403] rename field update_at to recorded_at in metrics Sample (Jose Celano)
5099e90 refactor: [#1403] extract Measurement strcut (Jose Celano)
017d977 refactor: [#1403] remove unused code (Jose Celano)
af8dbfa feat: [#1403] expose udp-tracker-server metrics expose in REST API (Jose Celano)
786f6f0 feat: [#1403] add extendable-labeled metrics to udp-tracker-server (Jose Celano)
3f51afc feat: [#1403] expose udp-tracker-core metrics expose in REST API (Jose Celano)
9d09337 feat: [#1403] add extendable-labeled metrics to udp-tracker-core (Jose Celano)
d717818 feat: [#1403] add extendable-labeled metrics to http-tracker-core and expose in REST API (Jose Celano)
730de9f feat: [#1403] add new package for extendable labeled metrics (Jose Celano)
8a169b1 feat: add protocol method to ServiceBinding (Jose Celano)

Pull request description:

  Relates to: #1263 (comment)

  It adds a new  REST API endpoint with a new extendable format for metrics.

  In this PR I will only add the metrics for:

  - Performance
  - Announce requests
  - Scrape requests

  See the complete list [here](#1263 (comment)).

  It requires emitting the new metrics from the:

  - HTTP Tracker Core package
  - UDP Tracker Core package
  - UDP Tracker Server package

  The remaining metrics (`torrents` and `peers`) require adding metrics to the tracker core package.

  ### JSON format

  **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,
            "recorded_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,
            "recorded_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"
              }
            ]
          }
        ]
      }
    ]
  }
  ```

  ### Prometheus format

  **URL:** http://0.0.0.0:1212/api/v1/metrics?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
  ```

  ### Manual Tests

  You can increase the number of `announce` or `scrape` requests by using the console tracker client.

  HTTP:

  ```console
  cargo run -p torrust-tracker-client --bin http_tracker_client announce http://127.0.0.1:7070 443c7602b4fde83d1154d6d9da48808418b181b6 | jq
  ```

  ```console
  cargo run -p torrust-tracker-client --bin http_tracker_client scrape http://127.0.0.1:7070 443c7602b4fde83d1154d6d9da48808418b181b6 | jq
  ```

  UDP:

  ```console
  cargo run -p torrust-tracker-client --bin udp_tracker_client announce udp://127.0.0.1:6969 443c7602b4fde83d1154d6d9da48808418b181b6 | jq
  ```

  ```console
  cargo run -p torrust-tracker-client --bin udp_tracker_client scrape udp://127.0.0.1:6969 443c7602b4fde83d1154d6d9da48808418b181b6 | jq
  ```

  ### TODO

  - [x] Move labeled metrics to `metrics` package.
  - [x] The metric name and label set must be unique in the array of labeled metrics. Enforce constraint.
  - [x] Replace primitive types in the new labeled metrics with new tpyes to enforce constraints. For example, metrics names, labels, metric types, etc.
  - [x] Serialize to Prometheus format.
  - [x] Serialize/Deserialize from JSON. Needed in the Index.
  - [x] Inject the rigth URL scheme. It's hardcoded now.
  - [x] Review what labels we include per metric. For example the "protocol" label can be derived from the URL but it requires parsing the URL and it makes harder to build graphs in Grafana. I guess we should include labels for the type of aggregate data we want to get.
  - [x] Implement versioning. A given API version must contain a set of labeled metrics. Clients expect some labeled metrics to be included in a API version. We need to initialize the array of metrics with all the expected labeled metrics with the initial value.
  - [x] Write more tests.
  - [x] Implement for UDP metrics. It's only implemented for HTTP tracker metrics. This would require merging labeled metrics.
    - [x] Emit metrics from UDP tracker core.
    - [x] Emit metrics from UDP tracker server.

  Discarded:

  - [ ] ~~Use a f64 for metric values instead of u64.~~. Using `u64` for counter and `f64` for gauge.
  - [ ] ~~Add a new `namespace` label to avoid conflict for packages using the same metric name.~~ The metric would not be the same with different context, it would be a different source even if they might represent the same thing. For example, a counter for announce requests can be added at the server level, HTTP core level and tracker core level. I think it's better to use a different metric for them.
    - In Grafana for example you should explicitly exclude labels otherwise you could get duplicate values if two metrics from two different packages have the same name.

  Notes:

  - Regarding what I called "versioning", you can describe metrics so they appear in the JSON response even if there are no samples yet. However, for the Prometheus format, they will not be included in the export. A line without a metric value would be an error. We could set the initial value, but it makes sense only for counters.

  ### Future work

  - We will probably need some methods for the `MetricCollection` to search for metrics, apply aggregated functions, etc. For example:
    - Sum all the samples values for a given counter metric (total). For example: total number of requests regardless what label values they have.
  - We can't deprecate the current `http://0.0.0.0:1212/api/v1/stats` API endpoint until we have the same information in the new endpoint `http://0.0.0.0:1212/api/v1/metrics`. We need to add this type of metrics to the tracker core package too because it's the package we can get `torrents` and `peers` metrics from. See #1263 (comment)
  - Add tests for the new endpoint.
  - Deploy to the demo tracker and build a new dashboard in Grafana and compare it with the current dashboard to check if metrics are being collected ok.

ACKs for top commit:
  josecelano:
    ACK e3b84a4

Tree-SHA512: 5f9fcaca6008b44cda6221fd6dccc486ee512825621d533d510a4a9d0e146982e073a766f290006ffecc1bb7e5478fb81639bf39f2b5b201e91ec45e7885c16a

Author: josecelano

.github/workflows/deployment.yaml

@@ -74,6 +74,7 @@ jobs:
           cargo publish -p torrust-tracker-configuration
           cargo publish -p torrust-tracker-contrib-bencode
           cargo publish -p torrust-tracker-located-error
+          cargo publish -p torrust-tracker-metrics
           cargo publish -p torrust-tracker-primitives
           cargo publish -p torrust-tracker-test-helpers
           cargo publish -p torrust-tracker-torrent-repository

Cargo.lock

@@ -59,9 +59,11 @@
         "Eray",
         "filesd",
         "flamegraph",
+        "formatjson",
         "Freebox",
         "Frostegård",
         "gecos",
+        "Gibibytes",
         "Grcov",
         "hasher",
         "healthcheck",
@@ -86,6 +88,7 @@
         "kcachegrind",
         "kexec",
         "keyout",
+        "Kibibytes",
         "kptr",
         "lcov",
         "leecher",
@@ -96,12 +99,14 @@
         "LOGNAME",
         "Lphant",
         "matchmakes",
+        "Mebibytes",
         "metainfo",
         "middlewares",
         "misresolved",
         "mockall",
         "multimap",
         "myacicontext",
+        "ñaca",
         "Naim",
         "nanos",
         "newkey",
@@ -157,6 +162,7 @@
         "Swiftbit",
         "taiki",
         "tdyne",
+        "Tebibytes",
         "tempfile",
         "testcontainers",
         "thiserror",

cSpell.json

@@ -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"] }