Health Checks & Production Monitoring¶
Katal includes an enterprise-grade Health Check subsystem with native endpoints designed for Kubernetes Probes, Docker Healthchecks, and Uptime Monitors:
- /health — Full diagnostic health snapshot
- /health/ready — Readiness probe (Can this instance receive incoming traffic?)
- /health/live — Liveness probe (Is this instance alive or should the container orchestrator restart it?)
1. Quick Start¶
import { Application } from "katal";
const app = new Application({ port: 3000 });
// 1. Readiness Check (Database connection)
app.addHealthCheck("database", async () => {
const isDbConnected = await testDatabasePing();
return isDbConnected; // true => "pass", false => "fail"
}, { readiness: true, liveness: false });
// 2. Liveness Check (Event loop responsiveness)
app.addHealthCheck("event-loop", () => {
return {
status: "pass",
detail: "Event loop latency under 10ms",
};
}, { readiness: false, liveness: true });
// 3. Expose endpoints: /health, /health/ready, /health/live
app.enableHealthEndpoints();
await app.listen();
2. Probe Semantics & Status Codes¶
| Endpoint | Purpose | Pass HTTP Status | Fail HTTP Status | Orchestrator Action on Failure |
|---|---|---|---|---|
/health/ready |
Readiness Probe | 200 OK |
503 Service Unavailable |
Kubernetes / Load Balancer removes container from active traffic routing until probe recovers. |
/health/live |
Liveness Probe | 200 OK |
503 Service Unavailable |
Kubernetes kills and restarts the deadlocked container pod. |
/health |
Diagnostic Snapshot | 200 OK |
503 Service Unavailable |
Used by Prometheus, Datadog, or SRE dashboards for system-wide health visualization. |
3. Real-World Health Probes¶
A. Database Connection Probe¶
app.addHealthCheck("postgresql", async () => {
try {
const start = performance.now();
await db.query("SELECT 1");
const latency = (performance.now() - start).toFixed(2);
return {
status: "pass",
detail: `PostgreSQL connection verified (${latency}ms)`,
};
} catch (err: any) {
return {
status: "fail",
detail: `Database unreachable: ${err.message}`,
};
}
}, { readiness: true });
B. Redis Cluster Ping Probe¶
app.addHealthCheck("redis", async () => {
try {
const reply = await redis.ping();
if (reply === "PONG") return true;
return { status: "fail", detail: "Unexpected ping reply" };
} catch (err: any) {
return { status: "fail", detail: `Redis error: ${err.message}` };
}
}, { readiness: true });
C. Node / Bun Process Memory Pressure Check¶
app.addHealthCheck("memory", () => {
const memory = process.memoryUsage();
const heapUsedMb = Math.round(memory.heapUsed / 1024 / 1024);
const heapLimitMb = 1024; // 1 GB threshold
if (heapUsedMb > heapLimitMb) {
return {
status: "fail",
detail: `High memory usage: ${heapUsedMb}MB exceeds limit of ${heapLimitMb}MB`,
};
}
return {
status: "pass",
detail: `Memory healthy: ${heapUsedMb}MB heap used`,
};
}, { liveness: true });
4. Health Report Output Schema¶
When queried, Katal returns a structured JSON payload:
{
"status": "pass",
"timestamp": "2026-10-14T23:30:00.000Z",
"checks": {
"postgresql": {
"status": "pass",
"detail": "PostgreSQL connection verified (1.2ms)"
},
"redis": {
"status": "pass"
},
"memory": {
"status": "pass",
"detail": "Memory healthy: 64MB heap used"
}
}
}
If any check returns false, { status: "fail" }, or throws an uncaught error, the root status changes to "fail" and HTTP 503 is returned:
{
"status": "fail",
"timestamp": "2026-10-14T23:30:00.000Z",
"checks": {
"postgresql": {
"status": "fail",
"detail": "Database unreachable: Connection refused at 5432"
}
}
}
5. Kubernetes Deployment Manifest¶
Here is the standard Kubernetes Pod configuration linking directly to Katal's endpoints:
apiVersion: apps/v1
kind: Deployment
metadata:
name: katal-api
spec:
replicas: 3
template:
spec:
containers:
- name: app
image: myorg/katal-api:latest
ports:
- containerPort: 3000
readinessProbe:
httpGet:
path: /health/ready
port: 3000
initialDelaySeconds: 5
periodSeconds: 10
timeoutSeconds: 2
failureThreshold: 3
livenessProbe:
httpGet:
path: /health/live
port: 3000
initialDelaySeconds: 15
periodSeconds: 20
timeoutSeconds: 3
failureThreshold: 3
6. Docker Compose Configuration¶
version: '3.8'
services:
api:
build: .
ports:
- "3000:3000"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health/ready"]
interval: 15s
timeout: 3s
retries: 3
start_period: 5s
7. Customizing Endpoint Paths¶
app.enableHealthEndpoints({
healthPath: "/api/v1/healthz",
readyPath: "/api/v1/readyz",
livePath: "/api/v1/livez",
});