Langfuse 2025 Patterns

---

📦 Dependencies & Versions

• Langfuse TypeScript SDK: v4 (GA Sep 2025, OTEL-native) and v5 (Mar 2026). Modularized into @langfuse/tracing and @langfuse/otel.
• Experiment Runner SDK: Released Sep 2025 (Python and JS/TS).
• Integrations: Out-of-the-box tracing for OpenAI, LangChain, Vercel AI SDK, and Mastra.

---

🚀 Quick Start: Experiment Runner SDK

The Experiment Runner SDK shifts prompt experiments from the UI into code. It enables programmatic execution of evaluation logic for CI/CD pipelines.

# Programmatic experiment execution (Python)
from langfuse import Langfuse
langfuse = Langfuse()
 
# Fetch dataset (supports historical version timestamps as of 2026)
dataset = langfuse.get_dataset("your-dataset-name")
 
# Run concurrent execution with automatic tracing and error isolation
dataset.run_experiment(
    name="regression-test",
    task=my_llm_app_function,
    # Inject item-level or run-level evaluators here
)

---

💡 Best Practices & Patterns

• Programmatic CI/CD Evals: Utilize the Experiment Runner SDK to automate regression testing in CI/CD. Fetch datasets using version timestamps to guarantee reproducible runs against historical states.
• Structured Output Enforcement: Always enforce JSON schema response formats in Prompt Experiments. This guarantees deterministic outputs, simplifying programmatic evaluation and metric extraction.
• Natural Language Trace Queries: Use Natural Language Filtering to debug traces intuitively instead of building complex filter queries. Query examples like “show traces where latency spiked after 3 PM” are processed securely via AWS Bedrock (zero data retention).
• OTEL-Native Tracing: Attach the LangfuseSpanProcessor to your global OpenTelemetry NodeSDK to capture standard trace data. This standardizes observability across your stack.

---

🚨 Gotchas / Warnings (Anti-patterns)

• SDK v3 Legacy Methods: Do not use langfuse.trace() or proprietary tracing structures. TypeScript SDK v4+ exclusively expects OpenTelemetry-compatible span models.
• Orphaned OTEL Traces: Avoid conflicting span processors when integrating Langfuse alongside tools like Sentry or Datadog. You must explicitly configure export filters or properly attach processors to the global TracerProvider to prevent missing data.
• Relying on UI for Core Evals: Stop configuring mission-critical evaluations solely in the Langfuse UI. Move complex logic into code using the Experiment Runner SDK to ensure version control and custom evaluator integration.
• Stagnating on SDK v4: Do not start new projects on v4 as it is now considered legacy as of mid-2026. Upgrade directly to TypeScript SDK v5 following the v4 → v5 migration guide.

---

🔍 Research / References

• Langfuse Changelog: Agentic Workflows and 2025 Platform Updates
• Langfuse Docs: Experiments via SDK