Struct Metrics 

pub struct Metrics { /* private fields */ }

The telemetry engine for the cache, providing high-concurrency event tracking.

Metrics is designed to be owned by the cache and serves as a thread-safe sink for all operational telemetry. It supports high-frequency invocation across multiple threads by utilizing a sharded, lock-free architecture.

Concurrency & Multi-Threaded Ownership

Although owned by a single cache instance, Metrics is designed to be accessed through shared references (&self) across all threads interacting with the cache. It leverages internal mutability via atomics to allow concurrent updates without requiring a Mutex or RwLock at the cache level.

Throughput Scalability

To prevent metrics from becoming a point of contention in multi-core environments, writes are distributed across independent [MetricsStorage] shards. A thread-local affinity mechanism maps worker threads to specific shards, localizing atomic increments and minimizing cross-core synchronization overhead.

Cache-Line Isolation

Each shard is explicitly wrapped in CachePadded to ensure it occupies unique cache lines. This physical isolation prevents “false sharing,” where unrelated updates to different shards would otherwise trigger expensive CPU cache-coherency protocols and degrade cache performance.

Operational Profile

• Wait-Free Writes: All recording operations are wait-free, ensuring telemetry collection never blocks cache lookups or insertions.
• Eventually Consistent Snapshots: The [snapshot()] method provides a point-in-time aggregation of all shards. While snapshots are linear in complexity relative to shard count, recording remains $O(1)$.

Implementations

impl Metrics

pub fn new(config: MetricsConfig) -> Self

Initializes the metrics engine with sharded storage.

pub fn record_hit(&self)

Increments the cache hit counter for the current thread’s assigned shard.

Concurrency

This is a wait-free $O(1)$ operation. It uses Relaxed atomic ordering, providing high throughput at the cost of strict sequential consistency.

pub fn record_miss(&self)

Increments the cache miss counter for the current thread’s assigned shard.

Concurrency

This is a wait-free $O(1)$ operation. It uses Relaxed atomic ordering, ensuring that telemetry collection does not stall cache lookups.

pub fn record_eviction(&self)

Records a cache entry eviction for the current thread’s assigned shard.

This should be invoked whenever an item is removed from the cache to satisfy capacity constraints.

pub fn record_latency(&self, latency: u64)

Records a latency measurement into the sampler assigned to the current thread’s shard.

This method captures execution timing (e.g., lookup duration or insertion time) without blocking the calling thread or incurring the overhead of a global lock.

Concurrency & Progress

This is a wait-free operation. It utilizes a thread-local shard lookup followed by an atomic fetch-and-add on the shard’s write cursor. This ensures that even under extreme write contention, every thread makes independent progress.

Sampling Behavior

Latency is recorded into a lossy, circular buffer (Sampler). If the buffer for the current shard is full, the oldest sample is overwritten. This “lossy” property is a deliberate design choice to bound memory usage and prioritize write throughput over absolute data retention.

Arguments

• latency - The raw timing value to record. Units (ns, us, ms) should remain consistent across all calls. A value of 0 is ignored during the [snapshot()] aggregation to prevent uninitialized data from skewing percentiles.

pub fn snapshot(&self) -> MetricsSnapshot

Performs a non-destructive aggregation of all sharded metrics into a consistent MetricsSnapshot.

Performance

This method is $O(S + N)$, where $S$ is the number of shards and $N$ is the total capacity of the latency samplers. Because it iterates over all shards and populates an [HdrHistogram], it is significantly more expensive than recording methods and should typically be called from a background reporting thread.

Consistency

The snapshot provides a point-in-time view. However, because shards are read sequentially without a global lock, the snapshot may not represent a single atomic instant across the entire cache. This is a standard trade-off in high-performance telemetry systems.

Trait Implementations

impl Debug for Metrics

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Metrics

fn default() -> Self

Returns the “default value” for a type.

impl From<&Metrics> for MetricsSnapshot

fn from(metrics: &Metrics) -> Self

Converts to this type from the input type.