Health Endpoints

Breeze exposes health check endpoints that let you verify whether the API and its dependencies are running. Use these with load balancers, container orchestrators, and uptime monitors to detect and respond to outages automatically.

Available Endpoints

| Endpoint | Purpose | Auth Required | |---|---|---| | GET /health | Basic liveness — is the API process running? | No | | GET /health/ready | Full readiness — are the database and Redis reachable? | No | | GET /health/live | Kubernetes liveness probe (alias for /health) | No | | GET /metrics/scrape | Prometheus-formatted metrics | Bearer token |

Response Formats

GET /health

Returns 200 OK if the API process is alive. This endpoint does not check backend dependencies — it only confirms the HTTP server is accepting connections.

{
  "status": "ok",
  "version": "0.50.0",
  "uptime": 86400
}

| Field | Description | |---|---| | status | Always "ok" when the process is running | | version | Current Breeze API version | | uptime | Seconds since the process started |

GET /health/ready

Returns 200 OK only when all backend dependencies are healthy. Returns 503 Service Unavailable if any check fails.

Healthy response (200):

{
  "status": "ready",
  "checks": {
    "database": "ok",
    "redis": "ok"
  }
}

Degraded response (503):

{
  "status": "not_ready",
  "checks": {
    "database": "ok",
    "redis": "error: connection refused"
  }
}

| Field | Description | |---|---| | status | "ready" or "not_ready" | | checks.database | "ok" or an error message from the PostgreSQL connection test | | checks.redis | "ok" or an error message from the Redis PING command |

Note

Use /health for liveness probes (restart the container if the process is dead) and /health/ready for readiness probes (stop sending traffic until dependencies recover).

GET /metrics/scrape

Prometheus-formatted metrics. Requires the METRICS_SCRAPE_TOKEN bearer token set in your environment.

curl -H "Authorization: Bearer $METRICS_SCRAPE_TOKEN" \
  https://breeze.yourdomain.com/metrics/scrape

See Observability Stack for the full list of available metrics.

Using Health Checks with Load Balancers

Configure your load balancer to probe the health endpoints so unhealthy instances are automatically removed from rotation.

AWS ALB

Target group health check:
  Protocol: HTTP
  Path: /health/ready
  Healthy threshold: 2
  Unhealthy threshold: 3
  Timeout: 5 seconds
  Interval: 30 seconds
  Success codes: 200

Nginx

upstream breeze_api {
    server api1:3001;
    server api2:3001;
}

server {
    location /api/ {
        proxy_pass http://breeze_api;
    }
}

# Passive health checks happen automatically.
# For active checks (Nginx Plus), add:
# health_check uri=/health/ready interval=30s fails=3 passes=2;

HAProxy

backend breeze_api
    option httpchk GET /health/ready
    http-check expect status 200
    server api1 api1:3001 check inter 30s fall 3 rise 2
    server api2 api2:3001 check inter 30s fall 3 rise 2

Docker Health Checks

Every container in the Breeze production stack has a built-in health check. Docker (and Docker Compose) use these to determine container status and trigger restarts.

| Container | Check Command | Interval | Start Period | |---|---|---|---| | API | wget http://localhost:3001/health | 30s | 10s | | Web | wget http://localhost:4321/ | 30s | 10s | | PostgreSQL | pg_isready | 10s | 30s | | Redis | redis-cli ping | 10s | 10s | | Prometheus | wget http://localhost:9090/-/healthy | 30s | 10s | | Grafana | wget http://localhost:3000/api/health | 30s | 30s | | Alertmanager | wget http://localhost:9093/-/healthy | 30s | 10s | | Loki | wget http://localhost:3100/ready | 30s | 10s |

Check container health status at any time:

docker compose ps

Look for (healthy), (unhealthy), or (health: starting) in the STATUS column.

Kubernetes Probes

If you deploy Breeze on Kubernetes, map the health endpoints to pod probes:

containers:
  - name: breeze-api
    ports:
      - containerPort: 3001
    livenessProbe:
      httpGet:
        path: /health/live
        port: 3001
      initialDelaySeconds: 10
      periodSeconds: 15
      failureThreshold: 3
    readinessProbe:
      httpGet:
        path: /health/ready
        port: 3001
      initialDelaySeconds: 5
      periodSeconds: 10
      failureThreshold: 3
    startupProbe:
      httpGet:
        path: /health
        port: 3001
      initialDelaySeconds: 5
      periodSeconds: 5
      failureThreshold: 30

Key Metrics to Watch

These are the most important indicators of operational health. Monitor them in Grafana or your preferred tool.

| Metric | Healthy Range | What It Means | |---|---|---| | /health/ready status | 200 | All backend dependencies are reachable | | http_request_duration_seconds P95 | < 2s | API response times are acceptable | | http_requests_total 5xx rate | < 1% | Very few server errors | | redis_memory_used_bytes | < 80% of max | Redis has headroom | | pg_stat_activity_count | < 80% of max_connections | Database connection pool is not saturated | | breeze_active_devices | Matches expected count | Agents are checking in | | API uptime | Increasing | Process has not restarted unexpectedly |

Troubleshooting Health Check Failures

/health returns non-200

The API process is not running or not reachable on port 3001.

1. Check if the container is running: docker compose ps api
2. Check container logs: docker compose logs api --tail 50
3. Verify the port binding: docker compose port api 3001
4. If the process is crash-looping, check for missing environment variables or database connection strings in the logs.

/health/ready returns 503

One or more backend dependencies are down.

1. Check which dependency failed by reading the checks object in the response body.
2. If database is failing:
   • Verify PostgreSQL is running: docker compose ps postgres
   • Test the connection manually: docker compose exec postgres pg_isready
   • Check for connection pool exhaustion: look at pg_stat_activity_count in Grafana
3. If redis is failing:
   • Verify Redis is running: docker compose ps redis
   • Test the connection: docker compose exec redis redis-cli ping
   • Check memory usage: docker compose exec redis redis-cli info memory

Containers showing (unhealthy)

1. Identify which container is unhealthy: docker compose ps
2. Check container logs: docker compose logs <container> --tail 100
3. If the container keeps restarting, look at the start_period — it may be failing its health check before it finishes starting. Increase the start period in your compose override if needed.

Caution

If Redis becomes unreachable, the API will still serve most requests (health check returns 503, but endpoints that do not require Redis will work). However, features that depend on Redis — rate limiting, BullMQ job queues, and real-time pub/sub — will be degraded until Redis recovers.