diff --git a/content/docs/observability/data-model.mdx b/content/docs/observability/data-model.mdx index edf68419e..18ceeec37 100644 --- a/content/docs/observability/data-model.mdx +++ b/content/docs/observability/data-model.mdx @@ -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 - - -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. - - -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. - - - ![Observation-centric data model](/images/changelog/2026-03-10-v4-preview/data-model.png) - - -### 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 Now that you understand the data model, let's explore how Langfuse actually captures and processes your traces. diff --git a/content/docs/v4.mdx b/content/docs/v4.mdx index 75cc66748..d0175c446 100644 --- a/content/docs/v4.mdx +++ b/content/docs/v4.mdx @@ -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] ![Langfuse data model @@ -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. diff --git a/content/faq/all/explore-observations-in-v4.mdx b/content/faq/all/explore-observations-in-v4.mdx index 875a6ca75..e5954337e 100644 --- a/content/faq/all/explore-observations-in-v4.mdx +++ b/content/faq/all/explore-observations-in-v4.mdx @@ -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