Health and Readiness Check Endpoints
Langfuse provides monitoring endpoints to check the health and readiness of your self-hosted deployment. These endpoints are essential for load balancers, orchestration systems, and monitoring tools.
Overview
| Container | Endpoint | Purpose |
|---|---|---|
| langfuse-web | /api/public/health | Check if the web service is healthy |
| langfuse-web | /api/public/ready | Check if the web service is ready to receive traffic |
| langfuse-worker | /api/health | Check if the worker service is healthy |
Health Check Endpoints
Health checks verify that the application is running and operational.
Web Container Health Check
curl http://localhost:3000/api/public/healthDefault Behavior:
- By default, this endpoint only checks if the API is running
- It does not validate database connectivity to allow serving traffic even when the database is temporarily unavailable
- To include database connectivity in the health check, add the query parameter:
curl http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true
Response Codes:
200 OK- API is functioning normally (and database is reachable if parameter is used)503 Service Unavailable- API is not functioning or database is unreachable (when parameter is used)
Worker Container Health Check
curl http://localhost:3030/api/healthResponse Codes:
200 OK- Worker service is functioning normally and database connection is successful503 Service Unavailable- Worker service is not functioning or cannot connect to the database
Event propagation staleness (v4 dual write):
While a v3 to v4 migration runs in the dual write mode, the worker executes an event-propagation job that moves data from older SDKs into the new events tables.
A dedicated probe can fail when this job stops making progress:
curl "http://localhost:3030/api/health?failIfEventPropagationStuck=true"- Returns
503when the job's last run started more thanLANGFUSE_EVENT_PROPAGATION_STUCK_THRESHOLD_MINUTES(default15) ago. The response body includes diagnostics (last run time, current propagation delay). - The check reads only Redis and never fails on deployments where the job does not run (write mode
legacyorevents_only, or the queue consumer disabled), so it is safe to keep configured permanently. - A job that has not run yet (e.g., right after a restart) is not considered stuck.
When using this parameter in a Kubernetes liveness probe, set initialDelaySeconds to at least 60: the heartbeat only refreshes when the job's minute-boundary cron next runs, so a shorter delay can crash-loop a freshly restarted container.
Readiness Check Endpoint
The readiness check indicates whether the web application is ready to receive traffic, particularly useful during graceful shutdowns.
curl http://localhost:3000/api/public/readyResponse Codes:
200 OK- Application is ready to serve traffic500 Internal Server Error- Application has received a shutdown signal (SIGTERM or SIGINT) and should not receive new traffic
Last edited
