langfuse-reference-architecture
Production-grade Langfuse architecture patterns and best practices. Use when designing LLM observability infrastructure, planning Langfuse deployment, or implementing enterprise-grade tracing architecture. Trigger with phrases like "langfuse architecture", "langfuse design", "langfuse infrastructure", "langfuse enterprise", "langfuse at scale".
- License 许可
- MIT
- 最近更新
- 2026-07-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- langfuse-reference-architecture
- tags
- [ "saas", "langfuse", "deployment", "observability", "llm" ]
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- description
- Production-grade Langfuse architecture patterns and best practices. Use when designing LLM observability infrastructure, planning Langfuse deployment, or implementing enterprise-grade tracing architecture. Trigger with phrases like "langfuse architecture", "langfuse design", "langfuse infrastructure", "langfuse enterprise", "langfuse at scale".
- allowed-tools
- Read, Write, Edit
- compatible-with
- claude-code, codex, openclaw
03 SKILL.md 正文
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
// 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 ["SIGTERM", "SIGINT"]) {
process.on(signal, async () => {
console.log(`Received ${signal}, flushing traces...`);
await sdk?.shutdown();
process.exit(0);
});
}
return sdk;
}
// Singleton client for non-tracing operations
let client: LangfuseClient | null = null;
export function getLangfuseClient(): LangfuseClient {
if (!client) client = new LangfuseClient();
return client;
}
// Request context for user/session tracking
interface RequestContext {
userId?: string;
sessionId?: string;
requestId: string;
}
const requestStore = new AsyncLocalStorage<RequestContext>();
export function getRequestContext(): RequestContext | undefined {
return requestStore.getStore();
}
export function runWithContext<T>(ctx: RequestContext, fn: () => T): T {
return requestStore.run(ctx, fn);
}
Pattern 2: Express Middleware for Automatic Tracing
// src/middleware/tracing.ts
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";
import { runWithContext, getRequestContext } from "../lib/tracing";
import { randomUUID } from "crypto";
import type { Request, Response, NextFunction } from "express";
export function langfuseMiddleware() {
return (req: Request, res: Response, next: NextFunction) => {
const ctx = {
requestId: req.headers["x-request-id"]?.toString() || randomUUID(),
userId: req.headers["x-user-id"]?.toString(),
sessionId: req.headers["x-session-id"]?.toString(),
};
runWithContext(ctx, () => {
startActiveObservation(`${req.method} ${req.path}`, async () => {
updateActiveObservation({
input: {
method: req.method,
path: req.path,
query: req.query,
},
metadata: {
userId: ctx.userId,
sessionId: ctx.sessionId,
requestId: ctx.requestId,
},
});
// Capture response
const originalEnd = res.end.bind(res);
res.end = function (...args: any[]) {
updateActiveObservation({
output: { statusCode: res.statusCode },
});
return originalEnd(...args);
} as any;
next();
}).catch(next);
});
};
}
// Usage
import express from "express";
import { initTracing } from "./lib/tracing";
import { langfuseMiddleware } from "./middleware/tracing";
initTracing();
const app = express();
app.use(langfuseMiddleware());
Pattern 3: Cross-Service Trace Correlation
For microservices, propagate trace context via HTTP headers:
// Service A: Inject trace context into outbound requests
import { context, propagation } from "@opentelemetry/api";
async function callServiceB(data: any) {
const headers: Record<string, string> = {};
// OTel propagation injects traceparent header automatically
propagation.inject(context.active(), headers);
const response = await fetch("https://service-b.internal/api/process", {
method: "POST",
headers: {
"Content-Type": "application/json",
...headers, // Includes traceparent, tracestate
},
body: JSON.stringify(data),
});
return response.json();
}
// Service B: Extract and continue trace context
import { context, propagation } from "@opentelemetry/api";
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";
app.post("/api/process", async (req, res) => {
// OTel automatically extracts context from incoming headers
// when using standard HTTP instrumentation.
// Any startActiveObservation call will be a child of the extracted trace.
await startActiveObservation("service-b-process", async () => {
updateActiveObservation({ input: req.body });
const result = await processData(req.body);
updateActiveObservation({ output: result });
res.json(result);
});
});
Pattern 4: Multi-Environment Configuration
// src/config/langfuse.ts
type Environment = "development" | "staging" | "production";
const configs: Record<Environment, {
exportIntervalMillis: number;
maxExportBatchSize: number;
sampleRate: number;
}> = {
development: {
exportIntervalMillis: 1000, // Immediate visibility
maxExportBatchSize: 1,
sampleRate: 1.0, // Trace everything
},
staging: {
exportIntervalMillis: 5000,
maxExportBatchSize: 25,
sampleRate: 0.5, // 50% sampling
},
production: {
exportIntervalMillis: 10000,
maxExportBatchSize: 100,
sampleRate: 0.1, // 10% sampling
},
};
export function getTracingConfig() {
const env = (process.env.NODE_ENV || "development") as Environment;
return configs[env] || configs.development;
}
Pattern 5: Graceful Degradation
When Langfuse is unavailable, the app must keep running:
// The v4+ SDK with OTel handles this gracefully:
// - Failed exports are logged but don't throw
// - Events are buffered in the queue
// - Queue drops oldest events when maxQueueSize is exceeded
//
// For additional safety at the application level:
import { observe, updateActiveObservation } from "@langfuse/tracing";
let tracingHealthy = true;
let consecutiveFailures = 0;
const MAX_FAILURES = 10;
export function safeTrace<T extends (...args: any[]) => Promise<any>>(
name: string,
fn: T
): T {
return (async (...args: Parameters<T>) => {
if (!tracingHealthy) {
return fn(...args); // Circuit breaker open
}
try {
const result = await observe({ name }, async () => {
updateActiveObservation({ input: args });
const r = await fn(...args);
updateActiveObservation({ output: r });
return r;
})();
consecutiveFailures = 0;
return result;
} catch (error) {
consecutiveFailures++;
if (consecutiveFailures >= MAX_FAILURES) {
tracingHealthy = false;
console.error("Langfuse tracing disabled (circuit breaker open)");
// Re-enable after 5 minutes
setTimeout(() => { tracingHealthy = true; consecutiveFailures = 0; }, 300000);
}
return fn(...args);
}
}) as T;
}
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 |
Resources
04 同仓库更多 Skills
zustand-store-creator
Create zustand store creator operations. Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like "zustand store creator", "zustand creator", "zustand".
zero-trust-config-helper
Configure with zero trust config helper operations. Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like "zero trust config helper", "zero helper", "zero".
zapier-integration-helper
Assist with zapier integration helper operations. Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like "zapier integration helper", "zapier helper", "zapier".
yaml-config-validator
Validate yaml config validator operations. Auto-activating skill for DevOps Basics. Triggers on: yaml config validator, yaml config validator Part of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like "yaml config validator", "yaml validator", "yaml".
xvary-stock-research
Thesis-driven equity analysis from public SEC EDGAR and market data; /analyze, /score, /compare workflows with bundled Python tools (Claude Code, Cursor, Codex).
xss-vulnerability-scanner
Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals. Triggers on: xss vulnerability scanner, xss vulnerability scanner Part of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like "xss vulnerability scanner", "xss scanner", "xss".