No bytes-evicted metric: eviction sweeps are only visible in logs (spec instrumentation item missing)

[matt-edmondson]

Plan reference

docs/superpowers/specs/2026-08-18-gitlfscache-design.md L222-L224

Instrumentation

System.Diagnostics.Metrics counters only, with no exporter dependency bundled: hits, misses, bytes served from cache, bytes fetched upstream, bytes evicted, coalesced waits, and verification failures.

The spec is marked implemented. Neither its As built section nor its Deferred section mentions dropping this counter.

What exists

• GitLfsCache/Observability/CacheMetrics.cs defines hits, misses, cache_bytes_served, upstream_bytes_fetched, upload_bytes_relayed, objects_stored, verification_failures, staging_failures, coalesced_waits, rejected_tokens, and the lock counters. There is no eviction counter.
• GitLfsCache/Storage/LeastRecentlyUsedEvictionPolicy.cs already returns an EvictionResult carrying EvictedCount, EvictedBytes, and SkippedCount.
• GitLfsCache/Storage/StoreMaintenanceService.cs (RunSweep) receives that result and only writes it to StoreLog.EvictedObjects. CacheMetrics is not injected into the service.

What's missing

Operators have no metric showing how much the cache is churning. The README's advice is to watch the hit ratio and enlarge the volume when it is low. Evicted bytes are the direct signal behind that advice: a store that evicts roughly what it fetches is too small for its working set, and today that can only be read out of logs.

Acceptance criteria

• CacheMetrics gains a gitlfscache.bytes_evicted counter (unit By), and probably an evicted-objects counter alongside it. It is tagged by upstream if that is practical; StoredObject carries Upstream, so the policy or the service can attribute bytes per upstream.
• StoreMaintenanceService (or the eviction policy) records to it after each sweep that deleted something.
• Optional: a counter for skipped deletions, so objects that can never be evicted show up.
• The README's "Health and metrics" counter list is updated.
• A unit test asserts that a sweep evicting N bytes adds N to the counter, for example with MetricCollector<long>.

Dependencies

None.

[matt-edmondson]

Triage

• Category: Improvement (a missing item from the spec's instrumentation list; nothing behaves incorrectly)
• Priority: Low. Eviction still works and is logged through StoreLog.EvictedObjects. What's missing is an operator signal for sizing the volume. It's worth doing because the README's sizing advice depends on it, but nothing is broken.
• Area / suggested assignment: Observability: GitLfsCache/Observability/CacheMetrics.cs and GitLfsCache/Storage/StoreMaintenanceService.cs (RunSweep).
• Duplicates: none found.
• In progress: no open PR in GitLfsCache covers this.

Suggested next step: this is a small, self-contained change. EvictionResult already carries EvictedCount/EvictedBytes/SkippedCount, so the work is to inject CacheMetrics into StoreMaintenanceService, add gitlfscache.bytes_evicted (plus an evicted-objects counter), record after each sweep, and test with MetricCollector<long>. The per-upstream tag is the only part that needs a decision. Attributing at the policy level, where StoredObject.Upstream is available, is cleaner than having the service re-derive it.

---

Generated by Claude Code