From 0badb5c82b39aa340af89f7e967c158d97f667f1 Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Fri, 26 Jun 2026 13:43:13 +0200 Subject: [PATCH 1/5] docs: add versions & compatibility overview page Add /docs/compatibility as the single reference for how Langfuse server, SDK, and API versions relate: GA versions, SDK<->server minimums, server versions (v1-v4 incl. Fast Preview) with security-patch support, read APIs (current/legacy/deprecated + MCP server), and evaluations & data-export integrations (current vs deprecated). Cross-link from the SDK overview, self-hosting versioning page, and the compatibility FAQ. Co-Authored-By: Claude Opus 4.8 --- content/docs/compatibility.mdx | 103 ++++++++++++++++++ content/docs/meta.json | 1 + content/docs/observability/sdk/overview.mdx | 2 + ...mpatibility-langfuse-ui-and-python-sdk.mdx | 2 + content/self-hosting/upgrade/versioning.mdx | 4 + 5 files changed, 112 insertions(+) create mode 100644 content/docs/compatibility.mdx diff --git a/content/docs/compatibility.mdx b/content/docs/compatibility.mdx new file mode 100644 index 0000000000..6b46899163 --- /dev/null +++ b/content/docs/compatibility.mdx @@ -0,0 +1,103 @@ +--- +title: Versions & compatibility +description: How Langfuse server, SDK, and API versions relate across GA versions, minimum server requirements, and Cloud vs self-hosted availability. +--- + +# Versions & compatibility + +Reference for how Langfuse's server, SDK, and API versions relate across Langfuse Cloud and self-hosted deployments. + + +Langfuse Cloud runs the latest version, including both GA and preview features. New capabilities usually ship to **Langfuse Cloud** first (as preview), then become GA for **OSS / self-hosted** once validated. Availability therefore differs between the two. This page calls out the difference per version, API, and endpoint. + + +## GA versions [#ga] + +Generally available versions. Forward-looking tracks that are not yet GA, such as the server v4 [Fast Preview](/docs/v4), are in **preview**. + +| Component | GA version | Package / repo | Notes | +| --- | --- | --- | --- | +| Server | v3 | [langfuse/langfuse](https://github.com/langfuse/langfuse/releases) Langfuse server release | ClickHouse + Redis + S3/blob storage + worker | +| Python SDK | v4 | [`langfuse`](https://pypi.org/project/langfuse/) PyPI langfuse | OpenTelemetry-based since v3 | +| JS/TS SDK | v5 | [`@langfuse/*`](https://www.npmjs.com/package/@langfuse/tracing) NPM @langfuse/tracing | OpenTelemetry-based since v4 | +| Other languages | n/a | [OpenTelemetry](/integrations/native/opentelemetry) | Any OTel SDK to the Langfuse OTel endpoint | + +## SDK ↔ server compatibility [#sdk-server] + +Recent SDKs require a recent self-hosted server. Cloud always satisfies these minimums. + +| SDK & version | Min. self-hosted server | Status | Upgrade guide | +| --- | --- | --- | --- | +| Python SDK v4 | [≥ 3.125.0](https://github.com/langfuse/langfuse/releases/tag/v3.125.0) | GA | | +| Python SDK v3 | [≥ 3.125.0](https://github.com/langfuse/langfuse/releases/tag/v3.125.0) | Legacy | [Python v3 → v4](/docs/observability/sdk/upgrade-path/python-v3-to-v4) | +| Python SDK v2 | server v2+ | Legacy | [Python v2 → v3](/docs/observability/sdk/upgrade-path/python-v2-to-v3) | +| Python SDK v1 | unsupported on v3 | End of life | [All paths](/docs/observability/sdk/upgrade-path) | +| JS/TS SDK v5 | [≥ 3.95.0](https://github.com/langfuse/langfuse/releases/tag/v3.95.0) | GA | | +| JS/TS SDK v4 | [≥ 3.95.0](https://github.com/langfuse/langfuse/releases/tag/v3.95.0) | Legacy | [JS v4 → v5](/docs/observability/sdk/upgrade-path/js-v4-to-v5) | +| JS/TS SDK v3 / v2 | server v2+ | Legacy | [JS v3 → v4](/docs/observability/sdk/upgrade-path/js-v3-to-v4) | +| JS/TS SDK v1 | unsupported on v3 | End of life | [All paths](/docs/observability/sdk/upgrade-path) | + +The server is backwards compatible with older SDKs. When upgrading an SDK, run a recent server too. See the [versioning policy](/self-hosting/upgrade/versioning). + +## Server versions [#server] + +| Version | Highlights | Status | Security patches | Upgrade guide | +| --- | --- | --- | --- | --- | +| v1 | PostgreSQL, synchronous ingestion. | End of life | No | [v1 → v2](/self-hosting/upgrade/upgrade-guides/upgrade-v1-to-v2) | +| v2 | PostgreSQL, synchronous ingestion. Rebuilt usage & cost tracking. Supports SDK v1+. | End of life | No | [v2 → v3](/self-hosting/upgrade/upgrade-guides/upgrade-v2-to-v3) | +| v3 | ClickHouse + Redis + S3/blob storage + worker; asynchronous, event-driven. Requires SDK v2+. | GA | Yes | | +| v4 ([Fast Preview](/docs/v4)) | Observations-first data model, faster at scale. Cloud-only preview. | Preview | Yes | [Adopt](/docs/v4) | + +v1 and v2 are end of life; upgrade is recommended. v2 → v3 is an infrastructure migration (adds ClickHouse, Redis, blob storage). + +## API versions [#api] + +### Ingestion [#ingestion] + +| Endpoint | Status | Notes | +| --- | --- | --- | +| `POST /api/public/otel/v1/traces` | Recommended | OpenTelemetry (OTLP) endpoint, server v3+ (self-hosted ≥ 3.22.0). The path forward for all ingestion. | +| `POST /api/public/ingestion` | Deprecated | Legacy batch ingestion; async on v3+ (returns `207`). Use the OTel endpoint. | + +### Read APIs [#read-apis] + +Current versions use cursor pagination and selective field groups. **Legacy** endpoints still work but are superseded by a current version. **Deprecated** endpoints will be removed in a future version; migrate to the replacement shown in Notes. + +| Endpoint | Status | Notes | +| --- | --- | --- | +| `GET /api/public/v2/observations` | Current | Cloud (GA); self-hosted via the v4 preview opt-in | +| `GET /api/public/observations` | Legacy | | +| `GET /api/public/observations/{id}` | Deprecated | Use `GET /api/public/v2/observations` | +| `GET /api/public/v2/metrics` | Current | Cloud (GA); self-hosted via the v4 preview opt-in | +| `GET /api/public/metrics` | Legacy | | +| `GET /api/public/v3/scores` | Current | GA (Cloud and self-hosted) | +| `GET /api/public/scores` | Legacy | | +| `GET /api/public/v2/scores` | Deprecated | Use `GET /api/public/v3/scores` | +| `GET /api/public/traces/{id}` | Deprecated | Use `GET /api/public/v2/observations` | +| `GET /api/public/sessions` | Deprecated | Use `GET /api/public/v2/observations` | +| `/api/public/mcp` | Preview | [MCP server](/docs/api-and-data-platform/features/mcp-server); v4 ([Fast Preview](/docs/v4)) only | + +- Self-hosted Observations/Metrics v2 require the v4 preview opt-in (`LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN`). +- SDKs default to the current resources (`api.observations`, `api.scores`, `api.metrics`); legacy versions are under `api.legacy.*` (e.g. `api.legacy.observations_v1` / `observationsV1`). On self-hosted, use the legacy observations and metrics resources until their v2 APIs are GA there. +- Metrics v2 has no `traces` view. + + +Real-time v2 data requires Python SDK ≥ 4.0.0, JS/TS SDK ≥ 5.0.0, or `x-langfuse-ingestion-version: 4` on your OTEL exporter. Otherwise data can lag up to 10 minutes. + + +See the [Observations API](/docs/api-and-data-platform/features/observations-api) and [Metrics API](/docs/metrics/features/metrics-api) pages for details. + +## Evaluations & integrations [#evals-integrations] + +Each has a current version (built on the v4 data model) and a deprecated version that still works but will be removed. Both run on Cloud and self-hosted. Some also require a specific plan or edition; see [pricing](/pricing). + +| Capability | Current | Deprecated | +| --- | --- | --- | +| [Evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Span / observation-level (server ≥ 3.150.0; Python SDK v3+ / JS SDK v4+) | Trace-level (Python SDK v2+ / JS SDK v3+) | +| [PostHog](/integrations/analytics/posthog) | Enriched observations | Traces and observations (legacy) | +| [Blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage) | Enriched observations | Traces and observations (legacy) | +| [Mixpanel](/integrations/analytics/mixpanel) | Enriched observations | Traces and observations (legacy) | + +## How versioning works [#policy] + +Langfuse uses [semantic versioning](/self-hosting/upgrade/versioning): a major bump means a breaking change (infrastructure or public-API removal). Server and SDKs are versioned independently. Release notes: [server](https://github.com/langfuse/langfuse/releases), [Python SDK](https://github.com/langfuse/langfuse-python/releases), [JS/TS SDK](https://github.com/langfuse/langfuse-js/releases). diff --git a/content/docs/meta.json b/content/docs/meta.json index 10935bb449..15f1505af1 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -17,6 +17,7 @@ "api-and-data-platform", "administration", "security-and-guardrails", + "compatibility", "---More---", "glossary", "roadmap", diff --git a/content/docs/observability/sdk/overview.mdx b/content/docs/observability/sdk/overview.mdx index 3d542aa1b4..d013154742 100644 --- a/content/docs/observability/sdk/overview.mdx +++ b/content/docs/observability/sdk/overview.mdx @@ -39,6 +39,8 @@ This section documents tracing related features of the Langfuse SDK. To use the If you are self-hosting Langfuse, the Python SDK v3 requires [**Langfuse platform version ≥ 3.125.0**](https://github.com/langfuse/langfuse/releases/tag/v3.125.0) and the TypeScript SDK v4 requires [**Langfuse platform version ≥ 3.95.0**](https://github.com/langfuse/langfuse/releases/tag/v3.95.0) for all features to work correctly. + +See the full [versions & compatibility overview](/docs/compatibility) for the SDK ↔ server matrix and API version availability. diff --git a/content/faq/all/compatibility-langfuse-ui-and-python-sdk.mdx b/content/faq/all/compatibility-langfuse-ui-and-python-sdk.mdx index 9b7d017545..f87139c313 100644 --- a/content/faq/all/compatibility-langfuse-ui-and-python-sdk.mdx +++ b/content/faq/all/compatibility-langfuse-ui-and-python-sdk.mdx @@ -6,3 +6,5 @@ tags: [self-hosting] # What is the compatibility between Langfuse application / UI and Python SDK? Generally, the UI is backwards compatible with older SDK versions. However, if you update the SDK, you also need to update the Langfuse Application to the latest version. + +For the full SDK ↔ server compatibility matrix, minimum version requirements, and API version availability, see [Versions & compatibility](/docs/compatibility). diff --git a/content/self-hosting/upgrade/versioning.mdx b/content/self-hosting/upgrade/versioning.mdx index dcf925d7ba..e1428c5363 100644 --- a/content/self-hosting/upgrade/versioning.mdx +++ b/content/self-hosting/upgrade/versioning.mdx @@ -8,6 +8,10 @@ sidebarTitle: "Versioning" Versioning is key to ensure compatibility between Langfuse Server, SDKs, and custom integrations via the Public API. Thus, we take [semantic versioning](https://semver.org/) seriously. + +For an overview of current and legacy versions, the SDK ↔ server compatibility matrix, and API version availability, see [Versions & compatibility](/docs/compatibility). + + ## Scope of semantic versioning The following changes **result in a major version bump** as they are considered breaking: From 777d086dac263d80f850a98db69698ab272190f5 Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Wed, 8 Jul 2026 11:15:02 +0200 Subject: [PATCH 2/5] docs(compatibility): apply coverage-audit fixes - Correct observation-level eval server floor to >= 3.153.0 - Add SDK runtime minimums (Python 3.9+, Node.js 20+) - Add self-hosted v3 infra minimums (Postgres >=12, ClickHouse >=24.3, Redis/Valkey >=7) - Reword v4 row: GA on Cloud, self-hosted via env opt-in (not "Cloud-only") - Reclassify read endpoints per spec: traces/{id} Current; observations/{id} & sessions Legacy; add sessions/{sessionId} - MCP server: Current (v3+), not "v4 Preview only"; its observations/metrics tools follow v2 preview availability - Evals & integrations: rename Deprecated column to Legacy (trace-level evals are legacy, per FAQ); add dataset-run -> experiment migration; note enriched exports need v4 opt-in on self-hosted and legacy export blocked on new Cloud projects - Link self-hosting pricing alongside Cloud pricing Co-Authored-By: Claude Opus 4.8 --- content/docs/compatibility.mdx | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/content/docs/compatibility.mdx b/content/docs/compatibility.mdx index 6b46899163..6afbc1460f 100644 --- a/content/docs/compatibility.mdx +++ b/content/docs/compatibility.mdx @@ -18,8 +18,8 @@ Generally available versions. Forward-looking tracks that are not yet GA, such a | Component | GA version | Package / repo | Notes | | --- | --- | --- | --- | | Server | v3 | [langfuse/langfuse](https://github.com/langfuse/langfuse/releases) Langfuse server release | ClickHouse + Redis + S3/blob storage + worker | -| Python SDK | v4 | [`langfuse`](https://pypi.org/project/langfuse/) PyPI langfuse | OpenTelemetry-based since v3 | -| JS/TS SDK | v5 | [`@langfuse/*`](https://www.npmjs.com/package/@langfuse/tracing) NPM @langfuse/tracing | OpenTelemetry-based since v4 | +| Python SDK | v4 | [`langfuse`](https://pypi.org/project/langfuse/) PyPI langfuse | OpenTelemetry-based since v3. Requires Python 3.9+. | +| JS/TS SDK | v5 | [`@langfuse/*`](https://www.npmjs.com/package/@langfuse/tracing) NPM @langfuse/tracing | OpenTelemetry-based since v4. Requires Node.js 20+. | | Other languages | n/a | [OpenTelemetry](/integrations/native/opentelemetry) | Any OTel SDK to the Langfuse OTel endpoint | ## SDK ↔ server compatibility [#sdk-server] @@ -46,9 +46,9 @@ The server is backwards compatible with older SDKs. When upgrading an SDK, run a | v1 | PostgreSQL, synchronous ingestion. | End of life | No | [v1 → v2](/self-hosting/upgrade/upgrade-guides/upgrade-v1-to-v2) | | v2 | PostgreSQL, synchronous ingestion. Rebuilt usage & cost tracking. Supports SDK v1+. | End of life | No | [v2 → v3](/self-hosting/upgrade/upgrade-guides/upgrade-v2-to-v3) | | v3 | ClickHouse + Redis + S3/blob storage + worker; asynchronous, event-driven. Requires SDK v2+. | GA | Yes | | -| v4 ([Fast Preview](/docs/v4)) | Observations-first data model, faster at scale. Cloud-only preview. | Preview | Yes | [Adopt](/docs/v4) | +| v4 ([Fast Preview](/docs/v4)) | Observations-first data model, faster at scale. GA on Cloud; self-hosted via env opt-in (migration in progress). | Preview | Yes | [Adopt](/docs/v4) | -v1 and v2 are end of life; upgrade is recommended. v2 → v3 is an infrastructure migration (adds ClickHouse, Redis, blob storage). +v1 and v2 are end of life; upgrade is recommended. v2 → v3 is an infrastructure migration (adds ClickHouse, Redis, blob storage). Self-hosted v3 requires [PostgreSQL ≥ 12](/self-hosting/deployment/infrastructure/postgres), [ClickHouse ≥ 24.3](/self-hosting/deployment/infrastructure/clickhouse), and [Redis/Valkey ≥ 7](/self-hosting/deployment/infrastructure/cache) (`maxmemory-policy=noeviction`). ## API versions [#api] @@ -67,15 +67,16 @@ Current versions use cursor pagination and selective field groups. **Legacy** en | --- | --- | --- | | `GET /api/public/v2/observations` | Current | Cloud (GA); self-hosted via the v4 preview opt-in | | `GET /api/public/observations` | Legacy | | -| `GET /api/public/observations/{id}` | Deprecated | Use `GET /api/public/v2/observations` | +| `GET /api/public/observations/{id}` | Legacy | Superseded by `GET /api/public/v2/observations` | | `GET /api/public/v2/metrics` | Current | Cloud (GA); self-hosted via the v4 preview opt-in | | `GET /api/public/metrics` | Legacy | | | `GET /api/public/v3/scores` | Current | GA (Cloud and self-hosted) | | `GET /api/public/scores` | Legacy | | | `GET /api/public/v2/scores` | Deprecated | Use `GET /api/public/v3/scores` | -| `GET /api/public/traces/{id}` | Deprecated | Use `GET /api/public/v2/observations` | -| `GET /api/public/sessions` | Deprecated | Use `GET /api/public/v2/observations` | -| `/api/public/mcp` | Preview | [MCP server](/docs/api-and-data-platform/features/mcp-server); v4 ([Fast Preview](/docs/v4)) only | +| `GET /api/public/traces/{id}` | Current | Single trace with nested observations and scores | +| `GET /api/public/sessions` | Legacy | Not recommended for extraction; use `GET /api/public/v2/observations` with a `sessionId` filter | +| `GET /api/public/sessions/{sessionId}` | Legacy | Single session with traces; use `GET /api/public/v2/observations` with a `sessionId` filter | +| `/api/public/mcp` | Current | [MCP server](/docs/api-and-data-platform/features/mcp-server); its observations and metrics tools follow the v2 preview availability above | - Self-hosted Observations/Metrics v2 require the v4 preview opt-in (`LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN`). - SDKs default to the current resources (`api.observations`, `api.scores`, `api.metrics`); legacy versions are under `api.legacy.*` (e.g. `api.legacy.observations_v1` / `observationsV1`). On self-hosted, use the legacy observations and metrics resources until their v2 APIs are GA there. @@ -89,14 +90,18 @@ See the [Observations API](/docs/api-and-data-platform/features/observations-api ## Evaluations & integrations [#evals-integrations] -Each has a current version (built on the v4 data model) and a deprecated version that still works but will be removed. Both run on Cloud and self-hosted. Some also require a specific plan or edition; see [pricing](/pricing). +Each has a current version (built on the v4 data model) and a legacy version that still works and may be deprecated later. Some capabilities also require a specific plan or edition; see [Cloud pricing](/pricing) and [self-hosting pricing](/pricing-self-host). -| Capability | Current | Deprecated | +| Capability | Current | Legacy | | --- | --- | --- | -| [Evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Span / observation-level (server ≥ 3.150.0; Python SDK v3+ / JS SDK v4+) | Trace-level (Python SDK v2+ / JS SDK v3+) | -| [PostHog](/integrations/analytics/posthog) | Enriched observations | Traces and observations (legacy) | -| [Blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage) | Enriched observations | Traces and observations (legacy) | -| [Mixpanel](/integrations/analytics/mixpanel) | Enriched observations | Traces and observations (legacy) | +| [Evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Span / observation-level (server ≥ 3.153.0; Python SDK v3+ / JS SDK v4+) | Trace-level (Python SDK v2+ / JS SDK v3+) | +| [Dataset evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Experiment-level | Dataset-run-level | +| [PostHog](/integrations/analytics/posthog) | Enriched observations | Traces and observations | +| [Blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage) | Enriched observations | Traces and observations | +| [Mixpanel](/integrations/analytics/mixpanel) | Enriched observations | Traces and observations | + +- The enriched (current) analytics exports build on the v4 data model; on self-hosted they require the v4 preview opt-in (Cloud is unaffected). +- On Cloud, projects created on or after 2026-05-20 can no longer select the legacy export source (existing projects and self-hosted are unaffected). ## How versioning works [#policy] From 2a852afd6aec6cd5aadbdc19b9b372b54ee74cb7 Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Wed, 8 Jul 2026 11:19:33 +0200 Subject: [PATCH 3/5] docs(compatibility): readability pass from cold-read testing - Unify status vocabulary to GA / Preview / Legacy / Deprecated / End of life and add a one-line legend near the top (was four competing vocabularies) - Define Fast Preview and the v4 preview opt-in env var once in the intro callout, before first use in tables - Add explicit cue that Cloud readers can skip self-hosted minimums/opt-ins - Gloss "enriched observations" (observations with trace attributes attached) - Fix bullet that softly contradicted the v2 opt-in availability Co-Authored-By: Claude Opus 4.8 --- content/docs/compatibility.mdx | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/content/docs/compatibility.mdx b/content/docs/compatibility.mdx index 6afbc1460f..3868a090fd 100644 --- a/content/docs/compatibility.mdx +++ b/content/docs/compatibility.mdx @@ -8,12 +8,12 @@ description: How Langfuse server, SDK, and API versions relate across GA version Reference for how Langfuse's server, SDK, and API versions relate across Langfuse Cloud and self-hosted deployments. -Langfuse Cloud runs the latest version, including both GA and preview features. New capabilities usually ship to **Langfuse Cloud** first (as preview), then become GA for **OSS / self-hosted** once validated. Availability therefore differs between the two. This page calls out the difference per version, API, and endpoint. +Langfuse Cloud runs the latest version, including both GA and preview features. New capabilities usually ship to **Langfuse Cloud** first (as preview), then become GA for **OSS / self-hosted** once validated. The current preview is the server v4 [Fast Preview](/docs/v4), an observations-first data model; self-hosted instances enable it with the `LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN` environment variable ("v4 preview opt-in" below). **On Langfuse Cloud, you can ignore the self-hosted minimums and opt-in notes on this page.** -## GA versions [#ga] +Status labels used on this page: **GA** (recommended, fully supported), **Preview** (Cloud first; self-hosted via opt-in), **Legacy** (still works, superseded by a newer version), **Deprecated** (will be removed; migrate to the replacement), **End of life** (unsupported, no security patches). -Generally available versions. Forward-looking tracks that are not yet GA, such as the server v4 [Fast Preview](/docs/v4), are in **preview**. +## GA versions [#ga] | Component | GA version | Package / repo | Notes | | --- | --- | --- | --- | @@ -56,30 +56,29 @@ v1 and v2 are end of life; upgrade is recommended. v2 → v3 is an infrastructur | Endpoint | Status | Notes | | --- | --- | --- | -| `POST /api/public/otel/v1/traces` | Recommended | OpenTelemetry (OTLP) endpoint, server v3+ (self-hosted ≥ 3.22.0). The path forward for all ingestion. | +| `POST /api/public/otel/v1/traces` | GA | OpenTelemetry (OTLP) endpoint, server v3+ (self-hosted ≥ 3.22.0). The path forward for all ingestion. | | `POST /api/public/ingestion` | Deprecated | Legacy batch ingestion; async on v3+ (returns `207`). Use the OTel endpoint. | ### Read APIs [#read-apis] -Current versions use cursor pagination and selective field groups. **Legacy** endpoints still work but are superseded by a current version. **Deprecated** endpoints will be removed in a future version; migrate to the replacement shown in Notes. +GA read endpoints use cursor pagination and selective field groups. | Endpoint | Status | Notes | | --- | --- | --- | -| `GET /api/public/v2/observations` | Current | Cloud (GA); self-hosted via the v4 preview opt-in | +| `GET /api/public/v2/observations` | GA | Cloud; self-hosted via the v4 preview opt-in | | `GET /api/public/observations` | Legacy | | | `GET /api/public/observations/{id}` | Legacy | Superseded by `GET /api/public/v2/observations` | -| `GET /api/public/v2/metrics` | Current | Cloud (GA); self-hosted via the v4 preview opt-in | +| `GET /api/public/v2/metrics` | GA | Cloud; self-hosted via the v4 preview opt-in | | `GET /api/public/metrics` | Legacy | | -| `GET /api/public/v3/scores` | Current | GA (Cloud and self-hosted) | +| `GET /api/public/v3/scores` | GA | Cloud and self-hosted | | `GET /api/public/scores` | Legacy | | | `GET /api/public/v2/scores` | Deprecated | Use `GET /api/public/v3/scores` | -| `GET /api/public/traces/{id}` | Current | Single trace with nested observations and scores | +| `GET /api/public/traces/{id}` | GA | Single trace with nested observations and scores | | `GET /api/public/sessions` | Legacy | Not recommended for extraction; use `GET /api/public/v2/observations` with a `sessionId` filter | | `GET /api/public/sessions/{sessionId}` | Legacy | Single session with traces; use `GET /api/public/v2/observations` with a `sessionId` filter | -| `/api/public/mcp` | Current | [MCP server](/docs/api-and-data-platform/features/mcp-server); its observations and metrics tools follow the v2 preview availability above | +| `/api/public/mcp` | GA | [MCP server](/docs/api-and-data-platform/features/mcp-server); its observations and metrics tools follow the v2 preview availability above | -- Self-hosted Observations/Metrics v2 require the v4 preview opt-in (`LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN`). -- SDKs default to the current resources (`api.observations`, `api.scores`, `api.metrics`); legacy versions are under `api.legacy.*` (e.g. `api.legacy.observations_v1` / `observationsV1`). On self-hosted, use the legacy observations and metrics resources until their v2 APIs are GA there. +- SDKs default to the GA resources (`api.observations`, `api.scores`, `api.metrics`); legacy versions are under `api.legacy.*` (e.g. `api.legacy.observations_v1` / `observationsV1`). On self-hosted without the v4 preview opt-in, use the legacy observations and metrics resources. - Metrics v2 has no `traces` view. @@ -90,9 +89,9 @@ See the [Observations API](/docs/api-and-data-platform/features/observations-api ## Evaluations & integrations [#evals-integrations] -Each has a current version (built on the v4 data model) and a legacy version that still works and may be deprecated later. Some capabilities also require a specific plan or edition; see [Cloud pricing](/pricing) and [self-hosting pricing](/pricing-self-host). +Each has a GA version (built on the v4 data model) and a legacy version that still works and may be deprecated later. Some capabilities also require a specific plan or edition; see [Cloud pricing](/pricing) and [self-hosting pricing](/pricing-self-host). -| Capability | Current | Legacy | +| Capability | GA | Legacy | | --- | --- | --- | | [Evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Span / observation-level (server ≥ 3.153.0; Python SDK v3+ / JS SDK v4+) | Trace-level (Python SDK v2+ / JS SDK v3+) | | [Dataset evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Experiment-level | Dataset-run-level | @@ -100,7 +99,7 @@ Each has a current version (built on the v4 data model) and a legacy version tha | [Blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage) | Enriched observations | Traces and observations | | [Mixpanel](/integrations/analytics/mixpanel) | Enriched observations | Traces and observations | -- The enriched (current) analytics exports build on the v4 data model; on self-hosted they require the v4 preview opt-in (Cloud is unaffected). +- Enriched observations are observations with trace attributes attached (v4 data model); on self-hosted these exports require the v4 preview opt-in (Cloud is unaffected). - On Cloud, projects created on or after 2026-05-20 can no longer select the legacy export source (existing projects and self-hosted are unaffected). ## How versioning works [#policy] From ee152b58db0ed001df0e784c2622036af8a29e72 Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Wed, 8 Jul 2026 23:32:53 +0200 Subject: [PATCH 4/5] docs(compatibility): merge Legacy status into Deprecated Co-Authored-By: Claude Fable 5 --- content/docs/compatibility.mdx | 104 ++++++++++++++++----------------- 1 file changed, 52 insertions(+), 52 deletions(-) diff --git a/content/docs/compatibility.mdx b/content/docs/compatibility.mdx index 3868a090fd..8c438d5adb 100644 --- a/content/docs/compatibility.mdx +++ b/content/docs/compatibility.mdx @@ -11,42 +11,42 @@ Reference for how Langfuse's server, SDK, and API versions relate across Langfus Langfuse Cloud runs the latest version, including both GA and preview features. New capabilities usually ship to **Langfuse Cloud** first (as preview), then become GA for **OSS / self-hosted** once validated. The current preview is the server v4 [Fast Preview](/docs/v4), an observations-first data model; self-hosted instances enable it with the `LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN` environment variable ("v4 preview opt-in" below). **On Langfuse Cloud, you can ignore the self-hosted minimums and opt-in notes on this page.** -Status labels used on this page: **GA** (recommended, fully supported), **Preview** (Cloud first; self-hosted via opt-in), **Legacy** (still works, superseded by a newer version), **Deprecated** (will be removed; migrate to the replacement), **End of life** (unsupported, no security patches). +Status labels used on this page: **GA** (recommended, fully supported), **Preview** (Cloud first; self-hosted via opt-in), **Deprecated** (still works but superseded; will be removed, migrate to the replacement), **End of life** (unsupported, no security patches). ## GA versions [#ga] -| Component | GA version | Package / repo | Notes | -| --- | --- | --- | --- | -| Server | v3 | [langfuse/langfuse](https://github.com/langfuse/langfuse/releases) Langfuse server release | ClickHouse + Redis + S3/blob storage + worker | -| Python SDK | v4 | [`langfuse`](https://pypi.org/project/langfuse/) PyPI langfuse | OpenTelemetry-based since v3. Requires Python 3.9+. | -| JS/TS SDK | v5 | [`@langfuse/*`](https://www.npmjs.com/package/@langfuse/tracing) NPM @langfuse/tracing | OpenTelemetry-based since v4. Requires Node.js 20+. | -| Other languages | n/a | [OpenTelemetry](/integrations/native/opentelemetry) | Any OTel SDK to the Langfuse OTel endpoint | +| Component | GA version | Package / repo | Notes | +| --------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | +| Server | v3 | [langfuse/langfuse](https://github.com/langfuse/langfuse/releases) Langfuse server release | ClickHouse + Redis + S3/blob storage + worker | +| Python SDK | v4 | [`langfuse`](https://pypi.org/project/langfuse/) PyPI langfuse | OpenTelemetry-based since v3. Requires Python 3.9+. | +| JS/TS SDK | v5 | [`@langfuse/*`](https://www.npmjs.com/package/@langfuse/tracing) NPM @langfuse/tracing | OpenTelemetry-based since v4. Requires Node.js 20+. | +| Other languages | n/a | [OpenTelemetry](/integrations/native/opentelemetry) | Any OTel SDK to the Langfuse OTel endpoint | ## SDK ↔ server compatibility [#sdk-server] Recent SDKs require a recent self-hosted server. Cloud always satisfies these minimums. -| SDK & version | Min. self-hosted server | Status | Upgrade guide | -| --- | --- | --- | --- | -| Python SDK v4 | [≥ 3.125.0](https://github.com/langfuse/langfuse/releases/tag/v3.125.0) | GA | | -| Python SDK v3 | [≥ 3.125.0](https://github.com/langfuse/langfuse/releases/tag/v3.125.0) | Legacy | [Python v3 → v4](/docs/observability/sdk/upgrade-path/python-v3-to-v4) | -| Python SDK v2 | server v2+ | Legacy | [Python v2 → v3](/docs/observability/sdk/upgrade-path/python-v2-to-v3) | -| Python SDK v1 | unsupported on v3 | End of life | [All paths](/docs/observability/sdk/upgrade-path) | -| JS/TS SDK v5 | [≥ 3.95.0](https://github.com/langfuse/langfuse/releases/tag/v3.95.0) | GA | | -| JS/TS SDK v4 | [≥ 3.95.0](https://github.com/langfuse/langfuse/releases/tag/v3.95.0) | Legacy | [JS v4 → v5](/docs/observability/sdk/upgrade-path/js-v4-to-v5) | -| JS/TS SDK v3 / v2 | server v2+ | Legacy | [JS v3 → v4](/docs/observability/sdk/upgrade-path/js-v3-to-v4) | -| JS/TS SDK v1 | unsupported on v3 | End of life | [All paths](/docs/observability/sdk/upgrade-path) | +| SDK & version | Min. self-hosted server | Status | Upgrade guide | +| ----------------- | ----------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------- | +| Python SDK v4 | [≥ 3.125.0](https://github.com/langfuse/langfuse/releases/tag/v3.125.0) | GA | | +| Python SDK v3 | [≥ 3.125.0](https://github.com/langfuse/langfuse/releases/tag/v3.125.0) | Deprecated | [Python v3 → v4](/docs/observability/sdk/upgrade-path/python-v3-to-v4) | +| Python SDK v2 | server v2+ | Deprecated | [Python v2 → v3](/docs/observability/sdk/upgrade-path/python-v2-to-v3) | +| Python SDK v1 | unsupported on v3 | End of life | [All paths](/docs/observability/sdk/upgrade-path) | +| JS/TS SDK v5 | [≥ 3.95.0](https://github.com/langfuse/langfuse/releases/tag/v3.95.0) | GA | | +| JS/TS SDK v4 | [≥ 3.95.0](https://github.com/langfuse/langfuse/releases/tag/v3.95.0) | Deprecated | [JS v4 → v5](/docs/observability/sdk/upgrade-path/js-v4-to-v5) | +| JS/TS SDK v3 / v2 | server v2+ | Deprecated | [JS v3 → v4](/docs/observability/sdk/upgrade-path/js-v3-to-v4) | +| JS/TS SDK v1 | unsupported on v3 | End of life | [All paths](/docs/observability/sdk/upgrade-path) | The server is backwards compatible with older SDKs. When upgrading an SDK, run a recent server too. See the [versioning policy](/self-hosting/upgrade/versioning). ## Server versions [#server] -| Version | Highlights | Status | Security patches | Upgrade guide | -| --- | --- | --- | --- | --- | -| v1 | PostgreSQL, synchronous ingestion. | End of life | No | [v1 → v2](/self-hosting/upgrade/upgrade-guides/upgrade-v1-to-v2) | -| v2 | PostgreSQL, synchronous ingestion. Rebuilt usage & cost tracking. Supports SDK v1+. | End of life | No | [v2 → v3](/self-hosting/upgrade/upgrade-guides/upgrade-v2-to-v3) | -| v3 | ClickHouse + Redis + S3/blob storage + worker; asynchronous, event-driven. Requires SDK v2+. | GA | Yes | | -| v4 ([Fast Preview](/docs/v4)) | Observations-first data model, faster at scale. GA on Cloud; self-hosted via env opt-in (migration in progress). | Preview | Yes | [Adopt](/docs/v4) | +| Version | Highlights | Status | Security patches | Upgrade guide | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | ---------------- | ---------------------------------------------------------------- | +| v1 | PostgreSQL, synchronous ingestion. | End of life | No | [v1 → v2](/self-hosting/upgrade/upgrade-guides/upgrade-v1-to-v2) | +| v2 | PostgreSQL, synchronous ingestion. Rebuilt usage & cost tracking. Supports SDK v1+. | End of life | No | [v2 → v3](/self-hosting/upgrade/upgrade-guides/upgrade-v2-to-v3) | +| v3 | ClickHouse + Redis + S3/blob storage + worker; asynchronous, event-driven. Requires SDK v2+. | GA | Yes | | +| v4 ([Fast Preview](/docs/v4)) | Observations-first data model, faster at scale. GA on Cloud; self-hosted via env opt-in (migration in progress). | Preview | Yes | [Adopt](/docs/v4) | v1 and v2 are end of life; upgrade is recommended. v2 → v3 is an infrastructure migration (adds ClickHouse, Redis, blob storage). Self-hosted v3 requires [PostgreSQL ≥ 12](/self-hosting/deployment/infrastructure/postgres), [ClickHouse ≥ 24.3](/self-hosting/deployment/infrastructure/clickhouse), and [Redis/Valkey ≥ 7](/self-hosting/deployment/infrastructure/cache) (`maxmemory-policy=noeviction`). @@ -54,31 +54,31 @@ v1 and v2 are end of life; upgrade is recommended. v2 → v3 is an infrastructur ### Ingestion [#ingestion] -| Endpoint | Status | Notes | -| --- | --- | --- | -| `POST /api/public/otel/v1/traces` | GA | OpenTelemetry (OTLP) endpoint, server v3+ (self-hosted ≥ 3.22.0). The path forward for all ingestion. | -| `POST /api/public/ingestion` | Deprecated | Legacy batch ingestion; async on v3+ (returns `207`). Use the OTel endpoint. | +| Endpoint | Status | Notes | +| --------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- | +| `POST /api/public/otel/v1/traces` | GA | OpenTelemetry (OTLP) endpoint, server v3+ (self-hosted ≥ 3.22.0). The path forward for all ingestion. | +| `POST /api/public/ingestion` | Deprecated | Batch ingestion; async on v3+ (returns `207`). Use the OTel endpoint. | ### Read APIs [#read-apis] GA read endpoints use cursor pagination and selective field groups. -| Endpoint | Status | Notes | -| --- | --- | --- | -| `GET /api/public/v2/observations` | GA | Cloud; self-hosted via the v4 preview opt-in | -| `GET /api/public/observations` | Legacy | | -| `GET /api/public/observations/{id}` | Legacy | Superseded by `GET /api/public/v2/observations` | -| `GET /api/public/v2/metrics` | GA | Cloud; self-hosted via the v4 preview opt-in | -| `GET /api/public/metrics` | Legacy | | -| `GET /api/public/v3/scores` | GA | Cloud and self-hosted | -| `GET /api/public/scores` | Legacy | | -| `GET /api/public/v2/scores` | Deprecated | Use `GET /api/public/v3/scores` | -| `GET /api/public/traces/{id}` | GA | Single trace with nested observations and scores | -| `GET /api/public/sessions` | Legacy | Not recommended for extraction; use `GET /api/public/v2/observations` with a `sessionId` filter | -| `GET /api/public/sessions/{sessionId}` | Legacy | Single session with traces; use `GET /api/public/v2/observations` with a `sessionId` filter | -| `/api/public/mcp` | GA | [MCP server](/docs/api-and-data-platform/features/mcp-server); its observations and metrics tools follow the v2 preview availability above | - -- SDKs default to the GA resources (`api.observations`, `api.scores`, `api.metrics`); legacy versions are under `api.legacy.*` (e.g. `api.legacy.observations_v1` / `observationsV1`). On self-hosted without the v4 preview opt-in, use the legacy observations and metrics resources. +| Endpoint | Status | Notes | +| -------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `GET /api/public/v2/observations` | GA | Cloud; self-hosted via the v4 preview opt-in | +| `GET /api/public/observations` | Deprecated | | +| `GET /api/public/observations/{id}` | Deprecated | Superseded by `GET /api/public/v2/observations` | +| `GET /api/public/v2/metrics` | GA | Cloud; self-hosted via the v4 preview opt-in | +| `GET /api/public/metrics` | Deprecated | | +| `GET /api/public/v3/scores` | GA | Cloud and self-hosted | +| `GET /api/public/scores` | Deprecated | | +| `GET /api/public/v2/scores` | Deprecated | Use `GET /api/public/v3/scores` | +| `GET /api/public/traces/{id}` | GA | Single trace with nested observations and scores | +| `GET /api/public/sessions` | Deprecated | Not recommended for extraction; use `GET /api/public/v2/observations` with a `sessionId` filter | +| `GET /api/public/sessions/{sessionId}` | Deprecated | Single session with traces; use `GET /api/public/v2/observations` with a `sessionId` filter | +| `/api/public/mcp` | GA | [MCP server](/docs/api-and-data-platform/features/mcp-server); its observations and metrics tools follow the v2 preview availability above | + +- SDKs default to the GA resources (`api.observations`, `api.scores`, `api.metrics`); older versions are under `api.legacy.*` (e.g. `api.legacy.observations_v1` / `observationsV1`). On self-hosted without the v4 preview opt-in, use the `api.legacy.*` observations and metrics resources. - Metrics v2 has no `traces` view. @@ -89,18 +89,18 @@ See the [Observations API](/docs/api-and-data-platform/features/observations-api ## Evaluations & integrations [#evals-integrations] -Each has a GA version (built on the v4 data model) and a legacy version that still works and may be deprecated later. Some capabilities also require a specific plan or edition; see [Cloud pricing](/pricing) and [self-hosting pricing](/pricing-self-host). +Each has a GA version (built on the v4 data model) and a deprecated version that still works but will be removed. Some capabilities also require a specific plan or edition; see [Cloud pricing](/pricing) and [self-hosting pricing](/pricing-self-host). -| Capability | GA | Legacy | -| --- | --- | --- | -| [Evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Span / observation-level (server ≥ 3.153.0; Python SDK v3+ / JS SDK v4+) | Trace-level (Python SDK v2+ / JS SDK v3+) | -| [Dataset evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Experiment-level | Dataset-run-level | -| [PostHog](/integrations/analytics/posthog) | Enriched observations | Traces and observations | -| [Blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage) | Enriched observations | Traces and observations | -| [Mixpanel](/integrations/analytics/mixpanel) | Enriched observations | Traces and observations | +| Capability | GA | Deprecated | +| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------- | +| [Evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Span / observation-level (server ≥ 3.153.0; Python SDK v3+ / JS SDK v4+) | Trace-level (Python SDK v2+ / JS SDK v3+) | +| [Dataset evaluation](/docs/evaluation/evaluation-methods/llm-as-a-judge) | Experiment-level | Dataset-run-level | +| [PostHog](/integrations/analytics/posthog) | Enriched observations | Traces and observations | +| [Blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage) | Enriched observations | Traces and observations | +| [Mixpanel](/integrations/analytics/mixpanel) | Enriched observations | Traces and observations | - Enriched observations are observations with trace attributes attached (v4 data model); on self-hosted these exports require the v4 preview opt-in (Cloud is unaffected). -- On Cloud, projects created on or after 2026-05-20 can no longer select the legacy export source (existing projects and self-hosted are unaffected). +- On Cloud, projects created on or after 2026-05-20 can no longer select the deprecated export source (existing projects and self-hosted are unaffected). ## How versioning works [#policy] From 862b1cda9196d4ec0cdaa3246f94513ae1ebeba0 Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Wed, 8 Jul 2026 23:33:19 +0200 Subject: [PATCH 5/5] chore: prettier formatting Co-Authored-By: Claude Fable 5 --- content/docs/observability/sdk/overview.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/observability/sdk/overview.mdx b/content/docs/observability/sdk/overview.mdx index d013154742..c8c7f19ea4 100644 --- a/content/docs/observability/sdk/overview.mdx +++ b/content/docs/observability/sdk/overview.mdx @@ -41,6 +41,7 @@ This section documents tracing related features of the Langfuse SDK. To use the If you are self-hosting Langfuse, the Python SDK v3 requires [**Langfuse platform version ≥ 3.125.0**](https://github.com/langfuse/langfuse/releases/tag/v3.125.0) and the TypeScript SDK v4 requires [**Langfuse platform version ≥ 3.95.0**](https://github.com/langfuse/langfuse/releases/tag/v3.95.0) for all features to work correctly. See the full [versions & compatibility overview](/docs/compatibility) for the SDK ↔ server matrix and API version availability. +