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.

ChannelWatch diagnostics screen showing health summary, multi-DVR status, debug bundle download, log tools, and alert tests
Diagnostics And Debug BundleDiagnostics groups health checks, log review, alert tests, and sanitized debug bundle download in one operator surface. Captured from ChannelWatch v1.3.0 with safe demo data.

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”