Skip to main content Início Criadores jeremylongshore tons-of-skills-marketplace langfuse-reference-architecture
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".
Ir para a instalação Skills Marketplace Descubra e explore skills de IA criadas pela comunidade.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Mostrar detalhes do prompt Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace --skill langfuse-reference-architectureO comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.
Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.
Baixar Zip Baixando... Mais deste repositório langchain-deploy-integration Deploy a LangChain 1.0 / LangGraph 1.0 app to Cloud Run, Vercel, or LangServe correctly — with timeouts sized for chain length, cold-start mitigation, SSE anti-buffering headers, and Secret Manager over .env. Use when prepping a first production deploy, debugging a stream that hangs behind a proxy, or diagnosing p99 latency spikes. Trigger with "langchain deploy", "langchain cloud run", "langchain vercel python", "langchain langserve", or "langchain docker".
langchain-langgraph-agents Build a correct LangGraph 1.0 ReAct agent with create_react_agent — typed tools, error propagation, recursion caps, and stop conditions that actually stop. Use when writing a first tool-calling agent, migrating from AgentExecutor or initialize_agent, or diagnosing an agent that loops on vague prompts. Trigger with "langgraph agent", "create_react_agent", "langgraph tool calling", "AgentExecutor migration", or "agent loop cost".
langchain-langgraph-human-in-loop Build LangGraph 1.0 human-in-the-loop approval flows with interrupt_before /
interrupt_after and Command(resume=...) — JSON-serializable state, clean
resume semantics, and UI wiring for approval decisions. Use when adding an
approval gate before an expensive tool call, wiring a Slack/web UI for agent
approvals, or debugging a graph that crashes on interrupt.
Trigger with "langgraph human in loop", "langgraph interrupt_before",
"langgraph approval flow", "Command resume", "langgraph HITL".
Explorador de arquivos
2 arquivos 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
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 