micsapp Langfuse SDK Patterns
Contents
Overview
Best practices and idiomatic patterns for using the Langfuse SDK, covering singleton clients, trace lifecycle, nested spans, decorators, sessions, and scoring.
Prerequisites
- Completed
langfuse-install-authsetup - Understanding of async/await patterns
- Familiarity with LLM application structure
Instructions
Step 1: Use Singleton Client
Create a single Langfuse instance reused everywhere. Register shutdownAsync() for clean exit.
Step 2: Manage Trace Lifecycle
Create trace at operation start. Update with output on success. Update with error level on failure. Never await flush in hot paths.
Step 3: Nest Spans for Complex Operations
Use parent/child spans: validation span, retrieval span, generation for LLM calls. Always call .end().
Step 4: Use Python Decorators
Use @observe() for automatic span creation. Use @observe(as_type="generation") for LLM calls. Access context via langfuse_context.
Step 5: Track Sessions and Users
Link traces across conversation turns using sessionId. Set userId for user-level analytics.
Step 6: Add Evaluation Scores
Score traces with numeric values (0-1) for accuracy, relevance, and user feedback.
See detailed implementation for advanced patterns.
Output
- Singleton client pattern
- Proper trace lifecycle management
- Nested span hierarchy
- Python decorator-based tracing
- Session tracking and scoring
Error Handling
| Pattern | Issue | Best Practice |
|---|---|---|
| Client creation | Multiple instances | Use singleton pattern |
| Trace updates | Missing outputs | Always update on success/error |
| Span nesting | Orphaned spans | Always call .end() in finally |
| Flush timing | Lost data | Use shutdownAsync() on exit |
Examples
Basic usage: Apply langfuse sdk patterns to a standard project setup with default configuration options.
Advanced scenario: Customize langfuse sdk patterns for production environments with multiple constraints and team-specific requirements.