# 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".

- Skill: `micsapp/langfuse-reference-architecture` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add micsapp/langfuse-reference-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/micsapp/langfuse-reference-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: micsapp (https://skillmd.com/u/micsapp)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/micsapp/langfuse-reference-architecture

---

# Langfuse Reference Architecture

## Contents
- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Instructions](#instructions)
- [Output](#output)
- [Error Handling](#error-handling)
- [Examples](#examples)
- [Resources](#resources)

## Overview
Production-grade architecture patterns for Langfuse LLM observability at scale, covering singleton SDK, context propagation, queue-based ingestion, and multi-environment configs.

## Prerequisites
- Understanding of distributed systems
- Knowledge of cloud infrastructure
- Familiarity with observability patterns

## Instructions

### Step 1: Implement Singleton SDK Pattern
Create a singleton Langfuse client with graceful shutdown handlers for SIGTERM/SIGINT.

### Step 2: Add Trace Context Propagation
Use `AsyncLocalStorage` to propagate trace context across async operations. Add Express middleware to auto-create traces.

### Step 3: Implement Queue-Based Ingestion
For high-volume (10M+ traces/day), buffer events through SQS/Kafka with async worker consumers.

### Step 4: Configure Multi-Environment Settings
Set environment-specific flush intervals, batch sizes, and sampling rates (dev: 100%, staging: 50%, prod: 10%).

### Step 5: Implement Service Mesh Tracing
Inject/extract trace headers (`x-langfuse-trace-id`) for cross-service trace correlation.

See [detailed implementation](${CLAUDE_SKILL_DIR}/references/implementation.md) for advanced patterns.

## Output
- Singleton SDK pattern with graceful shutdown
- Trace context propagation via AsyncLocalStorage
- Queue-based async ingestion for high volume
- Multi-environment configuration
- Service mesh header injection

## Error Handling
| Issue | Cause | Solution |
|-------|-------|----------|
| Multiple instances | No singleton | Use singleton pattern |
| Lost traces | No shutdown handler | Register SIGTERM handler |
| Cross-service gaps | No propagation | Implement header injection |
| Scale issues | Direct ingestion | Add message queue buffer |

## Examples

### Architecture Decision Matrix
| Pattern | Use Case | Complexity | Scale |
|---------|----------|------------|-------|
| Basic Cloud | Small apps | Low | 100K traces/day |
| Self-Hosted | Data privacy | Medium | 1M traces/day |
| Queue-Based | High volume | High | 10M+ traces/day |

## Resources
- [Langfuse Self-Hosting](https://langfuse.com/docs/deployment/self-host)
- [Langfuse Architecture](https://langfuse.com/docs)
- [OpenTelemetry Context](https://opentelemetry.io/docs/concepts/context-propagation/)