Skip to main content
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".
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill langfuse-reference-architectureThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository Implement user sign-up and sign-in flows with Clerk.
Use when building authentication UI, customizing sign-in experience,
or implementing OAuth social login.
Trigger with phrases like "clerk sign-in", "clerk sign-up",
"clerk login flow", "clerk OAuth", "clerk social login".
Implement session management and middleware with Clerk.
Use when managing user sessions, configuring route protection,
or implementing token refresh and custom JWT templates.
Trigger with phrases like "clerk session", "clerk middleware",
"clerk route protection", "clerk token", "clerk JWT".
Configure enterprise SSO, role-based access control, and organization management.
Use when implementing SSO integration, configuring role-based permissions,
or setting up organization-level controls.
Trigger with phrases like "clerk SSO", "clerk RBAC",
"clerk enterprise", "clerk roles", "clerk permissions", "clerk organizations".
Related occupations SOC
Based on SOC occupation classification
name langfuse-reference-architecture 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 version 1.12.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","langfuse","deployment","observability","llm"] compatibility Designed for Claude Code, also compatible with Codex and OpenClaw
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
import { LangfuseClient } from "@langfuse/client" ;
import { LangfuseSpanProcessor } from "@langfuse/otel" ;
import { NodeSDK } from "@opentelemetry/sdk-node" ;
import { AsyncLocalStorage } from "async_hooks" ;
let sdk : NodeSDK | null = null ;
export function initTracing (
if
return
new
NodeSDK
spanProcessors
new
LangfuseSpanProcessor
exportIntervalMillis
5000
maxExportBatchSize
50
start
for
const
of
"SIGTERM"
"SIGINT"
on
async
console
log
`Received ${signal} , flushing traces...`
await
shutdown
exit
0
return
let
client
LangfuseClient
null
null
export
function
getLangfuseClient
LangfuseClient
if
new
LangfuseClient
return
interface
RequestContext
userId
string
sessionId
string
requestId
string
const
new
AsyncLocalStorage
RequestContext
export
function
getRequestContext
RequestContext
undefined
return
getStore
export
function
ctx
RequestContext
fn
() =>
return
run
Pattern 2: Express Middleware for Automatic Tracing
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 ,
},
});
const originalEnd = res.end .bind (res);
res.end = function (...args : any [] ) {
updateActiveObservation ({
output : { statusCode : res.statusCode },
});
return originalEnd (...args);
} as any ;
next ();
}).catch (next);
});
};
}
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:
import { context, propagation } from "@opentelemetry/api" ;
async function callServiceB (data : any const headers : Record <string , string > = {};
propagation.inject (context.active (), headers);
const response = await fetch ("https://service-b.internal/api/process" , {
method : "POST" ,
headers : {
"Content-Type" : "application/json" ,
...headers,
},
body : JSON .stringify (data),
});
return response.json ();
}
import { context, propagation } from "@opentelemetry/api" ;
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing" ;
app.post ("/api/process" , async (req, res) => {
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
type Environment = "development" | "staging" | "production" ;
const configs : Record <Environment , {
exportIntervalMillis : number ;
maxExportBatchSize : number ;
sampleRate : number ;
}> = {
development : {
exportIntervalMillis : 1000 ,
maxExportBatchSize : 1 ,
sampleRate : 1.0 ,
},
staging : {
exportIntervalMillis : 5000 ,
maxExportBatchSize : 25 ,
sampleRate : 0.5 ,
},
production : {
exportIntervalMillis : 10000 ,
maxExportBatchSize : 100 ,
sampleRate : 0.1 ,
},
};
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:
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);
}
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)" );
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 