feat: [#1403] add new package for extendable labeled metrics

This package allow creating collection of metrics that can have labels.

It's similar to the `metrics` crate. There are two types of metrics:

- Counter
- Gauge

For example, you can increase a counter with:

```rust
let time = DurationSinceUnixEpoch::from_secs(1_743_552_000);
let label_set: LabelSet = (LabelName::new("label_name"), LabelValue::new("value")).into();

let mut metric_collection = MetricCollection::new(
    // Collection of counter-type metrics
    MetricKindCollection::new(vec![
      Metric::new(
        MetricName::new("test_counter"),
        SampleCollection::new(vec![Sample::new(Counter::new(0), time, label_set.clone())]))
    ]),
    // Empty colelction of gauge-type metrics
    MetricKindCollection::new(vec![])
);

metric_collection.increase_counter(&MetricName::new("test_counter"), &label_set, time);
```

Metric colelctions are serializable into JSON and exportable to
Prometheus format.

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

cSpell.json

@@ -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",

packages/metrics/.gitignore

@@ -0,0 +1 @@
+./.coverage

packages/metrics/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+description = "A library with the primitive types shared by the Torrust tracker packages."
+keywords = ["api", "library", "metrics"]
+name = "torrust-tracker-metrics"
+readme = "README.md"
+
+authors.workspace = true
+documentation.workspace = true
+edition.workspace = true
+homepage.workspace = true
+license.workspace = true
+publish.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+version.workspace = true
+
+[dependencies]
+chrono = { version = "0", default-features = false, features = ["clock"] }
+derive_more = { version = "2", features = ["constructor"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1.0.140"
+thiserror = "2"
+torrust-tracker-primitives = { version = "3.0.0-develop", path = "../primitives" }
+
+[dev-dependencies]
+approx = "0.5.1"
+formatjson = "0.3.1"
+pretty_assertions = "1.4.1"
+rstest = "0.25.0"

packages/metrics/LICENSE

@@ -0,0 +1,15 @@
+# Torrust Tracker Metrics
+
+A library with the metrics types used by the [Torrust Tracker](https://github.com/torrust/torrust-tracker) packages.
+
+## Documentation
+
+[Crate documentation](https://docs.rs/torrust-tracker-metrics).
+
+## 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.
+
+## License
+
+The project is licensed under the terms of the [GNU AFFERO GENERAL PUBLIC LICENSE](./LICENSE).

packages/metrics/README.md

@@ -0,0 +1,81 @@
+use derive_more::Display;
+use serde::{Deserialize, Serialize};
+
+use super::prometheus::PrometheusSerializable;
+
+#[derive(Debug, Display, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct Counter(u64);
+
+impl Counter {
+    #[must_use]
+    pub fn new(value: u64) -> Self {
+        Self(value)
+    }
+
+    #[must_use]
+    pub fn value(&self) -> u64 {
+        self.0
+    }
+
+    pub fn increment(&mut self, value: u64) {
+        self.0 += value;
+    }
+}
+
+impl From<u64> for Counter {
+    fn from(value: u64) -> Self {
+        Self(value)
+    }
+}
+
+impl From<Counter> for u64 {
+    fn from(counter: Counter) -> Self {
+        counter.value()
+    }
+}
+
+impl PrometheusSerializable for Counter {
+    fn to_prometheus(&self) -> String {
+        format!("{}", self.value())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn it_should_be_created_from_integer_values() {
+        let counter = Counter::new(0);
+        assert_eq!(counter.value(), 0);
+    }
+
+    #[test]
+    fn it_could_be_converted_from_u64() {
+        let counter: Counter = 42.into();
+        assert_eq!(counter.value(), 42);
+    }
+
+    #[test]
+    fn it_could_be_converted_into_u64() {
+        let counter = Counter::new(42);
+        let value: u64 = counter.into();
+        assert_eq!(value, 42);
+    }
+
+    #[test]
+    fn it_could_be_incremented() {
+        let mut counter = Counter::new(0);
+        counter.increment(1);
+        assert_eq!(counter.value(), 1);
+
+        counter.increment(2);
+        assert_eq!(counter.value(), 3);
+    }
+
+    #[test]
+    fn it_serializes_to_prometheus() {
+        let counter = Counter::new(42);
+        assert_eq!(counter.to_prometheus(), "42");
+    }
+}

packages/metrics/src/counter.rs

@@ -0,0 +1,83 @@
+use derive_more::Display;
+use serde::{Deserialize, Serialize};
+
+use super::prometheus::PrometheusSerializable;
+
+#[derive(Debug, Display, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct Gauge(f64);
+
+impl Gauge {
+    #[must_use]
+    pub fn new(value: f64) -> Self {
+        Self(value)
+    }
+
+    #[must_use]
+    pub fn value(&self) -> f64 {
+        self.0
+    }
+
+    pub fn set(&mut self, value: f64) {
+        self.0 = value;
+    }
+}
+
+impl From<f64> for Gauge {
+    fn from(value: f64) -> Self {
+        Self(value)
+    }
+}
+
+impl From<Gauge> for f64 {
+    fn from(counter: Gauge) -> Self {
+        counter.value()
+    }
+}
+
+impl PrometheusSerializable for Gauge {
+    fn to_prometheus(&self) -> String {
+        format!("{}", self.value())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use approx::assert_relative_eq;
+
+    use super::*;
+
+    #[test]
+    fn it_should_be_created_from_integer_values() {
+        let gauge = Gauge::new(0.0);
+        assert_relative_eq!(gauge.value(), 0.0);
+    }
+
+    #[test]
+    fn it_could_be_converted_from_u64() {
+        let gauge: Gauge = 42.0.into();
+        assert_relative_eq!(gauge.value(), 42.0);
+    }
+
+    #[test]
+    fn it_could_be_converted_into_i64() {
+        let gauge = Gauge::new(42.0);
+        let value: f64 = gauge.into();
+        assert_relative_eq!(value, 42.0);
+    }
+
+    #[test]
+    fn it_could_be_set() {
+        let mut gauge = Gauge::new(0.0);
+        gauge.set(1.0);
+        assert_relative_eq!(gauge.value(), 1.0);
+    }
+
+    #[test]
+    fn it_serializes_to_prometheus() {
+        let counter = Gauge::new(42.0);
+        assert_eq!(counter.to_prometheus(), "42");
+
+        let counter = Gauge::new(42.1);
+        assert_eq!(counter.to_prometheus(), "42.1");
+    }
+}

packages/metrics/src/gauge.rs

@@ -0,0 +1,9 @@
+mod name;
+mod pair;
+mod set;
+mod value;
+
+pub type LabelName = name::LabelName;
+pub type LabelValue = value::LabelValue;
+pub type LabelPair = pair::LabelPair;
+pub type LabelSet = set::LabelSet;

packages/metrics/src/label/mod.rs

@@ -0,0 +1,117 @@
+use derive_more::Display;
+use serde::{Deserialize, Serialize};
+
+use crate::prometheus::PrometheusSerializable;
+
+#[derive(Debug, Display, Clone, Eq, PartialEq, Default, Deserialize, Serialize, Hash, Ord, PartialOrd)]
+pub struct LabelName(String);
+
+impl LabelName {
+    /// Creates a new `LabelName` instance.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the provided name is empty.
+    #[must_use]
+    pub fn new(name: &str) -> Self {
+        assert!(
+            !name.is_empty(),
+            "Label name cannot be empty. It must have at least one character."
+        );
+
+        Self(name.to_owned())
+    }
+}
+
+impl PrometheusSerializable for LabelName {
+    /// In Prometheus:
+    ///
+    /// - Labels may contain ASCII letters, numbers, as well as underscores.
+    ///   They must match the regex [a-zA-Z_][a-zA-Z0-9_]*.
+    /// - Label names beginning with __ (two "_") are reserved for internal
+    ///   use.
+    /// - Label values may contain any Unicode characters.
+    /// - Labels with an empty label value are considered equivalent to
+    ///   labels that do not exist.
+    ///
+    /// The label name is changed:
+    ///
+    /// - If a label name starts with, or contains, an invalid character:
+    ///   replace character with underscore.
+    /// - If th label name starts with two underscores:
+    ///   add additional underscore (three underscores total)
+    fn to_prometheus(&self) -> String {
+        // Replace invalid characters with underscore
+        let processed: String = self
+            .0
+            .chars()
+            .enumerate()
+            .map(|(i, c)| {
+                if i == 0 {
+                    if c.is_ascii_alphabetic() || c == '_' {
+                        c
+                    } else {
+                        '_'
+                    }
+                } else if c.is_ascii_alphanumeric() || c == '_' {
+                    c
+                } else {
+                    '_'
+                }
+            })
+            .collect();
+
+        // If the label name starts with two underscores, add an additional
+        if processed.starts_with("__") && !processed.starts_with("___") {
+            format!("_{processed}")
+        } else {
+            processed
+        }
+    }
+}
+#[cfg(test)]
+mod tests {
+    mod serialization_of_label_name_to_prometheus {
+        use rstest::rstest;
+
+        use crate::label::LabelName;
+        use crate::prometheus::PrometheusSerializable;
+
+        #[rstest]
+        #[case("1 valid name", "valid_name", "valid_name")]
+        #[case("2 leading underscore", "_leading_underscore", "_leading_underscore")]
+        #[case("3 leading lowercase", "v123", "v123")]
+        #[case("4 leading uppercase", "V123", "V123")]
+        fn valid_names_in_prometheus(#[case] case: &str, #[case] input: &str, #[case] output: &str) {
+            assert_eq!(LabelName::new(input).to_prometheus(), output, "{case} failed: {input:?}");
+        }
+
+        #[rstest]
+        #[case("1 invalid start 1", "9invalid_start", "_invalid_start")]
+        #[case("2 invalid start 2", "@test", "_test")]
+        #[case("3 invalid dash", "invalid-char", "invalid_char")]
+        #[case("4 invalid spaces", "spaces are bad", "spaces_are_bad")]
+        #[case("5 invalid special chars", "a!b@c#d$e%f^g&h*i(j)", "a_b_c_d_e_f_g_h_i_j_")]
+        #[case("6 invalid colon", "my:metric/version", "my_metric_version")]
+        #[case("7 all invalid characters", "!@#$%^&*()", "__________")]
+        #[case("8 non_ascii_characters", "ñaca©", "_aca_")]
+        fn names_that_need_changes_in_prometheus(#[case] case: &str, #[case] input: &str, #[case] output: &str) {
+            assert_eq!(LabelName::new(input).to_prometheus(), output, "{case} failed: {input:?}");
+        }
+
+        #[rstest]
+        #[case("1 double underscore start", "__private", "___private")]
+        #[case("2 double underscore only", "__", "___")]
+        #[case("3 processed to double underscore", "^^name", "___name")]
+        #[case("4 processed to double underscore after first char", "0__name", "___name")]
+        fn names_starting_with_double_underscore(#[case] case: &str, #[case] input: &str, #[case] output: &str) {
+            assert_eq!(LabelName::new(input).to_prometheus(), output, "{case} failed: {input:?}");
+        }
+
+        #[test]
+        #[should_panic(expected = "Label name cannot be empty. It must have at least one character.")]
+        fn empty_name() {
+            let _name = LabelName::new("");
+        }
+    }
+}