Skip to content

Instrument a cache

Create a Cache, then record each lookup with Hit or Miss:

cache, err := instrument.NewCache(mp.Meter("checkout"), "sessions")
if err != nil {
    return err
}
defer cache.Close()

value, ok := store.Get(ctx, key)
if ok {
    cache.Hit(ctx)
} else {
    cache.Miss(ctx)
}

Pass the request's context so that a lookup inside a sampled span carries an exemplar.

Report evictions, size and capacity

cache.Eviction(ctx, 3)
cache.SetSize(store.Len())
cache.SetCapacity(1024)

Eviction ignores an n below 1. SetSize and SetCapacity store the value for the next collect, so they take no context and are cheap to call often. Both read 0 until you first set them, and a capacity of 0 means unbounded.

Close it when the cache goes away

Call Close when the cache goes away. It unregisters the callback that reports size and capacity. A process that creates caches as it runs and never closes them leaks one callback each, for the life of the provider.

Use one name per cache

The name becomes the value of cache.name, and every distinct value is a new series, so keep names to a small fixed set, never a per-call value. RED, USE and cardinality says what happens otherwise.

Give each cache its own name per meter, because every metric carries that name as cache.name. Two caches sharing a name add their hits together and overwrite each other's size.

Read the signals

Signal Query
Hit ratio cache.operations{cache.result=hit} over all cache.operations
Eviction rate the rate of cache.evictions
Fullness cache.size over cache.capacity

Metric names lists every metric and its Prometheus counterpart.