-
Notifications
You must be signed in to change notification settings - Fork 265
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.
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
main
Choose a base branch
from
docs/versions-and-compatibility-page
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
0badb5c
docs: add versions & compatibility overview page
maxdeichmann 777d086
docs(compatibility): apply coverage-audit fixes
maxdeichmann 2a852af
docs(compatibility): readability pass from cold-read testing
maxdeichmann ee152b5
docs(compatibility): merge Legacy status into Deprecated
maxdeichmann 862b1cd
chore: prettier formatting
maxdeichmann File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,107 @@ | ||
| --- | ||
| 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. 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.** | ||
| </Callout> | ||
|
|
||
| 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) <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. Requires Python 3.9+. | | ||
| | 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. 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) | 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) | | ||
|
|
||
| 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] | ||
|
|
||
| ### 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 | 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` | 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. | ||
|
|
||
| <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 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 | 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 deprecated export source (existing projects and self-hosted are unaffected). | ||
|
|
||
| ## 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). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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 newcompatibility.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. Opencontent/docs/observability/sdk/overview.mdxline 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. Opencontent/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/compatibilitylink 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.