App Health Endpoint Design: 3 Probes That Keep Logging and Metrics Useful

When crafting health probes for a Node.js application running in Docker or Kubernetes, it is crucial to differentiate their meanings and purpose. Startup probes determine if initialization is complete, readiness probes assess whether the instance can safely receive new requests, while liveness probes evaluate if the process is stuck beyond local recovery. Routine health checks should be excluded from application logging to prevent log noise.

For a property management API rolling out a new pricing rule, useful metrics can be preserved by measuring state transitions instead of counting every successful check. This distinction ensures that an instance can calculate rent correctly and accept traffic, without turning each kubelet poll into unnecessary noise.

When selecting which health signal controls each container decision, start with the decision, not the endpoint name. The signal should answer the following question: What should control the container decision? For example, if the focus is on whether initialization has completed, implement a startup probe. If the focus is on whether the instance can safely receive a new pricing request, implement a readiness probe. If the focus is on detecting if the process is stuck, implement a liveness probe.

Each container decision should be guided by the appropriate health signal. The startup probe determines if initialization has completed, allowing the process more time before applying other probes. The readiness probe checks if the instance can safely receive a new pricing request, removing the pod from Service endpoints if not ready. The liveness probe checks if the process is stuck beyond local recovery, restarting the container if needed.

This split is essential for filtering out noise. A downstream dependency becoming unavailable can make a pod unready, but restarting the same healthy process may not repair that dependency. If the dependency is placed in liveness instead, every pod can restart together, amplifying the problem. By keeping the health response narrow and focused on the specific condition, lost capacity and restart storms can be avoided.

When implementing Kubernetes probes for a beginner Node.js health endpoint, it is recommended to use distinct paths even if they share one small server. The handlers should avoid network calls in liveness, return a 503 status when startup or readiness has not been reached, and expose no tenant or property details. A status of 204 is sufficient for success, as the kubelet only needs status information, not a diagnostic document.

In the provided code snippet, the healthServer listens for GET requests on three specific URLs: /health/startup, /health/ready, and /health/live. The startup probe checks if initialization has completed, returning a 204 status if true and a 503 status if not. The readiness probe verifies if the instance can safely receive a new pricing request, considering the active rule version and dependency state.

If not ready, it returns a 503 status. The liveness probe evaluates the event loop's responsiveness, returning a 204 status if responsive and a 503 status otherwise. This approach ensures that each probe serves its intended purpose, keeping the application healthy and responsive while minimizing unnecessary noise and restarts.