Langfuse v4: Planning the Move to the Observations Data Model

Langfuse v4 changes how the platform stores and queries telemetry. One denormalized table of observations replaces the separate trace and observation tables that older versions joined at read time. Each LLM call, tool execution and agent step becomes one queryable row.

The change has a date attached. Langfuse Cloud removes its v3 APIs, features and ingestion on 16 November 2026. Self-hosted v3 receives security patches until the end of January 2027. This article explains what changed, what breaks, and how to plan the move on either route.

What changed in Langfuse v4

The “Simplify Langfuse for Scale” changelog of 10 March 2026 introduced the new architecture. It states that the main table in Langfuse is now observations, and that each row is one operation, not one trace. A trace becomes a grouping: the set of observations that share a trace_id, filtered like session_id or user_id.

The Langfuse v4 changelog of 17 August 2026 announced that v4 is live on Langfuse Cloud and generally available for self-hosted deployments. It describes three structural changes:

• Queries scan less data. One denormalized observations table replaces read-time joins between traces and observations.
• Ingestion writes less data. Each completed observation is written once.
• Observations are append-only and immutable. Older SDKs sent updates to separate tables that had to be joined and deduplicated at query time.

The same release groups several features that build on the new model. These include monitors for cost, quality and latency thresholds, code evaluators that run deterministic Python or TypeScript checks on live observations and experiments, full-text search, and Halo, the in-app assistant. It also introduces the Observations API v2, with selected fields and cursor-based pagination, and the Metrics API v2 for aggregating cost, tokens, volume, latency and scores.

Langfuse publishes performance claims for v4 on these pages. Treat them as vendor statements and measure your own projects before and after the move.

Why the data model matters to engineering teams

For most teams the visible change is the table they work in. The guide to working with the observations table warns that you will see more rows than in the old traces table, and calls this expected. Engineers who are used to opening a trace and drilling down now filter by observation name, type or model instead.

Three practical consequences follow.

Trace-level attributes must be on every observation

Filters such as user_id, session_id and tags only work if those attributes are present on each observation. The SDKs handle this with propagate_attributes() in Python and propagateAttributes() in JS/TS. The v4 changelog states that Python SDK 4.7.0 or later and JS/TS SDK 5.4.0 or later add these attributes to every observation before ingestion. Instrumentation that sets a user or session only on the root span needs review.

Default views change

The observations guide explains that, with no saved view or shared link, Langfuse applies an Is Root Observation = true filter. That default needs the same minimum SDK versions. It recommends saving a small number of common views for frequent tasks.

Evaluations move to observations

The Versions & Compatibility page states that trace-level evaluators are not supported on the v4 data model. Observation-level evaluators are fully supported. Teams that score whole conversations or agent runs must decide which observation carries the score, often the root observation, and rebuild the evaluator against it.

What breaks: SDKs, APIs, evaluators and exports

The compatibility page and the self-hosted v3-to-v4 migration guide list the surfaces that stop working once a deployment runs v4 defaults. The table summarises them.

Surface	v3 and earlier	v4 replacement
Python SDK	v2 rejected at ingestion; v3 deprecated	v4 (4.7.0 or later) or v5; the compatibility page states v5 needs self-hosted v4.59.0 or later
JS/TS SDK	v3 rejected at ingestion; v4 deprecated	v5 (5.4.0 or later) or v6; v6 needs self-hosted v4.59.0 or later
Ingestion	Legacy batch endpoint at /api/public/ingestion for trace and observation events	OpenTelemetry ingestion at /api/public/otel/v1/traces
Read APIs	Deprecated traces, observations, sessions, scores, metrics and dataset-run endpoints	Observations API v2, Metrics API v2, Scores API v3, Experiments APIs
Evaluators	Trace-level and legacy-dataset LLM-as-a-judge evaluators	Observation targets and experiment targets
Exports	“Traces and observations (legacy)” export source	Enriched observations for blob storage, PostHog and Mixpanel

Two details deserve attention. First, any OpenTelemetry SDK can export to the OTLP endpoint, and on v4 the compatibility page describes an x-langfuse-ingestion-version: 4 header for real-time data. Custom exporters need that change. Second, scores sent directly to /api/public/scores remain fully supported, so not every integration moves.

Internal tools are the usual blind spot. Notebooks, BI extracts, cost reports and cron jobs that call the old read endpoints will fail quietly unless someone owns them.

The Langfuse Cloud route: a fixed deadline

On Langfuse Cloud, v3 and the v4 preview run side by side until 16 November 2026. The v4 changelog states that legacy APIs, features and ingestion are removed after that date. The compatibility page adds that trace ingestion through the legacy path then stops working.

The Cloud upgrade guide describes the support Langfuse provides:

• New projects already use v4 and need no migration.
• Organization owners see a Migration Assistant sidebar and a migration status page listing the SDK, evaluator, API and integration actions detected for each project.
• Owners and admins receive an email summary of the required actions.
• Deprecated SDKs can delay data until the project moves off legacy ingestion.

The assistant only sees what reaches Langfuse. It cannot list every internal consumer of the API, so pair it with your own inventory. Neither page states what happens to historic data on Cloud projects, so confirm that with Langfuse if long retention matters to you.

The self-hosted route: three stable steps

Self-hosted deployments have no forced cutover date. The migration guide splits the work into three independent steps, and states that each step leaves the deployment in a stable state.

1. Upgrade infrastructure while still on v3. v4 needs ClickHouse 25.12 at minimum, with 26.4 recommended, plus PostgreSQL 15 and Redis 7.0 at minimum. Upgrade ClickHouse before the Langfuse server.
2. Upgrade the server to v4 in legacy or dual write mode. The LANGFUSE_MIGRATION_V4_WRITE_MODE variable controls this, and its default is events_only. Set it explicitly, or the upgrade jumps straight to v4 defaults.
3. Move to the new data model. Migrate SDKs, API consumers, evaluators and exports, handle historic data, then cut over to v4 defaults.

The guide gives two options for historic data. The default automated backfill rewrites older data into the new tables in the background, newest first. The guide asks you to plan roughly three times the disk headroom in ClickHouse for it. The alternative is a retention-based rollover: skip the backfill and keep dual-writing until one full data-retention window has passed.

Before any of this, confirm that every v3 background migration has finished. The guide warns that the v4 migrations permanently delete rows that were never copied, and gives a PostgreSQL check on the background_migrations table. Take and test a backup first. For where Langfuse and its data services sit in a wider stack, see our enterprise AI and LLMOps architecture.

Rollback and the point of commitment

The migration guide is direct about rollback. Rolling back to v3 is possible before the cutover, but not by redeploying a v3 image alone. There is no automatic downgrade path once the v4 schema migrations have run. A rollback without a restore requires rewinding the ClickHouse schema with the migrate binary. During legacy or dual mode, the guide states that a rollback loses no data.

The guide calls the cutover the point of commitment. After it, a rollback would miss data written since the switch. In practice this means:

• Run dual write long enough to compare old and new views for your most-used queries.
• Rehearse the rollback in a non-production copy before you rely on it.
• Watch the worker health check for the dual-write propagation job, which the LANGFUSE_EVENT_PROPAGATION_STUCK_THRESHOLD_MINUTES setting controls.
• Agree a cutover window and a named decision owner.

Because ClickHouse carries the new tables, the ClickHouse upgrade is part of the change, not a side task. Teams that run their own ClickHouse should apply the same version policy they use for ClickHouse OSS elsewhere.

Migration checklist

• Record the Langfuse version, route (Cloud or self-hosted) and plan or edition in use.
• List every SDK in use by language and version; target Python 4.7.0 or later and JS/TS 5.4.0 or later at minimum.
• Check that user, session and tag attributes are propagated to every observation.
• Inventory all API consumers, including notebooks, BI extracts and scheduled jobs.
• Rebuild trace-level and legacy-dataset evaluators against observation or experiment targets.
• Move blob storage, PostHog and Mixpanel exports to enriched observations.
• For Cloud, work through the Migration Assistant before 16 November 2026.
• For self-hosted, confirm v3 background migrations finished, upgrade ClickHouse, then start in dual write.
• Choose backfill or retention-based rollover, and size ClickHouse disk for it.
• Rehearse rollback, then cut over with a named owner.

How Bassirah can help

Langfuse is a Bassirah strategic technology partner. We help teams inventory their Langfuse integrations, update instrumentation and evaluators for the observations model, and plan and rehearse self-hosted upgrades, including the ClickHouse layer. See our Langfuse partner page and enterprise AI AgentOps work. Scope, edition and support entitlements are confirmed in each engagement.