ZerdaZerda

cache.cache_metrics

On this page

CacheMetrics

Python · 12 lines
@dataclass
class CacheMetrics:
    l1_hits: int = 0
    l2_hits: int = 0
    l3_hits: int = 0
    l1_misses: int = 0
    l2_misses: int = 0
    l3_misses: int = 0
    sets: int = 0
    evictions: int = 0
    promotions: int = 0
    expirations: int = 0

Overview

A simple, per-level hit/miss counter dataclass used exclusively by MultiLevelCache (self.metrics). This is distinct from — and much simpler than — CacheMetricsCollector, which serves the semantic-cache pipeline and adds latency histograms, cost tracking, and RL reward statistics.

Methods

MethodEffect
record_get(level: int, hit: bool) -> NoneIncrements l{level}_hits or l{level}_misses depending on hit, for level in {1, 2, 3} (any other value is silently ignored — no else branch)
record_set() -> Nonesets += 1
record_eviction() -> Noneevictions += 1
record_promotion() -> Nonepromotions += 1
record_expiration() -> Noneexpirations += 1
get_hit_rate(level: Optional[int] = None) -> floatHit rate for a specific level (1/2/3), or overall if level=None; returns 0.0 if the relevant total is 0 (avoids ZeroDivisionError)
get_stats() -> dictReturns a dict with every raw counter, total_hits, total_misses, l1/l2/l3_hit_rate, and overall_hit_rate
reset() -> NoneZeroes every counter

get_hit_rate() details

Python · 10 lines
def get_hit_rate(self, level: Optional[int] = None) -> float:
    if level == 1:
        total = self.l1_hits + self.l1_misses
        return self.l1_hits / total if total > 0 else 0.0
    elif level == 2: ...
    elif level == 3: ...
    else:
        total_hits = self.l1_hits + self.l2_hits + self.l3_hits
        total_gets = total_hits + self.l1_misses + self.l2_misses + self.l3_misses
        return total_hits / total_gets if total_gets > 0 else 0.0

Passing any level value other than 1, 2, 3, or None falls through to the else branch (the overall rate) — there is no validation or ValueError for out-of-range levels.

Examples

Python · 10 lines
from zerda.cache import CacheMetrics

m = CacheMetrics()
m.record_get(1, hit=False)
m.record_get(1, hit=True)
m.record_set()
print(m.get_hit_rate(1))        # 0.5
print(m.get_stats()["sets"])    # 1
m.reset()
print(m.get_hit_rate())         # 0.0 (no data)

Complexity

Every method is O(1).

Thread Safety

CacheMetrics has no internal locking of its own. It is safe only because its sole consumer, MultiLevelCache, always calls its methods while holding MultiLevelCache.lock. Using a CacheMetrics instance directly from multiple threads without external synchronization is not safe.

Related pages