Health Checks
Add /health, liveness and readiness endpoints to a Node.js API with HealthChecker from @axiljs/observability, with per-check timeouts and 200/503 status codes.
On this page6
HealthChecker runs named dependency checks (database, cache, downstream APIs) and turns the result into HTTP endpoints that load balancers, Kubernetes and uptime monitors understand: 200 when everything passes, 503 when something does not.
1import { Application } from '@axiljs/core'
2import { HealthChecker } from '@axiljs/observability'
3
4const app = new Application()
5const health = new HealthChecker()
6
7health
8 .addCheck('database', async () => {
9 await db.query('SELECT 1')
10 return { message: 'Connected' }
11 })
12 .addCheck('redis', async () => {
13 await redis.ping()
14 }, { timeoutMs: 1000 })
15
16app.get('/health', health.handler())
17app.get('/health/live', health.livenessHandler())
18app.get('/health/ready', health.readinessHandler())new HealthChecker(options?)
| Option | Type | Default | Description |
|---|---|---|---|
defaultTimeoutMs | number | 5000 | Timeout for checks that do not set their own. 0 disables timeouts |
The uptime reported by the endpoints is counted from when the HealthChecker was constructed.
addCheck(name, check, options?)
Registers a check and returns the checker, so calls can be chained. Adding a check with an existing name replaces it.
A check is an async function:
- Passes when it resolves. It may resolve with
{ message?, details? }to add information to the report. - Fails when it throws or rejects. The error message is reported.
- Fails when it does not settle within its timeout, with the message
Health check '<name>' timed out after <ms>ms. A hung dependency therefore cannot hang the health endpoint.
| Option | Type | Default | Description |
|---|---|---|---|
timeoutMs | number | defaultTimeoutMs | Timeout for this check. 0 disables it |
1health.addCheck('payments-api', async () => {
2 const res = await fetch('https://payments.internal/ping')
3 if (!res.ok) throw new Error(`payments-api returned ${res.status}`)
4 return { details: { region: res.headers.get('x-region') } }
5}, { timeoutMs: 2000 })All checks run in parallel, so the endpoint takes about as long as the slowest check.
check()
Runs every check and returns a HealthStatus without sending a response. Use it for logs, startup gating or your own endpoint.
const status = await health.check()
if (status.status !== 'healthy') log.warn('dependencies down', { checks: status.checks })| Field | Type | Description |
|---|---|---|
status | 'healthy' | 'unhealthy' | 'degraded' | unhealthy if any check failed, otherwise healthy |
timestamp | string | ISO time of the run |
uptime | number | Seconds since the checker was created |
version | string | Node.js version (process.version) |
checks | Record<string, CheckResult> | One result per check |
Each CheckResult:
| Field | Type | Description |
|---|---|---|
status | CheckStatus | healthy or unhealthy |
responseTimeMs | number | How long the check took |
message | string | undefined | From the check's return value, or the error message |
details | Record<string, unknown> | undefined | From the check's return value (passing checks only) |
degraded is part of the CheckStatus type, but HealthChecker never produces it: a check either passes or fails.
Endpoints
| Handler | Runs checks | Status code | Body |
|---|---|---|---|
handler() | Yes | 200 if healthy, else 503 | The full HealthStatus |
livenessHandler() | No | Always 200 | { status: 'alive', timestamp, uptime } |
readinessHandler() | Yes | 200 if no check failed, else 503 | { ready, timestamp, checks } |
1{
2 "status": "healthy",
3 "timestamp": "2026-11-12T09:30:00.000Z",
4 "uptime": 3521,
5 "version": "v24.4.0",
6 "checks": {
7 "database": { "status": "healthy", "responseTimeMs": 3, "message": "Connected" },
8 "redis": { "status": "healthy", "responseTimeMs": 1 }
9 }
10}The bodies are sent with res.json() as shown, not wrapped in the res.success() envelope.
Kubernetes probes
Liveness answers "is the process alive?", so it must not depend on the database: a database outage should not make Kubernetes restart every pod. Readiness answers "should this pod get traffic?", so it runs the checks.
1livenessProbe:
2 httpGet: { path: /health/live, port: 3000 }
3 periodSeconds: 10
4readinessProbe:
5 httpGet: { path: /health/ready, port: 3000 }
6 periodSeconds: 5
7 timeoutSeconds: 6 # above the 5000 ms default check timeoutTip
Keep check timeouts below the probe's timeoutSeconds. A timed-out check returns a clean 503 with a message; a timed-out probe only tells you the request took too long.
Note
Register health routes before authentication middleware, or exempt them from it, so probes and load balancers can reach them.
Related
Was this page helpful?