Skip to content

docs(observability): remove v4 data model comparison section #2916

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Lotte-Verheyden merged 3 commits into from
May 14, 2026
+11 −24
Merged

docs(observability): remove v4 data model comparison section #2916

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6d2822e
docs(observability): remove v4 data model comparison section
Lotte-Verheyden May 9, 2026
72631c5
docs(v4): add data model comparison and repoint stale anchor
Lotte-Verheyden May 9, 2026
974467b
Merge branch 'main' into audit-v4-references-docs
Lotte-Verheyden May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 0 additions & 22 deletions content/docs/observability/data-model.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,28 +150,6 @@ There are different types of attributes you can add:
| [Releases & Versions](/docs/observability/features/releases-and-versioning) | Track application versions and component changes |


## Underlying data model

<Callout type="info">
This data model is live on Langfuse Cloud. For OSS deployments, this will be available as of our next major release (v4). See the [changelog post](/changelog/2026-03-10-simplify-for-scale) for more details.
</Callout>

To improve query performance at scale, Langfuse introduces an **observation-centric data model**. In this model, context attributes (`user_id`, `session_id`, `metadata`, `tags`) that previously lived only on the trace are propagated to every observation. This eliminates expensive joins between trace and observation tables, enabling single-table queries.

<Frame fullWidth>
![Observation-centric data model](/images/changelog/2026-03-10-v4-preview/data-model.png)
</Frame>

### What changes
[Guide](/docs/v4) how to adopt the new data model.

| | Classic model | Observation-centric model |
|---|---|---|
| **Storage** | Separate mutable Traces and Observations tables | Single immutable Observations table |
| **Context attributes** | Stored on the trace, joined at query time | Propagated to every observation on SDK side. |
| **Trace input/output** | Set directly on the trace | Removed, use observation IO instead. (For legacy LLM-as-a-judge evaluators that depend on trace input and output, users can use the deprecated `set_trace_io` methods in the SDKs.) |
| **Mutability** | Traces and observations are mutable | Observations are immutable (written once) |

## How Langfuse Captures Data
Comment thread
claude[bot] marked this conversation as resolved.

Now that you understand the data model, let's explore how Langfuse actually captures and processes your traces.
Expand Down
11 changes: 10 additions & 1 deletion content/docs/v4.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ The new [Observations API v2](/docs/api-and-data-platform/features/observations-

[Observation-level evaluations](/docs/evaluation/evaluation-methods/llm-as-a-judge) execute in seconds as we do not need to query ClickHouse for each evaluation anymore.

## Under the hood
## Under the hood [#under-the-hood]

<Frame fullWidth>
![Langfuse data model
Expand All @@ -128,6 +128,15 @@ The new [Observations API v2](/docs/api-and-data-platform/features/observations-

This preview is powered by a simplified observation-centric data model. Trace-level attributes such as `user_id`, `session_id`, and `metadata` now propagate automatically to observations, which helps remove expensive joins and keep the product fast at larger scale. Learn more in the [data model docs](/docs/observability/data-model) and [Explore Observations](/faq/all/explore-observations-in-v4).

### What changes

| | Classic model | Observation-centric model |
|---|---|---|
| **Storage** | Separate mutable Traces and Observations tables | Single immutable Observations table |
| **Context attributes** | Stored on the trace, joined at query time | Propagated to every observation on SDK side. |
| **Trace input/output** | Set directly on the trace | Removed, use observation IO instead. (For legacy LLM-as-a-judge evaluators that depend on trace input and output, users can use the deprecated `set_trace_io` methods in the SDKs.) |
| **Mutability** | Traces and observations are mutable | Observations are immutable (written once) |

## OSS and self-hosting

This preview is currently available on Langfuse Cloud. We are working on the migration path for OSS deployments and will share updates here, in the [changelog](/changelog), and in the dedicated [GitHub Discussion](https://github.com/orgs/langfuse/discussions/12518) as they become available.
Expand Down
2 changes: 1 addition & 1 deletion content/faq/all/explore-observations-in-v4.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ As agentic applications grow more complex, a single trace can contain hundreds o

You will notice more rows in the table than before — that's expected. Each row is now one operation, not one trace. The key is to use filters and [saved views](/changelog/2025-05-20-save-table-views) to focus on what matters. Filter by observation name, type, or model to surface the operations you care about, then save that as a view. The filter sidebar shows available values with counts, so you can discover which models, observation names, or error levels are most common before committing to a filter.

For conceptual background, see the [observation-centric data model](/docs/observability/data-model#underlying-data-model). For broader release context, see the [Fast Preview docs](/docs/v4).
For conceptual background, see the [observation-centric data model](/docs/v4#under-the-hood). For broader release context, see the [Fast Preview docs](/docs/v4).

## Common views

Expand Down
Loading