Metrics Endpoint Debug

Use this runbook when the application is up but the /metrics endpoint is empty, unavailable, or missing expected Prometheus-formatted output.

Common symptoms

  • curl http://localhost:3002/metrics returns nothing useful
  • Prometheus target is DOWN
  • Grafana panels show no data even though containers are running

Step 1 — Call the endpoint directly

curl http://localhost:3002/metrics

A healthy endpoint should return plain-text Prometheus metrics.

Step 2 — Verify the service is listening on the expected port

docker ps
docker compose ps

Confirm the auth-service container is running and exposing the expected application port.

Step 3 — Review application logs

docker compose logs auth-service --tail=100

Look for errors related to route registration, metrics middleware, app startup, or port binding.

Step 4 — Confirm metrics registration

Typical metrics exposed by the service may include:

process_cpu_seconds_total
process_resident_memory_bytes
nodejs_active_handles
auth_service_http_requests_total

Step 5 — Restart the application service

docker compose restart auth-service

Success criteria

  • /metrics responds with Prometheus-formatted text
  • Prometheus can scrape the target
  • Grafana queries begin returning live data

Related runbooks