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",
});

See Also