Health, Diagnostics, and Metrics¶

DeltaLLM exposes process probes, dependency readiness, routing diagnostics, and Prometheus metrics. The current application does not enforce authentication on these routes. Treat all routes except coarse liveness as internal operational surfaces and restrict them with ingress, service-mesh, firewall, or private-network policy.

Exposure matrix¶

Endpoint	Application auth	Intended exposure	Purpose
`GET /health/liveliness`	None	Public or orchestrator probe	Confirms that the process can answer HTTP; performs no dependency I/O
`GET /health`	None	Internal only	Combines liveness with detailed readiness state
`GET /health/readiness`	None	Internal only	Checks required dependencies and supervised runtime services
`GET /health/deployments`	None	Operator network only	Reports deployment health, counts, and routing topology
`GET /health/fallback-events`	None	Operator network only	Returns recent sanitized routing/failover events
`GET /metrics`	None	Prometheus/private network only	Exposes process and gateway metrics

Do not publish detailed operational routes

Navigation or documentation visibility is not an access control. Configure the reverse proxy or cluster network so internet clients cannot reach readiness, deployment health, fallback events, or metrics. Protect the running application's /docs, /redoc, and /openapi.json routes similarly when the full control-plane schema is not public.

Liveness¶

GET /health/liveliness

Returns 200 while the process can serve HTTP:

{"status": "ok"}

Use this for container liveness. It deliberately does not query PostgreSQL, Redis, providers, or workers.

Readiness¶

GET /health/readiness

Returns 200 when all configured critical checks are ready and 503 when one is degraded. Database and critical Redis probes run concurrently, with one owned refresh per process, a one-second deadline and a one-second cache. Process drain and dead/stale required workers bypass cached dependency success. Missing required clients, capacity exhaustion, failures and timeouts return 503. PostgreSQL checks include database for control capacity and foreground_database for API-key authentication and admission. Outbox mode also requires telemetry_database and telemetry_worker_database; legacy mode omits these disabled allocations. Settlement capacity is required when spend operation intents are enabled. Optional cache Redis clients do not gate readiness.

Depending on enabled features, checks can also include routing reconciliation, spend/audit/email workers, batch webhook delivery, and organization lifecycle services.

{
  "status": "ok",
  "checks": {
    "redis": true,
    "database": true,
    "foreground_database": true
  },
  "details": {
    "redis": {"state": "ready"},
    "database": {"state": "ready"},
    "foreground_database": {"state": "ready"}
  }
}

Disabled and unavailable components have different meanings. Do not coerce a missing check or failed response to healthy.

Combined health¶

GET /health

Returns coarse liveness plus the full readiness payload. Its HTTP status follows readiness, so use /health/liveliness—not /health—for a process-only liveness probe.

Deployment diagnostics¶

GET /health/deployments
GET /health/deployments?model=app-chat

Reports provider-deployment routing health. The optional model query narrows the response. Because the payload reveals deployment counts and state, expose it only to operator networks.

Fallback events¶

GET /health/fallback-events?limit=50

The endpoint returns recent fallback events from the current process. limit has a maximum of 200. This bounded diagnostic history is not a durable audit log or a cluster-wide event stream. For a context fallback before the first provider attempt, from_deployment is null. In that condition, the gateway rejected the primary route group locally. No deployment failed.

Prometheus metrics¶

GET /metrics

Returns the Prometheus text format. Scrape the private service/pod address or an authenticated monitoring proxy; do not route this path through a public wildcard ingress.

See Observability for metrics and alerting guidance and Security hardening for path isolation.

See Process lifecycle for configured worker expectations, probe hysteresis, drain rejection and the complete termination budget.