docs(self-hosting): add v3 to v4 upgrade guide draft

[Steffen911]

Adds the self-hosted Langfuse v3 to v4 migration guide, structured as three independent steps (infrastructure, server upgrade with write-mode choice, data-model migration) with backfill and retention-based rollover options. Inline TODOs mark items to verify against the codebase before publishing.

Greptile Summary

This PR introduces the self-hosted Langfuse v3-to-v4 migration guide and updates all existing docs to replace the "Fast Preview" label with "Langfuse v4," reflecting the feature's general availability for self-hosted deployments.

• New migration guide (upgrade-v3-to-v4.mdx): documents a three-step, independent upgrade path \u2014 infrastructure (ClickHouse version gate), server upgrade with a choice between legacy, dual, and events_only write modes, and a data-model cutover via automated backfill or retention-based rollover.
• Terminology sweep: every \u201cFast Preview\u201d reference across changelogs, FAQ pages, integration docs, and observability feature pages is updated to \u201cLangfuse v4\u201d with availability callouts pointing to the new upgrade guide.
• Two factual errors need correction before publish: the intro callout links to discussion 12518 (the announcement) instead of the v4 rollout thread 14157, and the Support section\u2019s GitHub Issues link is a relative path that resolves to the docs host rather than the repository.

Confidence Score: 3/5

The terminology sweep is safe; the new migration guide has two broken links that should be fixed before publishing.

The bulk of the PR is a mechanical rename across docs files — low risk and internally consistent. The new upgrade guide is detailed and well-structured, but the intro callout links to the wrong GitHub Discussion (12518 vs the correct 14157), and the Support section uses a relative /issues path that resolves to the docs host rather than GitHub. Both affect navigation-critical content aimed at operators performing an irreversible migration.

content/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4.mdx — the intro callout GitHub Discussion link and the Support section /issues URL should both be corrected before publishing.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([Start: Existing Langfuse v3 deployment]) --> B[Step 1: Upgrade ClickHouse to 25.12+ / 26.4 recommended]
    B --> C[Step 2: Upgrade server to Langfuse v4]
    C --> D{Choose write mode}
    D -->|events_only default| E[events_only: Writes only to new events tables. Historic backfill starts automatically]
    D -->|dual| F[dual: Writes to old AND new tables. UI toggle and v2 APIs available]
    D -->|legacy| G[legacy: Full v3 behavior retained. No writes to new tables]
    G --> H[Switch to dual write when ready]
    H --> F
    E --> DONE([Migration complete])
    F --> I[Step 3: Upgrade SDKs - Python v4 / JS-TS v5 / OTEL]
    I --> J{Historic data strategy}
    J -->|Option A: Backfill| K[Enable backfill. Newest-first, gradual. Requires 3x disk headroom]
    J -->|Option B: Retention rollover| L[Wait one full retention window while dual-writing]
    K --> M[Cut over to events_only. Remove migration env vars]
    L --> M
    M --> N[Optional: Truncate old tables to reclaim ClickHouse disk]
    N --> DONE

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A([Start: Existing Langfuse v3 deployment]) --> B[Step 1: Upgrade ClickHouse to 25.12+ / 26.4 recommended]
    B --> C[Step 2: Upgrade server to Langfuse v4]
    C --> D{Choose write mode}
    D -->|events_only default| E[events_only: Writes only to new events tables. Historic backfill starts automatically]
    D -->|dual| F[dual: Writes to old AND new tables. UI toggle and v2 APIs available]
    D -->|legacy| G[legacy: Full v3 behavior retained. No writes to new tables]
    G --> H[Switch to dual write when ready]
    H --> F
    E --> DONE([Migration complete])
    F --> I[Step 3: Upgrade SDKs - Python v4 / JS-TS v5 / OTEL]
    I --> J{Historic data strategy}
    J -->|Option A: Backfill| K[Enable backfill. Newest-first, gradual. Requires 3x disk headroom]
    J -->|Option B: Retention rollover| L[Wait one full retention window while dual-writing]
    K --> M[Cut over to events_only. Remove migration env vars]
    L --> M
    M --> N[Optional: Truncate old tables to reclaim ClickHouse disk]
    N --> DONE

Loading

Prompt To Fix All With AI

Fix the following 4 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 4
content/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4.mdx:830-833
**Wrong GitHub Discussion linked in intro callout**

The intro callout links discussion `12518` as the "v4 rollout GitHub Discussion," but that is the original architecture announcement. The dedicated self-hosted v4 rollout thread is `14157` — the same one used throughout the rest of this file (Support section) and in `content/docs/v4.mdx`. Users clicking this link will land in the wrong thread when seeking upgrade help.

### Issue 2 of 4
content/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4.mdx:1192-1194
**Relative `/issues` link resolves to docs site, not GitHub**

`[GitHub Issue](/issues)` is a relative path that will resolve to the documentation host (e.g., `langfuse.com/issues`), not to the actual GitHub repository issues page. It should be an absolute URL such as `https://github.com/langfuse/langfuse/issues`.

### Issue 3 of 4
content/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4.mdx:999-1008
**`LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=dual_write` may be meaningless in `legacy` write mode**

In `legacy` mode nothing is written to the new `events` tables, so setting `LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=dual_write` — which controls how OTel spans flow into both old and new tables — may have no effect at all (or conflict with startup validation). The inline TODO acknowledges this is unverified. Including it in the published example config could confuse operators who copy the snippet and later discover the flag is silently ignored or invalid.

### Issue 4 of 4
content/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4.mdx:884
**Inline TODO marks an unverified API endpoint list**

The comment `{/* TODO: verify the final endpoint list against the rejectInEventsOnlyMode gates … */}` sits directly above the table of endpoints that return `404` in `events_only` mode. If any of those endpoints are incorrect at publish time, operators will either expect breakage that does not happen (no impact) or not expect breakage that does happen (downtime/data loss). The TODO should be resolved before the guide goes live.

_{Reviews (1): Last reviewed commit: "Merge branch 'main' into docs/upgrade-gu..." | Re-trigger Greptile}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview, Comment	Jul 23, 2026 10:28am

[github-actions]

@claude review

[AkioNuernberger]

Herculean effort and excited for this step. Looks great overall.

Few minor things:

• Clear deadlines to prevent Parkinson's law: Add info on how long we are planning to support dual writes and the legacy tables. Users need this information to plan accordingly or to convince people to invest time in the upgrade.
• Would add a sub-step in Step 3 Move to the new data model after 3.1 Upgrade your producers to compatible SDKs for completeness. Add: Upgrade your API consumers/exports to new APIs: Link to the APIs listed above.
  • Might make sense to add that another steps to migrate the evals
• For the V4 events (observations) view, would it make sense to set the default view to root spans only and nudge the user in product to add select more observations if they want to deep dive? I feel like this would a user friendly way to not overwhelm the users with all the different observations. (not sure how this would behave in installations without a rootspan tho)

[AkioNuernberger]

Also, please let us know before you are going to publish this → I would like to coordinate with @jannikmaierhoefer to send out communication to the enterprise customers.

[annabellscha]

minor comments, never deployed or migrated langfuse, so hard to judge

[marliessophie]

As per DM, @marliessophie to add context on how to upgrade trace-level evals for self-hosters.

[Lotte-Verheyden]

No specific comments, looks nice! One thing to keep in mind: these changes will probably interfere with @maxdeichmann's PR here and there: #3330