observability

Changing what fold reports about itself

Three surfaces, one rule each, and only one of them has a test.

Surface	Declared in	Held in lockstep by
Prometheus metrics	gateway/metrics.go	gateway/observability_pack_test.go, both directions
Trace attributes	gateway/otel.go	nothing — docs/operations.md "Tracing" is the record
Audit event fields	audit/audit.go	nothing — docs/operations.md "Audit events" is the record

Metrics: the pack is checked both ways

observability_pack_test.go compares the names in metrics.go against the three files that query them:

• deploy/helm/fold/dashboards/fold-overview.json
• deploy/helm/fold/templates/prometheusrule.yaml (prometheus-operator)
• deploy/observability/alerts.yml (plain Prometheus, the compose stack)

Forward: every fold_* the pack references must be declared. A query naming a metric that does not exist draws an empty panel and arms an alert that can never fire — the two failure modes that look exactly like health.

Backward: every declared metric must appear somewhere in the pack, so a new one forces the question "does this belong on the dashboard" instead of shipping unobserved. metricNamesUnexercised is the escape hatch and is currently empty; adding to it should cost a reason in the diff.

And TestBothRuleFilesCarryTheSameAlerts — the two rule files are the same alerts for two deployment shapes. Change one, change the other.

Two traps in how the check reads the code

• It extracts quoted string literals matching "fold_[a-z_]+" from metrics.go only. A name built by concatenation, or declared in another file, is invisible to the test — it will pass while shipping a metric nothing watches.
• Histogram series are matched after stripping _bucket / _sum / _count, so query fold_request_duration_seconds_bucket freely; the base name is what must be declared.

It reads the source rather than scraping a live registry on purpose: a CounterVec with no observations exposes nothing, so a scrape would under-report exactly the metrics that have never fired.