Skip to content

docs: add versions & compatibility overview page #3258

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

Open
maxdeichmann wants to merge 5 commits into
base: main
Choose a base branch
from
Open

docs: add versions & compatibility overview page #3258

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0badb5c
docs: add versions & compatibility overview page
maxdeichmann Jun 26, 2026
777d086
docs(compatibility): apply coverage-audit fixes
maxdeichmann Jul 8, 2026
2a852af
docs(compatibility): readability pass from cold-read testing
maxdeichmann Jul 8, 2026
ee152b5
docs(compatibility): merge Legacy status into Deprecated
maxdeichmann Jul 8, 2026
862b1cd
chore: prettier formatting
maxdeichmann Jul 8, 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
103 changes: 103 additions & 0 deletions content/docs/compatibility.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<Callout type="info">
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.
</Callout>

## 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) <a href="https://github.com/langfuse/langfuse/releases"><img className="inline" src="https://img.shields.io/github/v/release/langfuse/langfuse?style=flat-square&label=release" alt="Langfuse server release" /></a> | ClickHouse + Redis + S3/blob storage + worker |
| Python SDK | v4 | [`langfuse`](https://pypi.org/project/langfuse/) <a href="https://pypi.org/project/langfuse/"><img className="inline" src="https://img.shields.io/pypi/v/langfuse?style=flat-square&label=pypi" alt="PyPI langfuse" /></a> | OpenTelemetry-based since v3 |
| JS/TS SDK | v5 | [`@langfuse/*`](https://www.npmjs.com/package/@langfuse/tracing) <a href="https://www.npmjs.com/package/@langfuse/tracing"><img className="inline" src="https://img.shields.io/npm/v/@langfuse/tracing?style=flat-square&label=npm" alt="NPM @langfuse/tracing" /></a> | 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` |

@greptile-apps greptile-apps Bot Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Misleading replacement endpoint for traces/{id} and sessions

Both GET /api/public/traces/{id} and GET /api/public/sessions point users to GET /api/public/v2/observations as their replacement. Observations, traces, and sessions are conceptually distinct resources; a user migrating from the sessions list endpoint to an observations list endpoint would get fundamentally different data. If the v4 data model intentionally collapses these, a brief note explaining the conceptual change would reduce confusion — otherwise readers may assume the replacement is a straightforward semantic equivalent. Is there a v2 sessions or traces endpoint planned, or is the intent that users query the observations endpoint and filter by type? A one-line note clarifying the data-model reason for this would help readers understand the migration.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: content/docs/compatibility.mdx
Line: 76-77

Comment:
**Misleading replacement endpoint for `traces/{id}` and `sessions`**

Both `GET /api/public/traces/{id}` and `GET /api/public/sessions` point users to `GET /api/public/v2/observations` as their replacement. Observations, traces, and sessions are conceptually distinct resources; a user migrating from the sessions list endpoint to an observations list endpoint would get fundamentally different data. If the v4 data model intentionally collapses these, a brief note explaining the conceptual change would reduce confusion — otherwise readers may assume the replacement is a straightforward semantic equivalent. Is there a v2 sessions or traces endpoint planned, or is the intent that users query the observations endpoint and filter by type? A one-line note clarifying the data-model reason for this would help readers understand the migration.

How can I resolve this? If you propose a fix, please make it concise.

| `/api/public/mcp` | Preview | [MCP server](/docs/api-and-data-platform/features/mcp-server); v4 ([Fast Preview](/docs/v4)) only |

Check failure on line 78 in content/docs/compatibility.mdx

View check run for this annotation

Claude / Claude Code Review

MCP endpoint marked 'v4 only' contradicts existing mcp-server docs 

The compatibility table marks `/api/public/mcp` as "v4 (Fast Preview) only" (line 78), but [`mcp-server.mdx`](content/docs/api-and-data-platform/features/mcp-server.mdx) already documents this endpoint as generally available today on Cloud EU/US/Japan/HIPAA and Self-Hosted — no v4 or preview qualifier. Readers of this new canonical reference page will be misled into thinking MCP is unavailable outside the v4 preview. Please reconcile the two pages (e.g. mark MCP as GA for prompt management/exist

@greptile-apps greptile-apps Bot Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 MCP server availability contradicts existing docs

The table marks /api/public/mcp as "v4 (Fast Preview) only", but content/docs/api-and-data-platform/features/mcp-server.mdx lists active endpoints for Cloud EU, Cloud US, Cloud Japan, and HIPAA today with no v4 prerequisite. Users reading this page will incorrectly conclude the MCP server is unavailable to them, while the dedicated MCP page will tell them it is. The PR description flags this as needing reconciliation — one of the two pages needs to be authoritative before this goes live.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: content/docs/compatibility.mdx
Line: 78

Comment:
**MCP server availability contradicts existing docs**

The table marks `/api/public/mcp` as "v4 ([Fast Preview](/docs/v4)) only", but `content/docs/api-and-data-platform/features/mcp-server.mdx` lists active endpoints for Cloud EU, Cloud US, Cloud Japan, and HIPAA today with no v4 prerequisite. Users reading this page will incorrectly conclude the MCP server is unavailable to them, while the dedicated MCP page will tell them it is. The PR description flags this as needing reconciliation — one of the two pages needs to be authoritative before this goes live.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@claude claude Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 The compatibility table marks /api/public/mcp as "v4 (Fast Preview) only" (line 78), but mcp-server.mdx already documents this endpoint as generally available today on Cloud EU/US/Japan/HIPAA and Self-Hosted — no v4 or preview qualifier. Readers of this new canonical reference page will be misled into thinking MCP is unavailable outside the v4 preview. Please reconcile the two pages (e.g. mark MCP as GA for prompt management/existing tools, and call out any specific v4-only tools separately).

Extended reasoning...

The contradiction

content/docs/compatibility.mdx line 78 renders this row in the Read APIs table:

| `/api/public/mcp` | Preview | [MCP server](/docs/api-and-data-platform/features/mcp-server); v4 ([Fast Preview](/docs/v4)) only |

But the linked page — content/docs/api-and-data-platform/features/mcp-server.mdx — documents /api/public/mcp as available today across five environments (lines 29–75):

  • Cloud EU: https://cloud.langfuse.com/api/public/mcp
  • Cloud US: https://us.cloud.langfuse.com/api/public/mcp
  • Cloud Japan: https://jp.cloud.langfuse.com/api/public/mcp
  • HIPAA US: https://hipaa.cloud.langfuse.com/api/public/mcp
  • Self-Hosted: https://your-domain.com/api/public/mcp (with reverse-proxy guidance and LANGFUSE_MCP_ALLOWED_HOSTS env var)

Nowhere on that page is v4, Fast Preview, or a preview opt-in mentioned as a prerequisite. It is presented as a generally-available capability, and is already the recommended way to do prompt management via MCP on v3 self-hosted deployments today.

Why this misleads readers

The compatibility page is a new canonical reference that this same PR cross-links from three other places (SDK overview, self-hosting versioning, and the compatibility FAQ). A reader on v3 self-hosted who is already using /api/public/mcp for prompt management, or evaluating adopting it, will land on this table and reasonably conclude they need to opt into v4 Fast Preview first. That is not true for the currently-documented MCP surface.

Step-by-step proof

  1. A v3 self-hosted user reads the new compatibility FAQ addition and clicks through to /docs/compatibility.
  2. They scan the Read APIs table and see /api/public/mcp marked "Preview" with the qualifier "v4 (Fast Preview) only."
  3. They click the inline link to /docs/api-and-data-platform/features/mcp-server.
  4. That page shows a Self-Hosted tab with a working configuration, no mention of v4 or preview flags, and links to Prompt Management with MCP as an existing use case.
  5. The two pages contradict each other; the reader either (a) doesn't try MCP because they trust the compatibility table, or (b) tries it, it works, and is confused about which page is correct.

The author flagged this

The PR description explicitly calls this out under "Notes for reviewers": "The /docs/v4 MCP note says 'v4 only'; the existing mcp-server.mdx says the MCP server is available today for prompt management — may need reconciling." So this is a known unresolved gap in the PR as submitted.

Suggested fix

Update the compatibility row to reflect actual availability. Two reasonable options:

  • Drop the "v4 only" qualifier: /api/public/mcp | GA | MCP server (simplest, matches mcp-server.mdx today).
  • Or split the story if some tools really are v4-gated: mark the endpoint GA, and add a note that certain newer tools (name them) require v4 Fast Preview.


- 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.

Check failure on line 81 in content/docs/compatibility.mdx

View check run for this annotation

Claude / Claude Code Review

v4 self-hosted opt-in contradictions and undocumented env var 

The new compatibility page contradicts itself and other docs about v4 self-hosted availability. The Read APIs table (lines 68, 71) and bullet at line 80 tell self-hosted operators they can enable v2 Observations/Metrics via a preview opt-in and env var `LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN`, but the Server versions row (line 49) marks v4 as "Cloud-only preview" and the bullet at line 81 tells them to "use the legacy observations and metrics resources until their v2 APIs are GA there". The

@claude claude Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 The new compatibility page contradicts itself and other docs about v4 self-hosted availability. The Read APIs table (lines 68, 71) and bullet at line 80 tell self-hosted operators they can enable v2 Observations/Metrics via a preview opt-in and env var LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN, but the Server versions row (line 49) marks v4 as "Cloud-only preview" and the bullet at line 81 tells them to "use the legacy observations and metrics resources until their v2 APIs are GA there". The env var also appears nowhere else in the repo (not in the self-hosting configuration reference, not in /docs/v4, not in any changelog), and /docs/v4 line 146 explicitly states the OSS migration path is still being worked on. Please either drop the "self-hosted via the v4 preview opt-in" notes and the env var reference (aligning with the /docs/v4 stance), or document the opt-in path in /docs/v4 and the self-hosting config surface.

Extended reasoning...

What the bug is

The new content/docs/compatibility.mdx page contains internally contradictory guidance about whether the v4 Observations/Metrics v2 APIs are available on self-hosted deployments today, and it references an env variable (LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN) that is not documented anywhere else in the repository.

Where the contradictions live

On the same page:

  • Line 49 (Server versions table): v4 (Fast Preview) | ... Cloud-only preview.
  • Line 68 (Read APIs table): GET /api/public/v2/observations | Current | Cloud (GA); self-hosted via the v4 preview opt-in
  • Line 71 (Read APIs table): same phrasing for GET /api/public/v2/metrics.
  • Line 80 (bullet): Self-hosted Observations/Metrics v2 require the v4 preview opt-in (\LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN`).`
  • Line 81 (bullet): On self-hosted, use the legacy observations and metrics resources until their v2 APIs are GA there.

Lines 49 and 81 say self-hosted has no v2 API access today; lines 68, 71, and 80 say it does via an opt-in env var. Both cannot be right.

Cross-referencing other docs

content/docs/v4.mdx lines 144–146 ("OSS and self-hosting") explicitly says: "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, and in the dedicated GitHub Discussion as they become available." This confirms there is no self-hosted opt-in path today.

content/docs/api-and-data-platform/features/observations-api.mdx line 25 similarly states: "Cloud-only: The v2 Observations API is only available on Langfuse Cloud."

The phantom env variable

A repo-wide grep for LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN (and MIGRATION_V4 / PREVIEW_OPT_IN variants) returns exactly one file: the new compatibility.mdx. It is not in the self-hosting configuration reference (content/self-hosting/configuration/index.mdx), not in /docs/v4, and not in any changelog.

Step-by-step proof of impact

  1. A self-hosted operator lands on /docs/compatibility (linked from the SDK overview, self-hosting versioning page, and the compatibility FAQ).
  2. They read the Read APIs table and see v2/observations is "Cloud (GA); self-hosted via the v4 preview opt-in".
  3. They read the bullet on line 80 and try to set LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN on their deployment.
  4. They search the self-hosting configuration reference and /docs/v4 for how to configure this variable, find nothing, and get blocked.
  5. Alternatively they read line 81 or the "Cloud-only preview" row on line 49 and are left uncertain which statement is correct.

How to fix

Either:

  • Drop the two "self-hosted via the v4 preview opt-in" notes from the Read APIs table rows and remove the bullet on line 80 (aligning with the "Cloud-only preview" row and /docs/v4); or
  • If the opt-in path is real and about to ship, document LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN alongside /docs/v4 and in the self-hosting configuration reference before merging this page.

- Metrics v2 has no `traces` view.

<Callout type="warning">
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.
</Callout>

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+) |

Check failure on line 96 in content/docs/compatibility.mdx

View check run for this annotation

Claude / Claude Code Review

Trace-level evals labeled 'Deprecated' contradicts FAQ commitment 

The 'Deprecated' column on line 96 lists trace-level evaluations, but content/faq/all/llm-as-a-judge-migration.mdx line 24 explicitly promises 'Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation.' The compatibility page's own definition on line 92 says deprecated versions 'will be removed' — directly contradicting that promise. Fix by relabeling the column to 'Legacy' / 'Superseded' (matching the FAQ language), or update the FAQ with product sign-off if this

@greptile-apps greptile-apps Bot Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 "Deprecated" label for trace-level evals directly contradicts existing FAQ

content/faq/all/llm-as-a-judge-migration.mdx explicitly states: "Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation." Labeling trace-level evaluation as Deprecated here contradicts that page and will confuse users who read both. The PR description acknowledges this conflict. Both pages will be live simultaneously, so one of them needs to be corrected before this merges — either the FAQ line should be updated or the deprecation label here should be softened to "Legacy".

Prompt To Fix With AI 
This is a comment left during a code review.
Path: content/docs/compatibility.mdx
Line: 96

Comment:
**"Deprecated" label for trace-level evals directly contradicts existing FAQ**

`content/faq/all/llm-as-a-judge-migration.mdx` explicitly states: *"Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation."* Labeling trace-level evaluation as **Deprecated** here contradicts that page and will confuse users who read both. The PR description acknowledges this conflict. Both pages will be live simultaneously, so one of them needs to be corrected before this merges — either the FAQ line should be updated or the deprecation label here should be softened to "Legacy".

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@claude claude Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 The 'Deprecated' column on line 96 lists trace-level evaluations, but content/faq/all/llm-as-a-judge-migration.mdx line 24 explicitly promises 'Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation.' The compatibility page's own definition on line 92 says deprecated versions 'will be removed' — directly contradicting that promise. Fix by relabeling the column to 'Legacy' / 'Superseded' (matching the FAQ language), or update the FAQ with product sign-off if this really is a deprecation. The PR description already flags this as an unresolved reconciliation.

Extended reasoning...

The contradiction\n\nTwo docs pages shipping together on this repo now make mutually incompatible claims about the lifecycle of trace-level evaluators:\n\n- content/docs/compatibility.mdx:96 places "Trace-level (Python SDK v2+ / JS SDK v3+)" under the Deprecated column of the Evaluations & integrations table.\n- The same file, line 92, defines the Deprecated column's semantics for that section: "Each has a current version (built on the v4 data model) and a deprecated version that still works but will be removed."\n- content/faq/all/llm-as-a-judge-migration.mdx:24 states verbatim: "Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation." The same FAQ reiterates on line 176: "No changes needed—trace-level evaluators will continue to work."\n\nSo the compatibility page tells the reader trace-level evals will be removed; the FAQ tells the reader they will continue to work and are explicitly not a deprecation.\n\nStep-by-step proof of the contradiction\n\n1. A user planning around trace-level evals opens /docs/compatibility (the new page this PR introduces).\n2. They read the Evaluations & integrations intro: "deprecated version … will be removed."\n3. They see "Trace-level (Python SDK v2+ / JS SDK v3+)" in the Deprecated column → they conclude their setup is scheduled for removal.\n4. They open the FAQ linked from the LLM-as-a-Judge docs (/faq/all/llm-as-a-judge-migration) to plan the migration.\n5. Line 24 tells them: "This is an upgrade path, not a deprecation." Line 176 says: "No changes needed—trace-level evaluators will continue to work."\n6. The two statements cannot both be true under the compatibility page's own definitions.\n\nWhy the existing wording doesn't prevent it\n\nThe compatibility page uses "Deprecated" for API endpoints (line 64: "Deprecated endpoints will be removed in a future version") and reuses the same label — with the same removal semantics — for evals in the section intro on line 92. There is no local softening of the label for this specific row. Meanwhile the FAQ deliberately picked the word "Legacy" (see FAQ line 65, "Find evaluators marked 'Legacy'") precisely to avoid the removal connotation. Mixing the two labels across two shipping docs pages is what creates the contradiction.\n\nImpact\n\nThis is externally visible lifecycle guidance on a new reference page. A user relying on trace-level evaluators is left with two incompatible answers to "will my setup keep working?" and could either (a) prematurely rework working evaluators believing removal is imminent, or (b) delay migration because the FAQ reassured them nothing is changing. Either outcome is a real product cost driven by the docs themselves. The PR author acknowledged this in the PR description ("Trace-level evals are shown deprecated, which conflicts with a line in llm-as-a-judge-migration.mdx … that FAQ line likely needs updating for consistency") but left both files in a contradictory state.\n\nHow to fix\n\nDecision needed from the product owner — pick one and apply consistently:\n\n1. Relabel on the compatibility page (recommended, lower risk): change the column header or the trace-level row to use "Legacy" / "Superseded" instead of "Deprecated", matching the FAQ's existing wording, and add a note that trace-level evals continue to work. This preserves the public commitment.\n2. Update the FAQ (only if product genuinely intends removal): revise llm-as-a-judge-migration.mdx lines 24 and 174–177 to acknowledge a real deprecation and, ideally, name a removal window. This is a public-commitment change and should not be made without explicit product sign-off.

| [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).
1 change: 1 addition & 0 deletions content/docs/meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
"api-and-data-platform",
"administration",
"security-and-guardrails",
"compatibility",
"---More---",
"glossary",
"roadmap",
Expand Down
2 changes: 2 additions & 0 deletions content/docs/observability/sdk/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,11 @@
<Details>
<Summary>Requirements for self-hosted Langfuse</Summary>

<Callout type="info">
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.
</Callout>

Check warning on line 44 in content/docs/observability/sdk/overview.mdx

View check run for this annotation

Claude / Claude Code Review

Self-hosted requirements callout still names Python v3 / JS v4 as current 

The self-hosting requirements callout still names Python SDK v3 and TypeScript SDK v4 as if current, but the top of this same file (lines 17–18) and the new /docs/compatibility page identify Python v4 / JS-TS v5 as current. The numeric minimums (≥ 3.125.0 and ≥ 3.95.0) happen to match v4/v5 too, so the copy is out of date rather than wrong — but since this PR now cross-links this callout to a page that visibly lists v4/v5, a one-line update to say "Python SDK v4" / "JS-TS SDK v5" (or drop the ve
Comment on lines 40 to 45

@claude claude Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 The self-hosting requirements callout still names Python SDK v3 and TypeScript SDK v4 as if current, but the top of this same file (lines 17–18) and the new /docs/compatibility page identify Python v4 / JS-TS v5 as current. The numeric minimums (≥ 3.125.0 and ≥ 3.95.0) happen to match v4/v5 too, so the copy is out of date rather than wrong — but since this PR now cross-links this callout to a page that visibly lists v4/v5, a one-line update to say "Python SDK v4" / "JS-TS SDK v5" (or drop the version-specific sentence in favor of the new compatibility link) would remove the mismatch. Pre-existing copy — not a merge blocker.

Extended reasoning...

What the bug is. In content/docs/observability/sdk/overview.mdx, the <Details>Requirements for self-hosted Langfuse</Details> callout at lines 40–44 reads: "the Python SDK v3 requires Langfuse platform version ≥ 3.125.0 and the TypeScript SDK v4 requires Langfuse platform version ≥ 3.95.0". But the file's own header at lines 17–18 advertises Python SDK v4 and JS/TS SDK v5 as the SDKs to install, and the second <Details> block right below ("Legacy documentation") explicitly labels Python v3 and TypeScript v4 as legacy. So the same file, within a ~40-line window, both calls v3/v4 legacy and names them in an active self-hosting requirement.\n\nWhy the PR now surfaces this. The PR adds a new line inside this exact callout: "See the full versions & compatibility overview …". The linked page's SDK↔server matrix lists Python v4 and JS/TS v5 as GA / current and Python v3 / JS-TS v4 as Legacy. So a reader who follows the newly-added link immediately sees v4/v5 as current, then looks back at the sentence above the link and sees only v3/v4 named. The PR made the mismatch more visible without fixing the underlying stale copy.\n\nWhy it's not factually wrong (just stale). Per the new compatibility.mdx, Python SDK v4 shares the same ≥ 3.125.0 minimum as v3, and JS/TS v5 shares the same ≥ 3.95.0 minimum as v4. So the numbers still hold for a self-hoster on the current SDKs — the requirement bound is correct. The problem is framing: someone reading this on Python v4 or JS-TS v5 does not see their major called out at all, and has to infer that the constraint stated for the legacy version transfers to them.\n\nImpact. Low. A self-hoster on the current SDKs might briefly wonder whether the requirement applies to them, then follow the new /docs/compatibility link and confirm it does. Nothing breaks; the constraint is preserved. This is a documentation polish issue, not a correctness issue — hence nit severity.\n\nStep-by-step proof.\n1. Open content/docs/observability/sdk/overview.mdx line 17: "Python SDK v4".\n2. Line 18: "JS/TS SDK v5".\n3. Line 40 (inside <Details>Requirements for self-hosted Langfuse</Details>): "the Python SDK v3 requires Langfuse platform version ≥ 3.125.0 and the TypeScript SDK v4 requires Langfuse platform version ≥ 3.95.0".\n4. Line 42 (added by this PR): "See the full versions & compatibility overview …".\n5. Open content/docs/compatibility.mdx — the "SDK ↔ server compatibility" table lists Python SDK v4 → GA / ≥ 3.125.0, Python SDK v3 → Legacy, JS/TS SDK v5 → GA / ≥ 3.95.0, JS/TS SDK v4 → Legacy.\n6. Result: the callout the PR just cross-linked names only the legacy majors as if they were current.\n\nHow to fix. Either (a) update the sentence to "the Python SDK v4 requires Langfuse platform version ≥ 3.125.0 and the JS/TS SDK v5 requires Langfuse platform version ≥ 3.95.0", or (b) drop the version-specific sentence entirely and let the newly added /docs/compatibility link carry the details (that page already lists both current and legacy majors with their minimums). Option (b) also removes the need to keep two places in sync going forward.\n\nSeverity. Nit — pre-existing copy the PR only touches to append a link. Numeric constraint is still accurate; only the version-name framing is out of date. Not a merge blocker.


</Details>

Expand Down
2 changes: 2 additions & 0 deletions content/faq/all/compatibility-langfuse-ui-and-python-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
4 changes: 4 additions & 0 deletions content/self-hosting/upgrade/versioning.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Callout type="info">
For an overview of current and legacy versions, the SDK ↔ server compatibility matrix, and API version availability, see [Versions & compatibility](/docs/compatibility).
</Callout>

## Scope of semantic versioning

The following changes **result in a major version bump** as they are considered breaking:
Expand Down
Loading