Merge #1540: Overhaul stats: Persist all torrents downloads metric

4febda4 fic: [#1539] persisten metrics should be enabled by config (Jose Celano)
2c9311b test: [#1539] add integration test for persisted downloads counter (Jose Celano)
c07f366 feat: [#1539] load global downloads counter from DB (Jose Celano)
9301e58 feat: [#1539] save global downloads counter in DB (Jose Celano)
6f11534 feat: [#1539] add method to Database trait to persis global downloads counter (Jose Celano)

Pull request description:

  Persist "all torrent downloads" metric.

  ### Subtasks

  - [x] Add new methods to the `Database` trait.
  - [x] Make use of the new methods to persist the metric `TRACKER_CORE_PERSISTENT_TORRENTS_DOWNLOADS_TOTAL`.
  - [x] Add an integration test.

ACKs for top commit:
  josecelano:
    ACK 4febda4

Tree-SHA512: f2d316361048a368fdf23da4ad5550b2c27544b589fe03f55bae3174e206e1a76b53d1ad5f586e49e2731a738d49c0e3b7d6cc4dda1b7feb936b321d620d8d2c

Author: josecelano

packages/metrics/src/counter.rs

@@ -20,6 +20,10 @@ impl Counter {
     pub fn increment(&mut self, value: u64) {
         self.0 += value;
     }
+
+    pub fn absolute(&mut self, value: u64) {
+        self.0 = value;
+    }
 }
 
 impl From<u64> for Counter {
@@ -73,6 +77,13 @@ mod tests {
         assert_eq!(counter.value(), 3);
     }
 
+    #[test]
+    fn it_could_set_to_an_absolute_value() {
+        let mut counter = Counter::new(0);
+        counter.absolute(1);
+        assert_eq!(counter.value(), 1);
+    }
+
     #[test]
     fn it_serializes_to_prometheus() {
         let counter = Counter::new(42);

packages/metrics/src/metric/mod.rs

@@ -55,6 +55,10 @@ impl Metric<Counter> {
     pub fn increment(&mut self, label_set: &LabelSet, time: DurationSinceUnixEpoch) {
         self.sample_collection.increment(label_set, time);
     }
+
+    pub fn absolute(&mut self, label_set: &LabelSet, value: u64, time: DurationSinceUnixEpoch) {
+        self.sample_collection.absolute(label_set, value, time);
+    }
 }
 
 impl Metric<Gauge> {

packages/metrics/src/metric_collection.rs

@@ -72,6 +72,8 @@ impl MetricCollection {
         self.counters.get_value(name, label_set)
     }
 
+    /// Increases the counter for the given metric name and labels.
+    ///
     /// # Errors
     ///
     /// Return an error if a metrics of a different type with the same name
@@ -93,6 +95,30 @@ impl MetricCollection {
         Ok(())
     }
 
+    /// Sets the counter for the given metric name and labels.
+    ///
+    /// # Errors
+    ///
+    /// Return an error if a metrics of a different type with the same name
+    /// already exists.
+    pub fn set_counter(
+        &mut self,
+        name: &MetricName,
+        label_set: &LabelSet,
+        value: u64,
+        time: DurationSinceUnixEpoch,
+    ) -> Result<(), Error> {
+        if self.gauges.metrics.contains_key(name) {
+            return Err(Error::MetricNameCollisionAdding {
+                metric_name: name.clone(),
+            });
+        }
+
+        self.counters.absolute(name, label_set, value, time);
+
+        Ok(())
+    }
+
     pub fn ensure_counter_exists(&mut self, name: &MetricName) {
         self.counters.ensure_metric_exists(name);
     }
@@ -361,7 +387,7 @@ impl MetricKindCollection<Counter> {
     ///
     /// # Panics
     ///
-    /// Panics if the metric does not exist and it could not be created.
+    /// Panics if the metric does not exist.
     pub fn increment(&mut self, name: &MetricName, label_set: &LabelSet, time: DurationSinceUnixEpoch) {
         self.ensure_metric_exists(name);
 
@@ -370,6 +396,21 @@ impl MetricKindCollection<Counter> {
         metric.increment(label_set, time);
     }
 
+    /// Sets the counter to an absolute value for the given metric name and labels.
+    ///
+    /// If the metric name does not exist, it will be created.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the metric does not exist.
+    pub fn absolute(&mut self, name: &MetricName, label_set: &LabelSet, value: u64, time: DurationSinceUnixEpoch) {
+        self.ensure_metric_exists(name);
+
+        let metric = self.metrics.get_mut(name).expect("Counter metric should exist");
+
+        metric.absolute(label_set, value, time);
+    }
+
     #[must_use]
     pub fn get_value(&self, name: &MetricName, label_set: &LabelSet) -> Option<Counter> {
         self.metrics

packages/metrics/src/sample.rs

@@ -122,6 +122,11 @@ impl Measurement<Counter> {
         self.value.increment(1);
         self.set_recorded_at(time);
     }
+
+    pub fn absolute(&mut self, value: u64, time: DurationSinceUnixEpoch) {
+        self.value.absolute(value);
+        self.set_recorded_at(time);
+    }
 }
 
 impl Measurement<Gauge> {

packages/metrics/src/sample_collection.rs

@@ -79,6 +79,15 @@ impl SampleCollection<Counter> {
 
         sample.increment(time);
     }
+
+    pub fn absolute(&mut self, label_set: &LabelSet, value: u64, time: DurationSinceUnixEpoch) {
+        let sample = self
+            .samples
+            .entry(label_set.clone())
+            .or_insert_with(|| Measurement::new(Counter::default(), time));
+
+        sample.absolute(value, time);
+    }
 }
 
 impl SampleCollection<Gauge> {

packages/tracker-core/migrations/mysql/20240730183000_torrust_tracker_create_all_tables.sql

@@ -4,6 +4,7 @@ CREATE TABLE
         info_hash VARCHAR(40) NOT NULL UNIQUE
     );
 
+# todo: rename to `torrent_metrics`
 CREATE TABLE
     IF NOT EXISTS torrents (
         id integer PRIMARY KEY AUTO_INCREMENT,

packages/tracker-core/migrations/mysql/20250527093000_torrust_tracker_new_torrent_aggregate_metrics_table.sql

@@ -0,0 +1,6 @@
+CREATE TABLE
+    IF NOT EXISTS torrent_aggregate_metrics (
+        id integer PRIMARY KEY AUTO_INCREMENT,
+        metric_name VARCHAR(50) NOT NULL UNIQUE,
+        value INTEGER DEFAULT 0 NOT NULL
+    );

packages/tracker-core/migrations/sqlite/20240730183000_torrust_tracker_create_all_tables.sql

@@ -4,6 +4,7 @@ CREATE TABLE
         info_hash TEXT NOT NULL UNIQUE
     );
 
+# todo: rename to `torrent_metrics`
 CREATE TABLE
     IF NOT EXISTS torrents (
         id INTEGER PRIMARY KEY AUTOINCREMENT,

packages/tracker-core/migrations/sqlite/20250527093000_torrust_tracker_new_torrent_aggregate_metrics_table.sql

@@ -0,0 +1,6 @@
+CREATE TABLE
+    IF NOT EXISTS torrent_aggregate_metrics (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        metric_name TEXT NOT NULL UNIQUE,
+        value INTEGER DEFAULT 0 NOT NULL
+    );

packages/tracker-core/src/databases/driver/mod.rs

@@ -6,6 +6,9 @@ use sqlite::Sqlite;
 use super::error::Error;
 use super::Database;
 
+/// Metric name in DB for the total number of downloads across all torrents.
+const TORRENTS_DOWNLOADS_TOTAL: &str = "torrents_downloads_total";
+
 /// The database management system used by the tracker.
 ///
 /// Refer to:
@@ -97,9 +100,14 @@ pub(crate) mod tests {
 
         // Persistent torrents (stats)
 
+        // Torrent metrics
         handling_torrent_persistence::it_should_save_and_load_persistent_torrents(driver);
         handling_torrent_persistence::it_should_load_all_persistent_torrents(driver);
         handling_torrent_persistence::it_should_increase_the_number_of_downloads_for_a_given_torrent(driver);
+        // Aggregate metrics for all torrents
+        handling_torrent_persistence::it_should_save_and_load_the_global_number_of_downloads(driver);
+        handling_torrent_persistence::it_should_load_the_global_number_of_downloads(driver);
+        handling_torrent_persistence::it_should_increase_the_global_number_of_downloads(driver);
 
         // Authentication keys (for private trackers)
 
@@ -154,6 +162,8 @@ pub(crate) mod tests {
         use crate::databases::Database;
         use crate::test_helpers::tests::sample_info_hash;
 
+        // Metrics per torrent
+
         pub fn it_should_save_and_load_persistent_torrents(driver: &Arc<Box<dyn Database>>) {
             let infohash = sample_info_hash();
 
@@ -192,6 +202,40 @@ pub(crate) mod tests {
 
             assert_eq!(number_of_downloads, 2);
         }
+
+        // Aggregate metrics for all torrents
+
+        pub fn it_should_save_and_load_the_global_number_of_downloads(driver: &Arc<Box<dyn Database>>) {
+            let number_of_downloads = 1;
+
+            driver.save_global_number_of_downloads(number_of_downloads).unwrap();
+
+            let number_of_downloads = driver.load_global_number_of_downloads().unwrap().unwrap();
+
+            assert_eq!(number_of_downloads, 1);
+        }
+
+        pub fn it_should_load_the_global_number_of_downloads(driver: &Arc<Box<dyn Database>>) {
+            let number_of_downloads = 1;
+
+            driver.save_global_number_of_downloads(number_of_downloads).unwrap();
+
+            let number_of_downloads = driver.load_global_number_of_downloads().unwrap().unwrap();
+
+            assert_eq!(number_of_downloads, 1);
+        }
+
+        pub fn it_should_increase_the_global_number_of_downloads(driver: &Arc<Box<dyn Database>>) {
+            let number_of_downloads = 1;
+
+            driver.save_global_number_of_downloads(number_of_downloads).unwrap();
+
+            driver.increase_global_number_of_downloads().unwrap();
+
+            let number_of_downloads = driver.load_global_number_of_downloads().unwrap().unwrap();
+
+            assert_eq!(number_of_downloads, 2);
+        }
     }
 
     mod handling_authentication_keys {