Dix/metrics api (#56)

* refactor: streamline MetricsCell and enhance documentation

Removed the `new` method from `MetricsCell` to simplify its usage, as it is now directly initialized with a `Cell<u64>`. Updated the documentation for `metrics_impl.rs` to provide clearer insights into the metrics structures and their visibility, emphasizing the encapsulation of internal metrics management. Added concise summaries for each metrics struct to improve clarity and usability.

* feat: add serde support for cache metrics serialization

Introduced optional `serde` dependency for cache metrics snapshots, enabling serialization and deserialization of metrics structures. Enhanced documentation for `CacheMetricsSnapshot` and other metrics structs to clarify their purpose and usage, including examples demonstrating serialization capabilities. This change improves usability and facilitates integration with external systems requiring metrics data in a serialized format.

* docs: enhance metrics traits documentation with examples and clarity

Added example usage for `CoreMetricsRecorder` and its related traits, improving the documentation for cache metrics. Clarified the purpose of each metrics trait and their relationships, including references to mutable and read-only counterparts. This change enhances usability and understanding of the metrics system within the cache library.

* fix: update frequency buckets iteration method for accuracy

Replaced the `iter_entries` method with `iter` in the frequency buckets property tests to ensure accurate minimum frequency calculations. This change aligns with recent updates to the `FrequencyBuckets` module, enhancing consistency and correctness in the test implementation.

* docs: clarify MetricsCell usage in metrics_impl.rs

Updated the documentation for `MetricsCell` in `metrics_impl.rs` to include a direct reference to its location within the module. This change enhances clarity regarding the internal structure and visibility of the metrics management system, ensuring users understand the encapsulation of internal metrics management.

* docs: refine MetricsCell documentation in metrics_impl.rs

Updated the documentation for `MetricsCell` in `metrics_impl.rs` to remove redundant phrasing, enhancing clarity regarding its usage and visibility within the module. This change aims to improve understanding of the internal metrics management system.

Author: TKorr

Cargo.lock

@@ -35,6 +35,7 @@ crate-type = ["lib"]
 [features]
 default = ["policy-s3-fifo", "policy-lru", "policy-fast-lru", "policy-lru-k", "policy-clock"]
 metrics = []
+serde = ["dep:serde"]
 concurrency = ["parking_lot"]
 
 # Eviction policy feature flags. Enable only the policies you need for smaller builds.
@@ -81,6 +82,7 @@ policy-nru = []
 [dependencies]
 parking_lot = { version = "0.12", optional = true }
 rustc-hash = "2.1"
+serde = { version = "1", features = ["derive"], optional = true }
 
 [dev-dependencies]
 bench-support = { path = "bench-support" }

Cargo.toml

@@ -101,7 +101,7 @@ fn test_min_freq_accuracy(data: &[u8]) {
 
         // Compute actual minimum frequency
         let mut actual_min: Option<u64> = None;
-        for (_, meta) in buckets.iter_entries() {
+        for (_, meta) in buckets.iter() {
             actual_min = match actual_min {
                 None => Some(meta.freq),
                 Some(min) => Some(min.min(meta.freq)),

fuzz/fuzz_targets/frequency_buckets_property_tests.rs

@@ -9,11 +9,6 @@ use std::cell::Cell;
 pub(crate) struct MetricsCell(Cell<u64>);
 
 impl MetricsCell {
-    #[inline]
-    pub fn new() -> Self {
-        Self(Cell::new(0))
-    }
-
     #[inline]
     pub fn get(&self) -> u64 {
         self.0.get()

src/metrics/cell.rs

@@ -1,3 +1,16 @@
+//! Concrete metrics recorders for each eviction policy.
+//!
+//! Each struct accumulates lightweight counters that the corresponding policy
+//! increments on its hot path. The [`snapshot`](super::snapshot) module provides
+//! read-only, `Copy` snapshots of these counters for bench/test consumption,
+//! while [`exporter`](super::exporter) publishes them to monitoring backends.
+//!
+//! ## Field visibility
+//!
+//! Fields backed by plain `u64` are `pub` for direct reads.
+//! Fields that require interior mutability (recorded through `&self` on read
+//! paths) use the crate-internal `MetricsCell` and are `pub(crate)`.
+
 use crate::metrics::cell::MetricsCell;
 use crate::metrics::traits::{
     ArcMetricsRecorder, CarMetricsRecorder, ClockMetricsRecorder, ClockProMetricsRecorder,
@@ -7,7 +20,8 @@ use crate::metrics::traits::{
     S3FifoMetricsRecorder, SlruMetricsRecorder, TwoQMetricsRecorder,
 };
 
-#[derive(Debug, Default)]
+/// FIFO / insertion-order cache metrics.
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct CacheMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -29,7 +43,8 @@ pub struct CacheMetrics {
     pub(crate) age_rank_found: MetricsCell,
 }
 
-#[derive(Debug, Default)]
+/// LRU (least-recently-used) cache metrics.
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct LruMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -50,7 +65,8 @@ pub struct LruMetrics {
     pub(crate) recency_rank_scan_steps: MetricsCell,
 }
 
-#[derive(Debug, Default)]
+/// LFU (least-frequently-used) cache metrics.
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct LfuMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -72,7 +88,8 @@ pub struct LfuMetrics {
     pub increment_frequency_found: u64,
 }
 
-#[derive(Debug, Default)]
+/// LRU-K (K-distance) cache metrics.
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct LruKMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -102,31 +119,6 @@ pub struct LruKMetrics {
     pub(crate) k_distance_rank_scan_steps: MetricsCell,
 }
 
-impl CacheMetrics {
-    pub fn new() -> CacheMetrics {
-        Self {
-            get_calls: 0,
-            get_hits: 0,
-            get_misses: 0,
-            insert_calls: 0,
-            insert_updates: 0,
-            insert_new: 0,
-            evict_calls: 0,
-            evicted_entries: 0,
-            stale_skips: 0,
-            evict_scan_steps: 0,
-            pop_oldest_calls: 0,
-            pop_oldest_found: 0,
-            pop_oldest_empty_or_stale: 0,
-            peek_oldest_calls: MetricsCell::new(),
-            peek_oldest_found: MetricsCell::new(),
-            age_rank_calls: MetricsCell::new(),
-            age_rank_scan_steps: MetricsCell::new(),
-            age_rank_found: MetricsCell::new(),
-        }
-    }
-}
-
 impl CoreMetricsRecorder for CacheMetrics {
     fn record_get_hit(&mut self) {
         self.get_calls += 1;
@@ -185,6 +177,7 @@ impl FifoMetricsRecorder for CacheMetrics {
     }
 }
 
+#[doc(hidden)]
 impl FifoMetricsReadRecorder for &CacheMetrics {
     fn record_peek_oldest_call(&self) {
         self.peek_oldest_calls.incr();
@@ -279,6 +272,7 @@ impl LruMetricsRecorder for LruMetrics {
     }
 }
 
+#[doc(hidden)]
 impl LruMetricsReadRecorder for &LruMetrics {
     fn record_peek_lru_call(&self) {
         self.peek_lru_calls.incr();
@@ -377,6 +371,7 @@ impl LfuMetricsRecorder for LfuMetrics {
     }
 }
 
+#[doc(hidden)]
 impl LfuMetricsReadRecorder for &LfuMetrics {
     fn record_peek_lfu_call(&self) {
         self.peek_lfu_calls.incr();
@@ -505,6 +500,7 @@ impl LruKMetricsRecorder for LruKMetrics {
     }
 }
 
+#[doc(hidden)]
 impl LruKMetricsReadRecorder for &LruKMetrics {
     fn record_peek_lru_k_call(&self) {
         self.peek_lru_k_calls.incr();
@@ -535,11 +531,8 @@ impl LruKMetricsReadRecorder for &LruKMetrics {
     }
 }
 
-// ---------------------------------------------------------------------------
-// CoreOnlyMetrics (LIFO, Random)
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default)]
+/// Minimal metrics for policies with no policy-specific counters (LIFO, Random).
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct CoreOnlyMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -578,11 +571,8 @@ impl CoreMetricsRecorder for CoreOnlyMetrics {
     fn record_clear(&mut self) {}
 }
 
-// ---------------------------------------------------------------------------
-// ArcMetrics
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default)]
+/// ARC (adaptive replacement cache) metrics.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct ArcMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -652,11 +642,8 @@ impl ArcMetricsRecorder for ArcMetrics {
     }
 }
 
-// ---------------------------------------------------------------------------
-// CarMetrics
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default)]
+/// CAR (clock with adaptive replacement) metrics.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct CarMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -722,11 +709,8 @@ impl CarMetricsRecorder for CarMetrics {
     }
 }
 
-// ---------------------------------------------------------------------------
-// ClockMetrics
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default)]
+/// Clock (second-chance) cache metrics.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct ClockMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -776,11 +760,8 @@ impl ClockMetricsRecorder for ClockMetrics {
     }
 }
 
-// ---------------------------------------------------------------------------
-// ClockProMetrics
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default)]
+/// Clock-PRO (adaptive hot/cold/test clock) metrics.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct ClockProMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -838,11 +819,8 @@ impl ClockProMetricsRecorder for ClockProMetrics {
     }
 }
 
-// ---------------------------------------------------------------------------
-// MfuMetrics
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default)]
+/// MFU (most-frequently-used eviction) metrics.
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct MfuMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -908,6 +886,7 @@ impl MfuMetricsRecorder for MfuMetrics {
     }
 }
 
+#[doc(hidden)]
 impl MfuMetricsReadRecorder for &MfuMetrics {
     fn record_peek_mfu_call(&self) {
         self.peek_mfu_calls.incr();
@@ -923,11 +902,8 @@ impl MfuMetricsReadRecorder for &MfuMetrics {
     }
 }
 
-// ---------------------------------------------------------------------------
-// NruMetrics
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default)]
+/// NRU (not-recently-used) cache metrics.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct NruMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -977,11 +953,8 @@ impl NruMetricsRecorder for NruMetrics {
     }
 }
 
-// ---------------------------------------------------------------------------
-// SlruMetrics
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default)]
+/// SLRU (segmented LRU) cache metrics.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct SlruMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -1031,11 +1004,8 @@ impl SlruMetricsRecorder for SlruMetrics {
     }
 }
 
-// ---------------------------------------------------------------------------
-// TwoQMetrics
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default)]
+/// Two-Q (A1in/A1out/Am queue) cache metrics.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct TwoQMetrics {
     pub get_calls: u64,
     pub get_hits: u64,
@@ -1085,11 +1055,8 @@ impl TwoQMetricsRecorder for TwoQMetrics {
     }
 }
 
-// ---------------------------------------------------------------------------
-// S3FifoMetrics
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Default, Clone)]
+/// S3-FIFO (small/main/ghost queue) cache metrics.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct S3FifoMetrics {
     pub get_calls: u64,
     pub get_hits: u64,