Health Check Endpoint

Overview

A health check endpoint tells load balancers, orchestrators (Kubernetes), and monitoring tools whether your application is alive and ready to serve traffic. A naive return 200 is not enough — production health checks must verify the state of critical dependencies (database, cache, message queue) to prevent serving requests when the app cannot fulfill them.

When to Use

Use this resource when:

• Deploying on Kubernetes (livenessProbe / readinessProbe). See Docker Basics for container fundamentals.
• Running behind a load balancer or reverse proxy. See Rate Limiting for API protection.
• Setting up monitoring and alerting (Prometheus, Datadog). See Prometheus API Monitoring for metrics collection.
• You need graceful degradation or circuit breaker logic. See Circuit Breaker for failure isolation.

Solution

Python (FastAPI)

from fastapi import FastAPI, HTTPException
import psycopg2
import redis

app = FastAPI()

def check_database():
    try:
        conn = psycopg2.connect("dbname=test user=postgres")
        conn.cursor().execute("SELECT 1")
        conn.close()
        return True
    except Exception:
        return False

def check_cache():
    try:
        r = redis.Redis(host="localhost", port=6379)
        r.ping()
        return True
    except Exception:
        return False

@app.get("/health/live")
def liveness():
    return {"status": "alive"}

@app.get("/health/ready")
def readiness():
    db_ok = check_database()
    cache_ok = check_cache()
    if db_ok and cache_ok:
        return {"status": "ready", "checks": {"db": True, "cache": True}}
    raise HTTPException(status_code=503, detail="Not ready")

JavaScript (Express.js)

const express = require("express");
const { Pool } = require("pg");

const app = express();
const db = new Pool({ connectionString: process.env.DATABASE_URL });

app.get("/health/live", (req, res) => {
  res.status(200).json({ status: "alive" });
});

app.get("/health/ready", async (req, res) => {
  try {
    await db.query("SELECT 1");
    res.status(200).json({ status: "ready", checks: { db: true } });
  } catch (err) {
    res.status(503).json({ status: "not ready", checks: { db: false } });
  }
});

Java (Spring Boot Actuator)

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
import javax.sql.DataSource;
import java.sql.Connection;

@Component
public class DatabaseHealthIndicator implements HealthIndicator {
    private final DataSource dataSource;

    public DatabaseHealthIndicator(DataSource dataSource) {
        this.dataSource = dataSource;
    }

    @Override
    public Health health() {
        try (Connection conn = dataSource.getConnection()) {
            if (conn.isValid(1)) {
                return Health.up().withDetail("database", "reachable").build();
            }
        } catch (Exception e) {
            return Health.down().withException(e).build();
        }
        return Health.down().withDetail("database", "timeout").build();
    }
}

Explanation

Health checks follow the two-probe model popularized by Kubernetes:

• Liveness probe (/health/live): Answers “Is the process running?” If it fails, the orchestrator restarts the container.
• Readiness probe (/health/ready): Answers “Can the app serve traffic?” If it fails, the orchestrator removes the pod from the service load balancer.

The key difference: a failing liveness probe triggers a restart, while a failing readiness probe only stops traffic routing. Never put heavy dependency checks in the liveness probe, or a transient database blip will cause a container restart loop.

Variants

Probe Type	Endpoint	Checks	Failure Action
Liveness	/health/live	Process is running	Restart container
Readiness	/health/ready	DB, cache, queue reachable	Remove from load balancer
Startup	/health/startup	App finished initialization	Wait before other probes
Deep	/health/deep	Full end-to-end test	Alert, page on-call

What Works

• Separate liveness and readiness: They serve different purposes and should not share the same endpoint.
• Keep liveness lightweight: Only check that the process has not deadlocked.
• Timeout dependency checks: A slow database should not hang your health check indefinitely.
• Return structured JSON: Include per-check status so operators can diagnose quickly.
• Log health check failures: But at a lower log level to avoid noise.

Common Mistakes

• Single endpoint for everything: Causes unnecessary restarts when a dependency is temporarily unavailable.
• No timeout on DB checks: The health check itself becomes a denial-of-service vector.
• Caching health results too long: A 60-second cache defeats the purpose of real-time monitoring.
• Returning 500 for readiness: Some load balancers only check for 200; use 503 for intentional unavailability.
• Ignoring startup probes: Apps with long initialization get killed by the liveness probe before they finish starting.

Performance Tips

1. Keep liveness probes under 1ms. The liveness probe should only check process state — no I/O, no network calls:

@app.get("/health/live")
def liveness():
    return {"status": "alive"}  # Instant response

2. Cache readiness results for 5-10 seconds. Avoid hitting dependencies on every probe check:

from functools import lru_cache
import time

_readiness_cache = {"result": None, "ts": 0}

@app.get("/health/ready")
def readiness():
    now = time.time()
    if _readiness_cache["result"] and now - _readiness_cache["ts"] < 5:
        return _readiness_cache["result"]
    # Perform checks...

3. Use connection pooling for DB checks. Opening a new connection on every health check is expensive:

# Reuse the app's connection pool
db_pool = psycopg2.pool.SimpleConnectionPool(1, 5, dsn=DATABASE_URL)

def check_database():
    conn = db_pool.getconn()
    try:
        cursor = conn.cursor()
        cursor.execute("SELECT 1")
        cursor.close()
        return True
    finally:
        db_pool.putconn(conn)

4. Parallelize dependency checks. Check multiple dependencies concurrently:

import concurrent.futures

def readiness():
    with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
        db_future = executor.submit(check_database)
        cache_future = executor.submit(check_cache)
        queue_future = executor.submit(check_message_queue)

        checks = {
            "db": db_future.result(timeout=2),
            "cache": cache_future.result(timeout=2),
            "queue": queue_future.result(timeout=2),
        }
    return checks

5. Use TCP probes for very lightweight checks. If HTTP parsing overhead matters, use a TCP socket probe:

livenessProbe:
  tcpSocket:
    port: 8080
  periodSeconds: 10