Comprehensive checklist for deploying Langfuse observability to production with verified configuration, error handling, graceful shutdown, and monitoring.
Confirm production API keys are created, stored in a secrets manager, NOT in code/git, and isolated per environment. Verify PII scrubbing is enabled.
Set flushAt (15-50), flushInterval (5-10s), requestTimeout (10-30s), enabled (true for prod). Use singleton client pattern.
Wrap all trace operations in try/catch. Call .end() in finally blocks. Log errors to Langfuse with ERROR level. Register shutdownAsync() on SIGTERM/SIGINT.
Validate env vars are set, API keys are production keys (prefix pk-lf-), trace creation works, and graceful shutdown completes.
Expose metrics endpoint tracking traces created/failed, flush latency, and error rate.
See detailed implementation for advanced patterns.
| Issue | Cause | Solution |
|---|---|---|
| Missing traces in prod | Flush not called | Verify shutdown handler |
| High latency | Large batches | Reduce flushAt |
| Memory growth | Client recreation | Use singleton pattern |
| Lost traces on deploy | No graceful shutdown | Add SIGTERM handler |
| Category | Key Items |
|---|---|
| Auth & Security | Prod keys, secrets manager, env isolation, PII scrubbing |
| SDK Config | flushAt=25, flushInterval=5000, singleton client |
| Error Handling | try/catch, .end() in finally, ERROR level traces |
| Performance | Async tracing, batching, no memory leaks |
| Observability | Trace URL logging, SDK error monitoring, alerts |
{
flushAt: 25,
flushInterval: 5000, # 5000: 5 seconds in ms
requestTimeout: 15000, # 15000 = configured value
enabled: process.env.NODE_ENV === "production",
debug: false,
}