本页还没有译文
本页 70 段还没译成简体中文，下面显示的是英文原文。Versions & Compatibility
还没翻译译自英文（langfuse.com）本页 70 段都还没译
Versioning is key to ensure compatibility between Langfuse Server, SDKs, and custom integrations via the Public API. Thus, we take semantic versioning seriously.
Note
The feature availability matrix below shows what each self-hosted server version supports. For Langfuse Cloud and an overview of current and legacy versions, see Versions & Compatibility.
Scope of semantic versioning
The following changes result in a major version bump as they are considered breaking:
- Infrastructure changes
- Removal of existing Public APIs or removal/changes of existing parameters from Public APIs
The following changes do not result in a major version bump as they are considered internal implementation details:
- Database schemas
- Frontend APIs
Compatibility between Langfuse Server and SDKs
Langfuse Server and SDKs are versioned independently to allow for more flexibility in upgrading components. The compatibility rule: each server major version aims to support the current and the previous SDK major version of each language, and each SDK major requires a minimum server version. We try extremely hard to uphold this rule, but the v4 transition is an exception: it ends support for older SDK majors on a published schedule (see the feature availability matrix).
- Server: Can be upgraded independently of SDK versions within the supported range. Major server upgrades can drop support for old SDK majors; check the feature availability matrix and the upgrade guide before upgrading.
- SDKs: Older SDK majors keep working on newer servers until they are deprecated and removed. New SDK majors require the minimum server versions listed in the feature availability matrix.
We recommend keeping the Langfuse Server up to date to ensure access to all features and security updates.
How Langfuse Cloud is versioned
Langfuse Cloud deploys continuously and always runs the latest Langfuse version. New capabilities are battle-tested on Langfuse Cloud before they ship in a self-hosted release, so Cloud can run ahead of the latest self-hosted version, and some features may be enabled on Cloud before they are available self-hosted.
Consequences:
- On Cloud, server versions are managed for you; only SDK versions and API endpoints matter.
- Breaking removals on Cloud are announced with a migration window and happen on published dates; on self-hosted they only happen in major releases. Cloud removals are tracked in the Langfuse Cloud matrix, self-hosted support in the matrix below.
Feature availability matrix
The matrix below shows what each self-hosted server major version supports: security patches, SDK majors with their minimum server versions, ingestion paths, read APIs, exports, and evaluators. Click a row for details and replacement endpoints.
On Langfuse Cloud, server versions are managed for you; use the Langfuse Cloud matrix instead.
| Client | OSS v2 (End of life) | OSS v3 (Deprecated) | OSS v4 (GA) | Status |
|---|---|---|---|---|
| Server support · Upgrade guide | ||||
| Security patches | No | Through January 31, 2027 | Yes | |
| Python · Upgrade guide | ||||
| Python SDK v5 | Unsupported | Unsupported | ≥ 4.59.0 | GA |
| Python SDK v4 | Unsupported | ≥ 3.63.0 | Full | GA |
| Python SDK v3 | Unsupported | ≥ 3.63.0 | Deprecated | Deprecated |
| Python SDK v2 | Full | Full | Unsupported | Deprecated |
| Python SDK v1 | Full | Unsupported | Unsupported | End of life |
| JS/TS · Upgrade guide | ||||
| JS/TS SDK v6 | Unsupported | Unsupported | ≥ 4.59.0 | GA |
| JS/TS SDK v5 | Unsupported | ≥ 3.63.0 | Full | GA |
| JS/TS SDK v4 | Unsupported | ≥ 3.63.0 | Deprecated | Deprecated |
| JS/TS SDK v3 / v2 | Full | Full | Unsupported | Deprecated |
| JS/TS SDK v1 | Full | Unsupported | Unsupported | End of life |
| Third-party instrumentation · OpenTelemetry docs | ||||
OpenTelemetry/api/public/otel/v1/traces | Unsupported | ≥ 3.22.0 | Full | GA |
Direct scores ingestion/api/public/scores | Full | Full | Full | GA |
SDK scores ingestionscore-create via /api/public/ingestion | Full | Full | Full | GA |
Legacy trace and observation events/api/public/ingestion | Full | Full | Unsupported | Deprecated |
| Read APIs · Public API docs | ||||
Observations API v2 & Metrics API v2/api/public/v2/... | Unsupported | Unsupported | Full | GA |
Scores API v3/api/public/v3/scores | Unsupported | Full | Full | GA |
Deprecated read APIstraces, observations, sessions, scores, metrics, dataset runs | Full | Full | Unsupported | Deprecated |
| Metrics & alerts · Alerts docs | ||||
| Alerts | Unsupported | Unsupported | Full | GA |
| Integrations & exports · Export docs | ||||
| Blob storage export | Unsupported | Traces & observations | Enriched observations | GA |
| PostHog integration | Unsupported | Traces & observations | Enriched observations | GA |
| Mixpanel integration | Unsupported | Traces & observations | Enriched observations | GA |
| Legacy export source (traces and observations) | Unsupported | Full | Deprecated | Deprecated |
| Evaluations · LLM-as-a-judge docs | ||||
| Observation-level evaluators | Unsupported | ≥ 3.153.0 | Full | GA |
| Trace-level evaluators | Full | Full | Deprecated | Deprecated |
Python SDK v5
GA. Requires self-hosted server ≥ 4.59.0; OSS v3 and older are unsupported. If you self-host Langfuse v3, stay on Python SDK v4. See the Python v4 → v5 upgrade guide.
Python SDK v4
GA. Requires self-hosted server ≥ 3.63.0; OSS v2 and older are unsupported.
Limitations:
| Capability | OSS v3 | OSS v4 |
|---|---|---|
| Tracing (OpenTelemetry) | Supported | Supported (real time with SDK ≥ 4.7.0) |
Public API & querying (api.*) | Use the legacy APIs api.legacy.observations_v1 / api.legacy.metrics_v1 | Supported (deprecated read APIs are removed on v4) |
Python SDK v3
Deprecated. Requires self-hosted server ≥ 3.63.0; OSS v2 and older are unsupported.
Limitations:
| Capability | OSS v3 | OSS v4 |
|---|---|---|
| Tracing (OpenTelemetry) | Supported | Supported (data delayed up to 15 min; Python SDK v4 ≥ 4.7.0 for real time) |
| Datasets & experiments | Datasets only (experiments require Python SDK v4) | Datasets only (experiments require Python SDK v4) |
Public API & querying (api.*) | Supported | Unsupported (deprecated read APIs are removed on v4; upgrade to Python SDK v4) |
Python SDK v2
Deprecated.
Limitations:
| Capability | OSS v2 | OSS v3 | OSS v4 |
|---|---|---|---|
| Tracing (legacy batch ingestion) | Supported | Supported | Unsupported |
| Datasets & experiments | Datasets only (experiments require Python SDK v4) | Datasets only (experiments require Python SDK v4) | Datasets only (experiments require Python SDK v4) |
| Media (multimodal) | Requires OSS v3 | Supported | Supported |
Public API & querying (api.*) | Supported | Supported | Unsupported (deprecated read APIs are removed on v4; upgrade to Python SDK v4) |
JS/TS SDK v6
GA. Requires self-hosted server ≥ 4.59.0; OSS v3 and older are unsupported. If you self-host Langfuse v3, stay on JS/TS SDK v5. See the JS/TS v5 → v6 upgrade guide.
JS/TS SDK v5
GA. Requires self-hosted server ≥ 3.63.0; OSS v2 and older are unsupported.
Limitations:
| Capability | OSS v3 | OSS v4 |
|---|---|---|
| Tracing (OpenTelemetry) | Supported | Supported (real time with SDK ≥ 5.4.0) |
Public API & querying (api.*) | Use the legacy APIs api.legacy.observationsV1 / api.legacy.metricsV1 | Supported (deprecated read APIs are removed on v4. Langfuse Cloud serves these endpoints until November 16, 2026 (2026-11-16); migrate to v4 before this date.) |
JS/TS SDK v4
Deprecated. Requires self-hosted server ≥ 3.63.0; OSS v2 and older are unsupported.
Limitations:
| Capability | OSS v3 | OSS v4 |
|---|---|---|
| Tracing (OpenTelemetry) | Supported | Supported (data delayed up to 15 min; JS/TS SDK v5 ≥ 5.4.0 for real time) |
| Datasets & experiments | Datasets only (experiments require JS/TS SDK v5) | Datasets only (experiments require JS/TS SDK v5) |
Public API & querying (api.*) | Supported | Unsupported (deprecated read APIs are removed on v4. Langfuse Cloud serves these endpoints until November 16, 2026 (2026-11-16); upgrade to JS/TS SDK v5) |
JS/TS SDK v3 / v2
Deprecated.
Limitations:
| Capability | OSS v2 | OSS v3 | OSS v4 |
|---|---|---|---|
| Tracing (legacy batch ingestion) | Supported | Supported | Unsupported |
| Datasets & experiments | Datasets only (experiments require JS/TS SDK v5) | Datasets only (experiments require JS/TS SDK v5) | Datasets only (experiments require JS/TS SDK v5) |
| Media (multimodal) | Requires OSS v3 | Supported | Supported |
Public API & querying (api.*) | Supported | Supported | Unsupported (deprecated read APIs are removed on v4; upgrade to JS/TS SDK v5) |
OpenTelemetry
GA. Any OpenTelemetry SDK can export to the OTLP endpoint, available since OSS 3.22.0. On Langfuse v4, send the x-langfuse-ingestion-version: 4 header on your span exporter to see data in real time; without it, data can be delayed by up to 15 minutes. (Langfuse SDKs at Python ≥ 4.7.0 / JS ≥ 5.4.0 qualify for real time automatically; self-hosted deployments can set LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=direct to make all OTLP ingestion real time without the header.) See the OpenTelemetry setup guide.
Legacy trace and observation events
Deprecated. Trace, span, and generation events via the legacy batch ingestion API are not supported on the v4 data model: on Langfuse Cloud they keep working until November 16, 2026 (2026-11-16), on self-hosted Langfuse v4 in events_only mode they are rejected. The same applies to the older POST /api/public/traces, /spans, /generations, and /events endpoints. Migrate to OpenTelemetry ingestion.
Deprecated read APIs
Deprecated. Removed on Langfuse v4 and on Langfuse Cloud on November 16, 2026 (2026-11-16). The migration guide is the canonical per-endpoint mapping with parameter tables and before/after examples; it also documents the deprecated endpoints themselves.
Deprecated GET endpoints | Replacement |
|---|---|
/api/public/observations, /api/public/observations/{id} | Observations API v2 |
/api/public/traces, /api/public/traces/{id} | Observations API v2, filtered by traceId |
/api/public/sessions, /api/public/sessions/{id} | Observations API v2, filtered by sessionId |
/api/public/scores, /api/public/v2/scores (+ /{id}) | Scores API v3 |
/api/public/metrics, /api/public/metrics/daily | Metrics API v2 |
/api/public/datasets/{name}/runs (+ /{runName}) | Experiments API |
/api/public/dataset-run-items | Experiment Items API |
Observations API v2 & Metrics API v2
GA. Requires Langfuse v4. See the Observations API v2 and Metrics API v2 docs.
- Via SDK: these are the default resources (
api.observations,api.metrics) in Python SDK v4+ and JS/TS SDK v5+. On OSS v3, the defaults fail; with Python SDK v4 / JS/TS SDK v5, useapi.legacy.observations_v1/api.legacy.metrics_v1(Python) orapi.legacy.observationsV1/api.legacy.metricsV1(JS/TS). - Via REST:
GET /api/public/v2/observations?fromStartTime={datetime}&toStartTime={datetime}andGET /api/public/v2/metrics?query={json}. - Data freshness: data from older SDKs (Python < 4.7.0, JS < 5.4.0) or OTel exporters without the
x-langfuse-ingestion-version: 4header can appear on these APIs with up to a 10-minute delay. Upgrade to Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0 (or set the header) for real-time data.
Alerts
GA. Requires Langfuse v4. Threshold-based alerts on your LLM application metrics with notifications via Slack, webhooks, and GitHub Actions; self-hosted deployments have no alert limit. See the alerts docs.
Trace-level evaluators
Deprecated. Migrate to observation-level evaluators. Trace-level evaluators are not supported on the v4 data model; on Langfuse Cloud they keep running until November 16, 2026 (2026-11-16). On self-hosted Langfuse v4 in events_only mode, they will no longer produce results.
Legacy export source (traces and observations)
Deprecated. Exports built on the legacy "traces and observations" source are replaced by the enriched observations source (v4 data model). On Langfuse Cloud, projects created on or after 2026-05-20 cannot select legacy sources, new legacy export integrations cannot be created since 2026-06-22, and remaining legacy exports are switched to the enriched source automatically on November 16, 2026 (2026-11-16).
Release Notes
Release notes are published on GitHub:
You can watch the GitHub releases to get notified about new releases:
Also, you can subscribe to our mailing list to get notified about new releases and new major versions:
Note
Langfuse OSS updates — get an email when we ship important features and new releases for self-hosted (open source) Langfuse. Self-hosting updates only, no spam.