No lock snapshot-size metric: operators can't see how close a repository is to MaxSnapshotLocks (spec instrumentation item missing)

[matt-edmondson]

Plan

docs/superpowers/specs/2026-08-19-locks-subsystem-design.md#L236-L238

New counters on the existing ktsu.GitLfsCache meter: lock list hits, lock list refreshes, refresh failures, admission probes, admission rejections, fan-out items attempted, fan-out items succeeded, fan-out throttle pauses, and snapshot size.

What exists today

GitLfsCache/Observability/CacheMetrics.cs:67-75 defines every counter in that list except snapshot size. There is no snapshot_size instrument anywhere under GitLfsCache/.

What's missing

Nothing records how many locks a published snapshot holds, so operators can't see:

• how close a repository is to Locks:MaxSnapshotLocks, the point where it silently stops being cached (see A repository with more locks than MaxSnapshotLocks is re-walked up to the ceiling on every GET locks, then relayed anyway #65);
• how much snapshot memory is held (see Lock-list snapshots are never evicted: every distinct (repository, refspec) keeps a full lock list in memory for the life of the process #50).

Acceptance criteria

• A histogram (or an observable gauge per repository), e.g. gitlfscache.lock_snapshot_size, tagged by upstream and recorded each time a snapshot is published.
• A walk rejected as TooLarge records its count too, or through a companion counter, so the over-limit case is visible.
• A test asserts that the measurement is recorded on publish.

Dependencies

None.

[matt-edmondson]

Triage

• Category: Feature Request. This is an observability item the spec lists but the code doesn't have yet.
• Priority: Low. Nothing is broken. It makes A repository with more locks than MaxSnapshotLocks is re-walked up to the ceiling on every GET locks, then relayed anyway #65 (repositories over MaxSnapshotLocks) and Lock-list snapshots are never evicted: every distinct (repository, refspec) keeps a full lock list in memory for the life of the process #50 (snapshot memory) visible to operators.
• Area / suggested assignee: Observability (Observability/CacheMetrics.cs) and the lock snapshot publish path, @matt-edmondson.
• Duplicates: None.
• In progress: No open PR covers it.
• Notes: This is a small, self-contained change. Doing it alongside A repository with more locks than MaxSnapshotLocks is re-walked up to the ceiling on every GET locks, then relayed anyway #65 lets the metric verify that fix.

---

Generated by Claude Code