What is a health check endpoint?
A health check endpoint is a URL, such as /health or /healthz, that your application exposes so load balancers, orchestrators and monitors can ask whether it is working. A good one checks the dependencies the app needs (database, cache, queue), answers quickly with 200 or 503, and returns a short JSON body naming any failed check.
Why a health check endpoint matters
Load balancers and Kubernetes use the answer to route traffic away from broken instances and restart stuck ones. External monitors use it to see inside the app: a homepage can render from cache while the database behind it is down.
A health endpoint that returns 200 because the process is running tells nobody anything. One that checks too much, or too slowly, can take a whole fleet out of rotation because one optional dependency hiccuped.
How to measure a health check endpoint
endpoint time ≈ sum of the dependency checks (run one after another)
≈ slowest dependency check (run in parallel)
keep it well under the caller's timeout
Worked example
Your /health endpoint checks the database (40 ms), Redis (5 ms) and an internal payments API (120 ms). The monitor's timeout is 2 seconds and the load balancer's is 500 ms.
- Run one after another: 40 + 5 + 120 = 165 ms.
- Run in parallel: max(40, 5, 120) = 120 ms.
- Both fit under 500 ms today, but if the payments API slows to 600 ms the load balancer marks every instance unhealthy at once.
Result: Keep optional dependencies out of the load balancer's check, or report them as degraded without failing it, and give the external monitor the detailed version.
Common mistakes
- Liveness that checks dependencies. In Kubernetes, a liveness probe that fails when the database is down restarts every pod, which fixes nothing. Put dependencies in readiness and keep liveness for the process itself.
- Always returning 200. Report failure with a 503 status, or at least an explicit status field, so callers can act on it.
- Expensive checks. A heavy query on every probe adds load. Use cheap checks such as
SELECT 1. - Leaking internals. Error messages, host names and versions in a public health response help attackers. Protect the detailed output with a secret header or keep it internal.
How Vigil handles a health check endpoint
- Vigil's App health monitor reads your app's own health JSON: Laravel Health, Spring Boot Actuator, the Oh Dear format or a plain
{"status":"ok"}, and can send a secret header so the detailed endpoint stays private. - An API check can also call the endpoint and assert on the body, for example
json checks.database == ok, with a response-time limit. - The guides for Django, FastAPI and Laravel cover what else to watch in those frameworks.
Health check endpoint: frequently asked questions
What should a health check return?
HTTP 200 with a short JSON body when healthy, 503 when not, and a field per dependency so a person can see which part failed. Keep it fast and free of secrets.
What is the difference between liveness and readiness?
Liveness asks whether the process should be restarted; readiness asks whether it should receive traffic right now. Dependencies belong in readiness, not liveness.
Should the health endpoint be public?
A minimal status can be public; detailed output should be protected, for example by a secret header that only your monitor sends.