Langfuse Pack Patterns

Core Intent: High-density extraction of Patterns, Anti-patterns, and Best Practices for Langfuse LLM Observability using the IntentSolutions.io Langfuse Skill Pack.

💡 BEST PRACTICES & PATTERNS

• Singleton Client Initialization: Instantiate a single global Langfuse client/SDK instance. Reusing the client avoids memory leaks and prevents duplicate trace initialization.
• Tracing Wrappers (v4+): Use the observe wrapper for ergonomic function tracing without internal rewrites. For inline lifecycle control, use startActiveObservation.
• AsyncLocalStorage & Middleware: Use Node’s AsyncLocalStorage for robust trace context propagation. Create Express middleware to automatically generate traces for incoming requests.
• Cross-Service Correlation: Propagate trace context between microservices via HTTP headers using OpenTelemetry (@opentelemetry/api).
• Graceful Shutdown: Register SIGTERM/SIGINT handlers to call sdk.shutdown() (v4+) or langfuse.flushAsync() (v3) to prevent trace loss on redeploys.
• PII Scrubbing: Implement regex-based PII_PATTERNS (emails, API keys, SSNs) and scrub objects before tracing to maintain data privacy.
• Error-Safe Tracing: Wrap observe calls in try/catch logic. Tracing failures MUST NEVER crash the primary application.
• Multi-Env Isolation: Maintain separate Langfuse projects (dev/staging/prod). Use strictly scoped, securely rotated API keys for each environment.

🚨 ANTI-PATTERNS (Gotchas & Fixes)

❌ Anti-Pattern	⚠️ Impact	✅ Correct Pattern
new Langfuse() per request	Severe memory leaks, duplicate traces.	Singleton Client: Initialize once, export globally.
Awaiting flush() in hot path	Adds massive latency to every LLM request.	Background Flush: Rely on internal batching; flush only on shutdown.
Logging full request bodies	Bloated trace payloads, performance hits.	Truncation: Summarize or truncate large inputs before trace injection.
Missing .end() on spans (v3)	Spans remain “in progress” indefinitely.	Try/Finally: Always end spans in finally, or upgrade to v4 observe.
Hardcoding API keys	Critical security risk.	Env Vars: Inject strictly via environment variables.
High Temperature in CI/CD	Non-deterministic outputs, flaky test suites.	Zero Temp: Set temperature: 0 during CI prompt experiments.

🔧 PERFORMANCE & TUNING CONFIG

• Batch Sizing: Tune flushAt: 25-50 and flushInterval: 5000 for high-volume ingestion.
• Rate Limiting: Implement a BATCH_SIZE loop with DELAY_BETWEEN_BATCHES (e.g., p-queue, backoff) to handle 429 API responses gracefully.
• Timeouts: Configure a standard requestTimeout: 15000 to prevent hanging telemetry requests.
• Graceful Degradation: Use an asynchronous queue buffer. If Langfuse is unreachable, drop the oldest telemetry events rather than blocking the application layer.