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.

Queue consumption liveness:

Connectivity checks alone cannot detect a worker whose queue consumers have silently stopped — for example after a Redis incident that invalidates BullMQ job locks (FLUSHALL, key eviction, failover; see the cache configuration guide). A dedicated probe can fail when no queue processes jobs anymore:

curl "http://localhost:3030/api/health?failIfQueueConsumptionStuck=true"

• Returns 503 when the worker has neither picked up nor completed a single job — across all queues — for more than LANGFUSE_QUEUE_CONSUMPTION_STUCK_THRESHOLD_MINUTES (default 60). The response body includes diagnostics (registered consumers, last job activity).
• Built-in scheduled jobs keep a healthy worker busy at least once per hour, so use this parameter in a liveness probe to restart a wedged container automatically.
• The signal is tracked in memory per container and measured from worker startup, so a freshly started container gets the full threshold as grace period; no initialDelaySeconds requirement applies.
• Containers that run no queue consumers never fail this check.

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

Container health checks

The curl examples above run from outside the container. The Langfuse images do not include curl, so health checks that run inside the container (Docker Compose healthcheck, ECS healthCheck) need wget, which both images include. Probe 127.0.0.1 rather than localhost, so the check does not depend on how the container resolves localhost.

# docker-compose.yml
services:
  langfuse-web:
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3000/api/public/health"]
  langfuse-worker:
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3030/api/health"]

Kubernetes httpGet probes run outside the container and need no extra tools.