langfuse-reference-architecture

# Langfuse Reference Architecture ## Overview Production-grade architecture patterns for Langfuse LLM observability: singleton SDK, context propagation with `AsyncLocalStorage`, cross-service trace correlation, multi-environment configurations, and scale strategies. ## Prerequisites - Understanding of distributed systems and async patterns - Node.js 18+ with OpenTelemetry SDK - For v4+: `@langfuse/tracing`, `@langfuse/otel`, `@opentelemetry/sdk-node` ## Architecture Tiers | Tier | Scale | Architecture | Langfuse Host | |------|-------|-------------|---------------| | Starter | < 100K traces/day | Direct SDK, Cloud | Langfuse Cloud | | Growth | 100K-1M traces/day | Singleton + batching | Cloud or Self-hosted | | Enterprise | 1M+ traces/day | Queue-buffered + sampling | Self-hosted (HA) | ## Instructions ### Pattern 1: Singleton SDK with Context Propagation ```typescript // src/lib/tracing.ts -- Single module for all tracing import { LangfuseClient } from "@langfuse/client"; import { LangfuseSpanProcessor } from "@langfuse/otel"; import { NodeSDK } from "@opentelemetry/sdk-node"; import { AsyncLocalStorage } from "async_hooks"; // Singleton OTel SDK let sdk: NodeSDK | null = null; export function initTracing() { if (sdk) return sdk; sdk = new NodeSDK({ spanProcessors: [ new LangfuseSpanProcessor({ exportIntervalMillis: 5000, maxExportBatchSize: 50, }), ], }); sdk.start(); // Graceful shutdown for (const signal of ["SIGT...