relay: wire pyrycode_relay_connected_{binaries,phones} gauges into registry events

[ilmoniemi]

User Story

As a relay operator, I want pyrycode_relay_connected_binaries and pyrycode_relay_connected_phones gauges to track live connection counts in real time, so I can graph utilization and alert on unexpected drops from Prometheus instead of polling /healthz.

Context

/healthz (#10) reports current connection counts as a one-shot snapshot. Time-series visibility into connection lifecycle (joins, leaves, grace expiries) requires Prometheus gauges wired at the registry's mutation points.

This ticket wires the cheapest pair of metrics — connection counters — into the existing register / unregister / grace-expiry-eviction sites in internal/relay/registry.go. The gauges live on the metrics registry introduced by the scaffolding slice (#59); this ticket adds the gauge definitions and the Inc/Dec wiring.

The gauges are independent of the listener — once they're wired, they reflect live counts in the registry whether or not anyone is scraping. The listener slice (#60) is a separate sibling.

Acceptance Criteria

• Two gauges defined and registered against the metrics registry from relay: adopt prometheus/client_golang and introduce metrics registry scaffolding #59 (not the global default registry):
  • pyrycode_relay_connected_binaries
  • pyrycode_relay_connected_phones
• Gauges are incremented and decremented at the existing register, unregister, and grace-expiry-eviction sites in internal/relay/registry.go. The architect picks the exact shape (counters maintained inside the registry's lock vs. a pull-based prometheus.Collector over the existing Counts()).
• Under concurrent register/unregister/grace-expiry sequences, gauge values match the registry's live count at all observation points (verified by -race test that races register/unregister/grace-expiry against periodic gauge reads).
• Grace-expiry-eviction increments/decrements fire only on real evictions — stale-fire no-ops (per the pointer-identity guard pattern in docs/PROJECT-MEMORY.md) must not change the gauge.
• make vet, make test -race, and make build clean.
• docs/knowledge/codebase/<n>.md summary entry created; docs/knowledge/INDEX.md updated.

Technical Notes

• The metrics registry constructor (NewMetricsRegistry) and handler factory (NewMetricsHandler) live in internal/relay/metrics.go from relay: adopt prometheus/client_golang and introduce metrics registry scaffolding #59. Consume that seam; do not re-create the registry.
• Follow the per-concern collector struct seam from relay: adopt prometheus/client_golang and introduce metrics registry scaffolding #59 — see docs/knowledge/features/metrics-registry.md § "Seam shape — per-concern collector struct". A separate file (e.g. metrics_connections.go) with a private struct holding the two gauges and a constructor taking prometheus.Registerer matches the established pattern; sibling tickets (relay: /metrics — upgrade-attempt and register-failure counters #57, relay: /metrics — frame-forwarded and grace-expiry counters #58) will follow the same shape.
• Gauge mutations must respect the registry's existing locking discipline (docs/PROJECT-MEMORY.md line 41: "Interface methods called under the lock are documented as non-blocking getters" — prometheus.Gauge.Inc/Dec is non-blocking and safe to call under the lock).
• Out of scope: the listener (relay: localhost-only /metrics listener with bind-address validation #60), upgrade-attempt counters (relay: /metrics — upgrade-attempt and register-failure counters #57), frame/grace counters (relay: /metrics — frame-forwarded and grace-expiry counters #58).

Size Estimate

S

Split from #56. Depends on the scaffolding slice (#59, closed 2026-05-11).

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Refinement complete. Status remains Backlog, `size:s` and `security-sensitive` retained, `wip:po` will be swapped to `ready:po` by the dispatcher on successful completion.

**Changes made:**
1. Concretised "(sibling)" → "(#59)" — #59 is closed (2026-05-11), no reason to keep the dependency abstract.
2. Tightened AC #2's alternative phrasing: "counters maintained inside the registry's lock vs. a pull-based `prometheus.Collector` over the existing `Counts()`" — removes the contradiction between "Inc/Dec at the existing sites" and "derived from existing fields".
3. Added a Technical Note pointing the architect at the seam-shape doc (`docs/knowledge/features/metrics-registry.md` § "Seam shape — per-concern collector struct") with a concrete filename suggestion (`metrics_connections.go`), matching the pattern siblings #57/#58 will also follow.
4. No size change (S is right — ~30-60 LOC for the collector struct, two gauges, three Inc/Dec sites, race test).
5. No split — single concern (gauges into registry events), four AC, well within S limits.

The `security-sensitive` label was kept (border­line — internal bookkeeping triggered from internet-exposed paths — but the human triager applied it and the conservative call is to leave it).

Ready for human review. Move to the next column when approved.

[ilmoniemi]

🤖 System Architect — defines Go interfaces, data flows, concurrency patterns

architect agent has completed work on this ticket.

Agent output (click to expand)

Spec for #61 committed on `feature/61` at `docs/specs/architecture/61-connected-gauges.md`.

**Design pick:** pull-based `prometheus.Collector` wrapping `Registry.Counts()`. Justified on five axes — zero diff in `registry.go` (preserves audit surface of the internet-exposed file), the stale-fire AC is satisfied structurally (no second source of truth to drift), `Counts()` already takes the right lock, no new lock-acquisition path, and the seam admits both pull and push shapes (gauges-of-state pull-shaped; sibling counters-of-events stay push-shaped).

**Deliverables for the developer:**
- `internal/relay/metrics_connections.go` (new, ~40 lines) — `connectionsCollector` struct + exported `NewConnectionsMetrics` constructor.
- `internal/relay/metrics_connections_test.go` (new, ~120 lines) — three tests: gauge-reflects-live-counts, grace-stale-fire-no-op, race-freedom against periodic scrapes.
- Zero edits to existing files. Production wiring in `main.go` is #60's job per #59's seam contract.

**Security review:** PASS. Load-bearing choice is label-less gauges (no `{server="..."}`) — closes the threat-model § Log hygiene exfiltration channel structurally; spec calls out the rejected shape so the developer cannot quietly re-add it.

Ready for human review. Move to the next column when approved.