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

Health Check Endpoints

Health checks verify that the application is running and operational.

Web Container Health Check

curl http://localhost:3000/api/public/health

Default 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/health

Response Codes:

• 200 OK - Worker service is functioning normally and database connection is successful
• 503 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 503 when the job's last run started more than LANGFUSE_EVENT_PROPAGATION_STUCK_THRESHOLD_MINUTES (default 15) 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 legacy or events_only, or the queue consumer disabled), so it is safe to keep configured permanently.
• A job that has never run — for example, on a deployment that has not enabled the dual write mode yet — is not considered stuck. The heartbeat lives in Redis, so it survives container restarts; see the probe guidance below for restarts.

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/ready

Response Codes:

• 200 OK - Application is ready to serve traffic
• 500 Internal Server Error - Application has received a shutdown signal (SIGTERM or SIGINT) and should not receive new traffic