Health and metrics
Liveness, readiness, and Prometheus metrics endpoints on auth and proxy services (ADR-0022).
Both Go services expose three operational HTTP routes on their respective IBEX_PORT values: proxy 8080, auth 8081. These endpoints are unauthenticated and intended for load balancers, Kubernetes probes, and Prometheus scrapes.
Endpoints
/healthLiveness — always 200 when the process responds; no external dependency checks.
/readyReadiness — 200 when critical dependencies are healthy; 503 when any critical check fails.
/metricsPrometheus text exposition format from packages/metrics.
Apply the same three routes on both http://localhost:8080 (proxy) and http://localhost:8081 (auth).
Response schemas
GET /health
Always returns 200 with minimal JSON:
{
"status": "ok",
"checks": {}
}Use for liveness probes. Failure → restart the pod/process.
GET /ready
Returns dependency detail:
{
"status": "ok",
"checks": {
"postgres": { "status": "ok", "latency_ms": 2 },
"auth_grpc": { "status": "ok", "latency_ms": 4 }
}
}Top-level status | HTTP | Meaning |
|---|---|---|
ok | 200 | All critical checks passed |
degraded | 200 | Critical OK; advisory failure |
unhealthy | 503 | At least one critical check failed |
Per-check timeout: 500ms. Overall request budget: 750ms.
Critical checks by service
| Service | Check name | What it verifies |
|---|---|---|
| Auth | postgres | SELECT 1 via pool |
| Auth | grpc | TCP reachability to gRPC listen address |
| Proxy | auth_grpc | ValidateToken with sentinel probe token; Unauthenticated = reachable |
| Proxy | redis | PING over RESP |
Use readiness probes for load-balancer membership. A failing /ready removes traffic without restarting the pod.
Probe examples
# Liveness
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/health
# Readiness (proxy — needs auth gRPC + Redis)
curl -s http://localhost:8080/ready | jq
# Metrics scrape
curl -s http://localhost:8080/metrics | headMetrics catalog
Scrape /metrics on both services. Key series include:
| Metric | Type | Labels | Service |
|---|---|---|---|
ibex_proxy_requests_total | Counter | route, method, code | Proxy |
ibex_proxy_auth_validate_duration_seconds | Histogram | result | Proxy |
ibex_auth_validate_token_duration_seconds | Histogram | result | Auth |
ibex_auth_validate_agent_duration_seconds | Histogram | result | Auth |
Full catalog: ADR-0021.
Related
- Docker Compose — local boot order
- Kubernetes — future probe wiring (not shipped)
Was this page helpful?
Last updated on