Health Check Endpoints: Reporting App Status

Why it exists

In distributed systems, an orchestrator like Kubernetes or a load balancer needs an automated way to know if a specific server instance is functioning correctly. Without this signal, they might send user traffic to a dead, overloaded, or misconfigured server, causing errors.

The mental model

Think of a health check endpoint as your application's pulse. An external system pings this endpoint to ask two questions. First, 'Are you alive?' (liveness). If there's no pulse, the system might try to resuscitate it by restarting the container. Second, 'Are you ready for work?' (readiness). If the app is alive but busy or waiting for a dependency, it can signal that it's not ready, and the system will stop sending it new tasks for a while.

How it works

You create a specific route, like /healthz, in your Express application. When this endpoint receives a request, it performs checks. A simple liveness check might just respond with a 200 OK status to show the server process is running. A readiness check should verify connections to databases, message queues, or other critical services. If all checks pass, it returns a 200 OK. If a check fails, it returns a 5xx error, signaling to the orchestrator that the instance is unhealthy.

When to use it

Always use health checks when deploying applications in containerized or load-balanced environments. Orchestration platforms like Kubernetes rely on 'liveness' probes to know when to restart a faulty container and 'readiness' probes to know when an instance is prepared to be added to a service's load balancer. This prevents routing traffic to pods that are still starting up or have encountered a critical error.

When not to use it

There's rarely a reason not to have a basic health check. However, avoid making your health check too complex, slow, or resource-intensive. A check that puts significant load on the system or has its own failure modes can cause cascading failures. A liveness check, in particular, should be extremely lightweight and reliable, as a failure leads to a disruptive restart.

One canonical example

Kubernetes distinguishes between liveness and readiness. A liveness probe at /healthz could simply check if the Express server is responsive. If it fails, Kubernetes restarts the container. A readiness probe at /readyz would perform a more thorough check, like verifying the app can connect to its database. If the database connection is lost, the endpoint fails, and Kubernetes stops sending traffic to that pod until the connection is restored, preventing user-facing errors.