Observability

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.

4 min readUpdated DocumentationEdit this page
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.

❯npm install @axiljs/observability
❯pnpm add @axiljs/observability
❯yarn add @axiljs/observability
❯bun add @axiljs/observability
TypeScript
TS
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?)

OptionTypeDefaultDescription
defaultTimeoutMsnumber5000Timeout 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.
OptionTypeDefaultDescription
timeoutMsnumberdefaultTimeoutMsTimeout for this check. 0 disables it
TypeScript
TS
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.

TypeScript
TS
const status = await health.check()
if (status.status !== 'healthy') log.warn('dependencies down', { checks: status.checks })
FieldTypeDescription
status'healthy' | 'unhealthy' | 'degraded'unhealthy if any check failed, otherwise healthy
timestampstringISO time of the run
uptimenumberSeconds since the checker was created
versionstringNode.js version (process.version)
checksRecord<string, CheckResult>One result per check

Each CheckResult:

FieldTypeDescription
statusCheckStatushealthy or unhealthy
responseTimeMsnumberHow long the check took
messagestring | undefinedFrom the check's return value, or the error message
detailsRecord<string, unknown> | undefinedFrom 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

HandlerRuns checksStatus codeBody
handler()Yes200 if healthy, else 503The full HealthStatus
livenessHandler()NoAlways 200{ status: 'alive', timestamp, uptime }
readinessHandler()Yes200 if no check failed, else 503{ ready, timestamp, checks }
Terminal
❯curl -i http://localhost:3000/health
JSON
JSON
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.

YAML
YAML
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 timeout

Tip

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.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY