Skip to content

feat(metrics): serve prometheus metrics at /metrics - #24

Merged
jamiehdev merged 3 commits into
mainfrom
feat/prometheus-metrics
Sep 27, 2026
Merged

jamiehdev merged 3 commits into
mainfrom
feat/prometheus-metrics

Conversation

@jamiehdev

Copy link
Copy Markdown
Owner

shadowstep now serves Prometheus metrics at GET /metrics in text format 0.0.4, so operators can scrape request, cache and origin counts. /health reads the same counters, so the two cannot drift, and its JSON shape and values stay the same.

Changes

  • The prometheus crate with default features off produces the exposition. It writes format 0.0.4 directly and adds one package to the lock file. prometheus-client writes only OpenMetrics text, whose counter TYPE lines omit _total and so mismatch the 0.0.4 media type.
  • The metrics are shadowstep_requests_total{route,cache}, shadowstep_responses_total{route,status_class}, shadowstep_origin_requests_total{kind,outcome}, shadowstep_origin_body_idle_timeouts_total{kind}, the shadowstep_origin_response_seconds histogram (5 ms to 30 s), two cache counters and two cache gauges. No label holds a path.
  • A body that goes idle counts in its own counter, because it follows a response that origin_requests_total already counted by status class.
  • --metrics-addr (METRICS_ADDR) moves /metrics to a separate listener that serves nothing else. The proxy listeners then forward /metrics to the origin. Without the flag, /metrics stays on the proxy listeners, as /health does. The README describes the exposure and the path shadowing.
  • The Deployment gets no prometheus.io/scrape annotations, because they are a scrape-config convention and not a standard.

Verification

  • On main, all 11 new tests in tests/integration/metrics.rs fail, because the origin answers /metrics.
  • One deliberate break for each metric family makes at least one test fail. The breaks cover wrong cache labels, status classes, origin outcomes and kind, a missing histogram observation, swapped gauges, and uncounted revalidations, refreshes and idle timeouts. They also cover a slash in a label, a counted scrape, and /metrics kept on the proxy listener.

Not run: a scrape by a real Prometheus server.

@jamiehdev
jamiehdev merged commit 73740dd into main Sep 27, 2026
2 checks passed
@jamiehdev
jamiehdev deleted the feat/prometheus-metrics branch September 27, 2026 17:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant