Class CacheMetrics

java.lang.Object
com.loomcache.server.datastructures.CacheMetrics
public final class CacheMetrics extends Object
Thread-safe cache operation metrics.

Tracks hit/miss counts and eviction counts using LongAdder for high-throughput, low-contention counting with cache-friendly summary metrics.

Hit ratio = hits / (hits + misses). A ratio below 0.80 typically indicates the working set doesn't fit in the cache and the eviction policy or max-size should be tuned.

Thread Safety: All operations are atomic via LongAdder. Safe for concurrent access from multiple threads without synchronization.

Since:
1.0

  • Constructor Details

    • CacheMetrics

      public CacheMetrics()

  • Method Details

    • recordHit

      public void recordHit()
      Record a cache hit.

    • recordMiss

      public void recordMiss()
      Record a cache miss.

    • recordPut

      public void recordPut()
      Record a put operation.

    • recordRemoval

      public void recordRemoval()
      Record a removal operation.

    • recordEviction

      public void recordEviction()
      Record an eviction.

    • recordListenerFailure

      public void recordListenerFailure()
      Record a listener failure during event delivery.

    • recordWriteThroughFailure

      public void recordWriteThroughFailure()
      Record a write-through persistence failure. The in-memory PUT succeeded, but the write-through callback threw — the persisted store diverges from cache state. Operators should alert on a non-zero value.
      Since:
      1.1 (Round-9: previously silently swallowed)

    • recordDeleteThroughFailure

      public void recordDeleteThroughFailure()
      Record a delete-through persistence failure. The in-memory DELETE succeeded, but the delete-through callback threw — the persisted store diverges from cache state. Operators should alert on a non-zero value.
      Since:
      1.1 (Round-9: previously silently swallowed)

    • hitCount

      public long hitCount()
      Get the total number of cache hits.
      Returns:
      hit count

    • missCount

      public long missCount()
      Get the total number of cache misses.
      Returns:
      miss count

    • putCount

      public long putCount()
      Get the total number of put operations.
      Returns:
      put count

    • removalCount

      public long removalCount()
      Get the total number of removal operations.
      Returns:
      removal count

    • evictionCount

      public long evictionCount()
      Get the total number of evictions.
      Returns:
      eviction count

    • listenerFailureCount

      public long listenerFailureCount()
      Get the total number of listener failures.
      Returns:
      listener failure count

    • writeThroughFailureCount

      public long writeThroughFailureCount()
      Get the total number of write-through failures. A non-zero value means the cache's in-memory state is ahead of the backing store for at least that many writes; operators should alert.
      Returns:
      write-through failure count

    • deleteThroughFailureCount

      public long deleteThroughFailureCount()
      Get the total number of delete-through failures. A non-zero value means the cache's in-memory state is ahead of the backing store for at least that many deletes; operators should alert.
      Returns:
      delete-through failure count

    • hitRatio

      public double hitRatio()
      Calculate the cache hit ratio.

      Returns the ratio of hits / (hits + misses) in the range [0.0, 1.0]. A ratio below 0.80 indicates insufficient cache size for the working set.

      Returns:
      hit ratio, or 0.0 if no accesses have been recorded

    • reset

      public void reset()
      Reset all metric counters.

      Useful for periodic metric windows and testing. All counters (hits, misses, puts, removals, evictions, listener failures) are reset to zero.