Health Checks¶

Overview¶

Katal includes a built-in health check registry with three endpoints: - /health - full health snapshot - /health/ready - readiness checks - /health/live - liveness checks

Quick Start¶

import { Application } from "katal";

const app = new Application({ port: 3000 });

app.addHealthCheck("database", async () => {
    // replace with your actual probe
    return true;
}, { readiness: true, liveness: false });

app.addHealthCheck("event-loop", () => ({
    status: "pass",
    detail: "event loop responsive",
}), { liveness: true });

app.enableHealthEndpoints();

await app.listen();

Endpoint Status Codes¶

200 when all included checks are pass
503 when any included check is fail

Health Report Shape¶

{
  "status": "pass",
  "timestamp": "2026-04-12T10:00:00.000Z",
  "checks": {
    "database": { "status": "pass" },
    "event-loop": { "status": "pass", "detail": "event loop responsive" }
  }
}

API¶

`app.addHealthCheck(name, check, options?)`¶

Register a check function.

Options: - critical (reserved for future policy weighting) - readiness (default true) - liveness (default false)

`app.enableHealthEndpoints(options?)`¶

Enable and/or customize endpoint paths.

Options: - healthPath (default /health) - readyPath (default /health/ready) - livePath (default /health/live)

Notes¶

Checks can return either boolean or a structured { status: "pass" | "fail"; detail?: string } object.
Exceptions thrown by a check are caught and recorded as fail with the error message.
By default all checks are included in /health/ready. Set liveness: true to also include them in /health/live.