checkId: check.core.services.health plugin: stellaops.doctor.core severity: fail tags: [health, services]

Service Health

Doctor check check.core.services.health — for operators rolling up a Stella Ops service’s registered health checks (database, broker, upstream APIs) into a single verdict so they can spot a downed dependency fast.

What It Checks

Aggregates health status from all registered ASP.NET Core IHealthCheck services. The check resolves HealthCheckService from the DI container and calls CheckHealthAsync(). It then categorizes each registered health check as Healthy, Degraded, or Unhealthy.

Overall Status	Result
Unhealthy (any check unhealthy)	`fail` — lists the failing checks by name with error details for up to 5
Degraded (any check degraded, none unhealthy)	`warn`
Healthy (all checks healthy)	`pass` — reports total count and duration

If HealthCheckService is not registered in the DI container, the check is skipped.

Evidence collected includes: overall status, total checks count, healthy/degraded/unhealthy counts, failed check names, and execution duration.

Why It Matters

Health checks are the primary mechanism for detecting infrastructure problems: database connectivity, message broker availability, external API reachability, and internal service dependencies. An unhealthy result means at least one critical dependency is down, and the service cannot function correctly. Load balancers and orchestrators use health check endpoints to route traffic away from unhealthy instances.

Common Causes

Dependent service unavailable (database, Valkey, external API)
Database connection failed or timed out
External API unreachable (network partition, DNS failure)
Health check timeout exceeded (default check estimated duration is 5 seconds)
Configuration error preventing a dependency from connecting

How to Fix

Docker Compose

Check the health endpoint directly:

# Hit the health endpoint
curl -s http://localhost:5000/health | jq

# Check dependent service connectivity
docker compose exec <service> curl -s http://postgres:5432
docker compose exec <service> curl -s http://valkey:6379

# Restart unhealthy services
docker compose restart <failing-dependency>

Ensure dependent services are healthy before starting:

services:
  platform:
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_healthy

Bare Metal / systemd

# Check the health endpoint
curl -s http://localhost:5000/health | jq

# Check database connectivity
pg_isready -h localhost -p 5432

# Check service logs for errors
journalctl -u stellaops-platform --since "5 minutes ago" | grep -i error

Kubernetes / Helm

# Check pod health
kubectl describe pod <pod> | grep -A 5 "Conditions"

# Check health endpoint inside the pod
kubectl exec -it <pod> -- curl -s http://localhost:5000/health | jq

# Check events for restart loops
kubectl get events --field-selector involvedObject.name=<pod> --sort-by='.lastTimestamp'

Configure health check probes in Helm values:

livenessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 30
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 10
  periodSeconds: 5

Verification

stella doctor run --check check.core.services.health

check.core.services.dependencies — verifies required DI services are registered (prerequisite for health checks)
check.core.config.required — verifies required settings like connection strings are present
check.docker.daemon — verifies Docker daemon is running (relevant when health checks include Docker connectivity)

See the Doctor reference for the full check catalog, CLI usage, and export bundles.