feat: add lean_tick_interval_duration_seconds metric (lambdaclass#352)

closes lambdaclass#350

## 🗒️ Description / Motivation

Adds the `lean_tick_interval_duration_seconds` metric as defined in
leanMetrics PR
[lambdaclass#34](leanEthereum/leanMetrics#34). This tracks
the scheduling interval of the blockchain server loop.

## What Changed

* `crates/blockchain/src/lib.rs`: Added `last_tick_instant:
Option<Instant>` to `BlockChainServer` to measure elapsed time at the
top of `on_tick`.
* `crates/blockchain/src/metrics.rs`: Registered the histogram with
buckets from the spec.
* `docs/metrics.md`: Added the new metric to the documentation.

## Correctness / Behavior Guarantees

* Uses `std::time::Instant` (monotonic clock) rather than `SystemTime`
to avoid wall-clock/NTP drift bugs.
* Skips observation on the first tick.

## Tests Added / Run

* Ran `cargo test -p ethlambda-blockchain --lib` (19 passed).

## ✅ Verification Checklist

* [x] Ran `make fmt` — clean
* [x] Ran `make lint` (clippy with `-D warnings`) — clean

---------

Co-authored-by: Tomás Grüner <47506558+MegaRedHand@users.noreply.github.com>

Author: Andrurachi

crates/blockchain/src/lib.rs

@@ -1,5 +1,5 @@
 use std::collections::{HashMap, HashSet, VecDeque};
-use std::time::{Duration, SystemTime};
+use std::time::{Duration, Instant, SystemTime};
 
 use ethlambda_network_api::{BlockChainToP2PRef, InitP2P};
 use ethlambda_state_transition::is_proposer;
@@ -73,6 +73,7 @@ impl BlockChain {
             aggregator,
             pending_block_parents: HashMap::new(),
             current_aggregation: None,
+            last_tick_instant: None,
         }
         .start();
         let time_until_genesis = (SystemTime::UNIX_EPOCH + Duration::from_secs(genesis_time))
@@ -123,10 +124,19 @@ pub struct BlockChainServer {
     /// worker started at the most recent interval 2 is still running or until
     /// the next interval 2 takes over.
     current_aggregation: Option<AggregationSession>,
+
+    /// Last tick instant for measuring interval duration.
+    last_tick_instant: Option<Instant>,
 }
 
 impl BlockChainServer {
     async fn on_tick(&mut self, timestamp_ms: u64, ctx: &Context<Self>) {
+        // Observe tick interval duration before any processing
+        if let Some(prev_instant) = self.last_tick_instant {
+            metrics::observe_tick_interval_duration(prev_instant.elapsed());
+        }
+        self.last_tick_instant = Some(Instant::now());
+
         let genesis_time_ms = self.store.config().genesis_time * 1000;
 
         // Calculate current slot and interval from milliseconds

crates/blockchain/src/metrics.rs

@@ -1,5 +1,7 @@
 //! Prometheus metrics for the blockchain module.
 
+use std::time::Duration;
+
 use ethlambda_metrics::*;
 
 // --- Gauges ---
@@ -305,6 +307,18 @@ static LEAN_FORK_CHOICE_REORG_DEPTH: std::sync::LazyLock<Histogram> =
         .unwrap()
     });
 
+static LEAN_TICK_INTERVAL_DURATION_SECONDS: std::sync::LazyLock<Histogram> =
+    std::sync::LazyLock::new(|| {
+        register_histogram!(
+            "lean_tick_interval_duration_seconds",
+            "Elapsed time between clock ticks in seconds",
+            vec![
+                0.4, 0.6, 0.75, 0.8, 0.805, 0.81, 0.815, 0.82, 0.825, 0.85, 0.9, 1.0, 1.2, 1.6
+            ]
+        )
+        .unwrap()
+    });
+
 // --- Block Production ---
 
 static LEAN_BLOCK_AGGREGATED_PAYLOADS: std::sync::LazyLock<Histogram> =
@@ -417,6 +431,7 @@ pub fn init() {
     std::sync::LazyLock::force(&LEAN_COMMITTEE_SIGNATURES_AGGREGATION_TIME_SECONDS);
     std::sync::LazyLock::force(&LEAN_AGGREGATED_PROOF_SIZE_BYTES);
     std::sync::LazyLock::force(&LEAN_FORK_CHOICE_REORG_DEPTH);
+    std::sync::LazyLock::force(&LEAN_TICK_INTERVAL_DURATION_SECONDS);
     // Block production
     std::sync::LazyLock::force(&LEAN_BLOCK_AGGREGATED_PAYLOADS);
     std::sync::LazyLock::force(&LEAN_BLOCK_BUILDING_PAYLOAD_AGGREGATION_TIME_SECONDS);
@@ -599,6 +614,11 @@ pub fn observe_fork_choice_reorg_depth(depth: u64) {
     LEAN_FORK_CHOICE_REORG_DEPTH.observe(depth as f64);
 }
 
+/// Observe the duration between consecutive tick intervals in seconds.
+pub fn observe_tick_interval_duration(duration: Duration) {
+    LEAN_TICK_INTERVAL_DURATION_SECONDS.observe(duration.as_secs_f64());
+}
+
 /// Observe the number of aggregated payloads in a built block.
 pub fn observe_block_aggregated_payloads(count: usize) {
     LEAN_BLOCK_AGGREGATED_PAYLOADS.observe(count as f64);

docs/metrics.md

@@ -43,6 +43,7 @@ The exposed metrics follow [the leanMetrics specification](https://github.com/le
 |`lean_attestation_validation_time_seconds`| Histogram | Time taken to validate attestation | On validate attestation | | 0.005, 0.01, 0.025, 0.05, 0.1, 1 | ✅ |
 | `lean_fork_choice_reorgs_total` | Counter | Total number of fork choice reorgs | On fork choice reorg | | | ✅ |
 | `lean_fork_choice_reorg_depth` | Histogram | Depth of fork choice reorgs (in blocks) | On fork choice reorg | | 1, 2, 3, 5, 7, 10, 20, 30, 50, 100 | ✅ |
+| `lean_tick_interval_duration_seconds` | Histogram | Elapsed time between clock ticks in seconds | At the start of each tick interval | | 0.4, 0.6, 0.75, 0.8, 0.805, 0.81, 0.815, 0.82, 0.825, 0.85, 0.9, 1.0, 1.2, 1.6 | ✅ |
 | `lean_gossip_signatures` | Gauge | Number of gossip signatures in fork-choice store | On gossip signatures update | | | ✅ |
 | `lean_latest_new_aggregated_payloads` | Gauge | Number of new aggregated payload items | On `latest_new_aggregated_payloads` update | | | ✅ |
 | `lean_latest_known_aggregated_payloads` | Gauge | Number of known aggregated payload items | On `latest_known_aggregated_payloads` update | | | ✅ |