Skip to content
ChannelWatch

Health & Readiness Probes

ChannelWatch exposes four HTTP health endpoints. Three are minimal probe-oriented endpoints under /healthz/*. /api/health is the authenticated detailed monitoring endpoint.

Health endpoints

Section titled “Health endpoints”
Endpoint Purpose Healthy status
/api/health Detailed monitoring and runtime summary 200 OK
/healthz/live Process is alive and responding 200 OK
/healthz/ready Monitoring readiness summary for enabled DVRs 200 OK
/healthz/startup Startup completion gate 200 OK

All four endpoints return JSON payloads. The /healthz/* probes are auth-exempt. /api/health requires an API key or an authenticated RBAC session when authentication is configured.

General health check (/api/health)

Section titled “General health check (/api/health)”

GET /api/health returns the detailed aggregate health document used by authenticated operational tooling. It includes overall status plus runtime, DVR monitoring, and notification-routing diagnostics. For example:

{
  "status": "ok",
  "runtime": { "started": true },
  "dvrs": [],
  "notification_routing_diagnostics": {}
}

The exact nested fields can grow with diagnostics. Use /healthz/ready when a monitor needs only an unauthenticated readiness result.

Kubernetes probe endpoints

Section titled “Kubernetes probe endpoints”

Liveness probe (/healthz/live)

Section titled “Liveness probe (/healthz/live)”

The liveness probe checks whether the web process can respond at all. The current implementation always returns a simple JSON success body while the process is alive:

{
  "status": "ok"
}

Use this probe to let Kubernetes restart a wedged process. It does not evaluate DVR connectivity or freshness.

Readiness probe (/healthz/ready)

Section titled “Readiness probe (/healthz/ready)”

The readiness probe returns aggregate status only. On success it returns 200 with:

{
  "status": "ready",
  "ready": true
}

If the aggregate monitoring summary is not ready, the same JSON shape is returned with status: "degraded" and HTTP 503.

The important distinction is that readiness is based on the watchdog-style monitoring summary, not just raw process liveness.

Startup probe (/healthz/startup)

Section titled “Startup probe (/healthz/startup)”

The startup probe reports whether the backend has completed startup initialization:

Healthy:

{
  "status": "ready"
}

Not ready yet:

{
  "status": "not_ready"
}

The backend returns HTTP 503 until startup completes.

What drives readiness

Section titled “What drives readiness”

Both /api/health and /healthz/ready use the backend monitoring-health snapshot. /api/health exposes the detailed authenticated aggregate. The public readiness probe deliberately reduces that state to status and ready, omitting per-DVR names, identifiers, versions, timestamps, thresholds, and failure reasons.

Example Kubernetes config

Section titled “Example Kubernetes config”
livenessProbe:
  httpGet:
    path: /healthz/live
    port: 8501
  initialDelaySeconds: 0
  periodSeconds: 30
  timeoutSeconds: 3
  failureThreshold: 3


readinessProbe:
  httpGet:
    path: /healthz/ready
    port: 8501
  initialDelaySeconds: 0
  periodSeconds: 10
  timeoutSeconds: 3
  failureThreshold: 3


startupProbe:
  httpGet:
    path: /healthz/startup
    port: 8501
  initialDelaySeconds: 0
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 30
Section titled “Related pages”