Health Check API Reference

The Boilerplate includes a robust Native Health domain (src/domain/health/) designed to provide deep observability into the application's runtime state.

These endpoints are crucial when deploying the application to container orchestrators like Kubernetes or Docker Swarm, as they dictate whether traffic should be routed to a specific instance or if the container needs to be restarted.

---

Readiness Probe Diagram

Press enter or space to select a node. You can then use the arrow keys to move the node around. You can then use the arrow keys to move the node around, press delete to remove it and press escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or press escape to cancel.

---

1. Liveness Probe

The Liveness Probe is a lightweight endpoint that simply confirms the Fastify web server's Event Loop is not blocked and that it can respond to HTTP requests.

Endpoint

GET /api/v1/health/liveness

When to use

Configure orchestrators to hit this endpoint to detect deadlocks. If this endpoint times out or returns an error, the orchestrator should kill and restart the container.

Expected Response (200 OK)

{
  "status": "active",
  "version": "1.0.0",
  "date": "2024-03-01T12:00:00.000Z"
}

---

2. Readiness Probe (Deep Check)

The Readiness Probe performs a deep system check. It actively pings external dependencies (like PostgreSQL and Redis) and measures hardware resources (Memory, Disk).

Endpoint

GET /api/v1/health/readiness

When to use

Configure orchestrators/load balancers to hit this endpoint to check if the instance is fully booted and connected to databases. If this returns 503, the orchestrator will temporarily stop routing traffic to this instance, but it will not kill it.

Checks Performed

• Database: Executes a quick SELECT version() using Drizzle ORM to verify Postgres connectivity and measure latency.
• Cache: Sends a PING command to the Redis server to measure latency.
• Hardware: Reads the process.memoryUsage() and free disk space.

Expected Response (200 OK)

When all dependencies are connected:

{
  "status": "active",
  "version": "1.0.0",
  "date": "2024-03-01T12:00:00.000Z",
  "uptime": 3600.5,
  "memory": {
    "rss": 45000000,
    "heapTotal": 25000000,
    "heapUsed": 15000000,
    "external": 2000000
  },
  "disk": {
    "free": 10240000000,
    "total": 50000000000
  },
  "dependencies": {
    "database": {
      "status": "connected",
      "latency": 5.2,
      "version": "PostgreSQL 15.3..."
    },
    "cache": {
      "status": "connected",
      "latency": 2.1,
      "version": "7.0.12"
    }
  }
}

Degraded Response (503 Service Unavailable)

If either the Database or Redis connection fails, the status string changes to "degraded" and the HTTP code becomes 503.

{
  "status": "degraded",
  // ...
  "dependencies": {
    "database": {
       "status": "disconnected",
       "latency": -1
    }
  }
}