Agent skill · software engineering · jeremylongshore
langfuse-reference-architecture
Production-grade Langfuse architecture patterns and best practices.
Why this skill is useful
Adds executable scripts and architecture patterns for implementing Langfuse observability that are not widely documented.
What it needs
Requires node installed locally. About 5k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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 Pattern 2: Express Middleware for Automatic Tracing Pattern 3: Cross-Service Trace Correlation For microservices, propagate trace context via HTTP headers: Pattern 4: Multi-Environment Configuration Pattern 5: Graceful Degradation When Langfuse is unavailable, the app must keep running: Architecture Decision Matrix Decision Starter Growth Enterprise ---------- --------- -------- ------------ Langfuse host Cloud Cloud or Self-hosted Self-hosted (HA) SDK version v4+ v4+ v4+ with custom processor Sampling 100% 50-100% 5-20% + error always Context propagation Not needed AsyncLocalStorage OTel + HTTP headers Queue buffer SDK internal SDK internal External (SQS/Kafka) Failover None Log-and-continue Circuit breaker Error Handling Issue Cause Solution ------- ------- ---------- Multiple SDK instances No singleton Centralize in tracing.ts module Lost traces on deploy No SIGTERM handler Register shutdown handler Cross-service trace gaps No context propagation Inject OTel traceparent header Scale bottleneck Direct SDK at high volume Add queue buffer or increase sampling Output Produce an architecture decision record identifying the selected deployment tier, tracing boundary, context-propagation met …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/langfuse-reference-architecture