Langfuse v4
Langfuse v4 rebuilds the data model around observations: trace-level attributes live on every observation, and records are immutable (written once, never updated). Reads no longer need joins or deduplication, so queries run an order of magnitude faster at scale. This page explains what changed and why. To migrate, follow the step-by-step upgrade guide; the Versions & Compatibility matrix shows what works with what.
New to Langfuse? There is nothing to migrate. Start with the get started guide; it already uses v4.
Timeline
On Langfuse Cloud, review your project's remaining migration actions in the app.
Upgrade
Follow the step-by-step upgrade guide. It covers each situation: Langfuse Cloud with older SDKs, Langfuse Cloud with current SDKs, direct API and OpenTelemetry users, and self-hosted deployments.
What changed
The new mental model: Langfuse stores one immutable observations table. A trace is simply all rows that share a trace_id, and trace-level attributes are copied onto every row:
| Observation-level data | Trace-level data · on every row | ||||||
|---|---|---|---|---|---|---|---|
| id | type | name | latency | trace_id | trace_name | user_id | session_id |
| obs-1 | span | handle-chat | 3.1s | abc123 | chat-request | u-42 | s-7 |
| obs-2 | span | retrieval | 0.4s | abc123 | chat-request | u-42 | s-7 |
| obs-3 | generation | llm-call | 2.6s | abc123 | chat-request | u-42 | s-7 |
| obs-4 | span | build-report | 1.2s | def789 | export-report | u-17 | s-9 |
| obs-5 | generation | summarize | 0.9s | def789 | export-report | u-17 | s-9 |
Trace-level input/output is deprecated across the product. Every feature that previously read a trace's input and output (tables in the UI, LLM-as-a-judge evaluators, exports) now reads the input and output of the right observation, typically the root span or the LLM call that holds the relevant data. Selecting one observation with the right data instead of assembling it across a whole trace is a big part of the faster loading times.
Why observations-first: two problems drove this change. First, agentic traces got big, and a single trace input/output is no longer what you are interested in: you care about a specific sub-agent, a specific tool call, or a specific LLM call inside the run. With observations as the primary entity you query those directly ("which LLM calls are slow?"), and observation-level evaluations run in seconds. Second, scalability: applications continuously updated the trace output as the agent progressed, and every update created another record version that Langfuse had to deduplicate at read time, degrading performance across the product. Immutable observations remove that cost. The data model docs explain the model; the observations guide covers day-to-day workflows in the UI.
Cloud rollout details (until the v4 cutover)
- Organizations created on or after April 14, 2026, 14:00 UTC run v4 by default and do not see a toggle.
- Organizations created before that date can switch the Preview toggle (bottom-left in the UI) on and off until Langfuse Cloud becomes v4-only (date will follow).
- Cloud projects created on or after May 20, 2026 are locked to the "enriched observations" export source; new legacy export integrations cannot be created since June 22, 2026.
Questions
Ask rollout and migration questions in the dedicated GitHub Discussion; we use that thread for updates and answers.
Step-by-step upgrade guide
Versions & Compatibility
Working with observations
Ask questions on Langfuse v4
Last edited
