A metrics gauge counts entries by ranging a sync.Map — why is that count never exactly right?

## Why there is no Len The missing `Len` is not an oversight. Ask what such a method could honestly return on a map that any number of goroutines may be mutating: a number that was true at some instant during the call and is potentially false by the time the caller sees it. Maintaining it would also mean a shared counter updated on every insert and delete — a contention point on the very operations `sync.Map` exists to keep cheap, imposed on every user whether they want a size or not. So the type simply does not offer one, and the API forces you to be explicit about what kind of count you actually want. ## What Range does and does not promise `Range(f func(key, value any) bool)` calls `f` for each entry, and stops early if `f` returns `false`. The guarantees are narrow and worth memorising: - **No key is visited more than once.** That is the strong guarantee. - **There is no consistent snapshot.** The walk does not correspond to the contents of the map at any single moment. - **Range does not block the map's other methods.** Other goroutines keep storing and deleting while you iterate, and `f` itself may call any method on the same map, including deleting the entry it was just handed. - **A key mutated during the walk may be observed in any state it held during the call** — the old value, the new value, or not at all if it was deleted before the walk reached it. This is a deliberate trade. A snapshot would require either copying the whole map or locking out writers for the duration of the walk, and both would defeat the point of the type. ## How the gauge goes wrong A registry of live client connections publishes `connections_live` by walking the map every fifteen seconds: ```go n := 0 conns.Range(func(key, value any) bool { n++ return true }) ``` On a quiet service this looks correct forever, which is what makes it dangerous. Under churn the walk takes real time, and during that time connections open and close. Some that closed early in the walk were already counted; some that opened late are not visited. The result is a number that is plausible, never exactly right, and biased in whichever direction traffic happens to be moving — so it drifts most precisely when you most want to trust it, during a spike or a mass disconnect. The second failure is cost. `Range` is O(entries), and it walks live structures rather than a copy. A gauge that used to walk two hundred entries and now walks two hundred thousand, on a fifteen-second timer, is suddenly a measurable slice of a CPU profile — and if someone wires the same walk into a request handler because "we need the current size", it becomes a per-request full scan. ## Counting where the change happens Membership changes at exactly two points, and both of those operations already report whether they changed anything: ```go var live atomic.Int64 if _, loaded := conns.LoadOrStore(id, meta); !loaded { live.Add(1) // this call actually inserted } if _, loaded := conns.LoadAndDelete(id); loaded { live.Add(-1) // this call actually removed } ``` The discipline is to route every mutation through those two helpers and never call bare `Store` or `Delete` on the map, because `Store` on an existing key must not move the counter and `Delete` of an absent key must not either — that is exactly the information the two `loaded` booleans carry and the bare methods throw away. Wrap the map and the counter in one small unexported struct so the invariant is enforced by the type rather than by review. The counter is itself a moving target — it is read without stopping the world, so it reports a moment, not a truth — but it is *consistent* with the sequence of insertions and removals, and it costs one atomic add per membership change instead of a full walk per scrape. ## Where Range is still the right tool `Range` earns its place where approximation is acceptable and a walk is what you actually want: a debug endpoint dumping every live entry, a shutdown path closing everything still registered, a sweeper that deletes entries older than a deadline (deleting from inside `f` is explicitly allowed), or a test where you can prove the map is quiescent. What it must not become is the source of a number some other system treats as exact — a billing count, a capacity check, a comparison against a hard limit. The rule of thumb: `Range` answers "roughly what is in here", never "how many are in here right now".