What a Langfuse migration involves
A Langfuse migration means one of two things: moving trace, prompt and evaluation data from Langfuse Cloud or another LLM observability tool onto a self-hosted Langfuse you run, or moving an existing self-hosted Langfuse from one major version to the next. Both can happen in the same project, and they carry different risks. The first is mainly a data mapping and cutover exercise. The second changes the architecture underneath the application, so it needs its own plan.
Teams usually start a move from Langfuse Cloud or another tool for a small set of reasons: data residency, which determines where traces that may contain user input and model output can be stored; network isolation, where the platform must run inside a private network with no outbound path to a vendor; and cost control at high trace volume. Name the trigger first, because it sets the acceptance criteria. A residency driver means the storage locations and access paths must be documented. A cost driver means you need current trace volume and retention figures before comparing options.
Major versions change the architecture. The v2 to v3 move adds ClickHouse as an analytical store alongside PostgreSQL, so the target environment needs that database sized, backed up and monitored before any data is moved. The v3 to v4 move changes the data model to observations-first and includes a backfill of historic data. Langfuse's guide advises about 3x ClickHouse disk headroom for that backfill, so confirm free disk space and the ClickHouse version (25.12 or later, with 26.4 recommended) before scheduling. Helm users with bundled data stores must upgrade the chart from v1 to v2 first.
Decide early whether your internal team or a partner runs the work. In-house teams often handle a single-version upgrade on a small instance with a tested rollback. A partner is more often involved when a cloud-to-self-hosted move must be cut over without losing history, when a v3 to v4 backfill must run against production-sized ClickHouse, or when SDK versions across many services must be coordinated. In either case, ask for a written scope that names the source system, the data to be carried over, the rollback point and who signs off the cutover.
What the work includes
A Langfuse migration usually runs as a set of connected workstreams, from sizing the target environment to cutting applications over and handing the system to your team. The cards below describe what each one covers and what to check before it closes.
Target architecture and sizing
We define the target topology, including the Docker Compose or Kubernetes path, replica counts and whether langfuse-web is split into ingestion and UI deployments. Sizing starts from expected trace volume and the minimum resources Langfuse documents for each component. Check that the plan names the environments, failure domains and the data store versions your chosen Langfuse release requires.
Web and worker deployment
Langfuse Web serves the UI and APIs, and Langfuse Worker processes asynchronous events, so both must be deployed, scaled and monitored separately. The worker is the component most likely to fall behind under heavy ingestion. Confirm how each container is configured, how secrets reach it and how scaling decisions will be made.
Data store deployment
PostgreSQL holds application metadata, ClickHouse holds traces and observations, Redis or Valkey handles queues and caching, and S3-compatible storage keeps blobs such as uploaded media. Each store is provisioned in your infrastructure with its own sizing, access control and backup path. Confirm which of these are managed services and which are bundled, because that changes the upgrade and recovery work.
Data movement or re-instrumentation
Migrating from Langfuse Cloud or another observability tool means either moving historic data or accepting a clean break and re-instrumenting applications. Export formats, trace identifiers and user or session attributes often differ between sources, so mapping them is the main effort. Agree in writing what history is kept, what is archived and how completeness will be checked.
SDK and application cutover
Applications switch their Langfuse host, keys and SDK versions in a planned sequence, often one service at a time. Newer SDK majors require minimum Langfuse versions, so SDK and server versions must be aligned before cutover. Check rollback steps for each application and confirm that traces arrive in the new instance before the old endpoint is retired.
Runbooks and handover documentation
Runbooks cover routine operations, upgrades, backup restores, scaling changes and the signals that ingestion is falling behind. They are written for the team that will operate the system after go-live. Handover includes the architecture record, a migration log, validation evidence and the procedures your operators will use without us.
What drives cost and duration
This table lists the drivers that change migration effort and duration, why each one matters, and how to keep each one contained.
| Driver | Why it moves effort | How to keep it contained |
|---|---|---|
| Trace and observation volume | Ingestion rate sets ClickHouse, worker and web sizing, and how long dual running must last. | Measure daily volume over a representative period and size from that measurement, starting from the scaling guide minimums. |
| Historic data to move | Bulk export, transformation and import take time, and backfilling needs spare ClickHouse disk while it runs. | Move only history that must stay queryable. Plan ClickHouse disk for roughly 3x the data being backfilled, per the v3 to v4 upgrade guide. |
| Applications and SDK integrations | Every service sending traces or fetching prompts needs its host, keys and SDK version changed and retested. | Inventory integrations before planning. Group services by SDK and repoint each group with one shared configuration pattern. |
| Projects and prompt versions | Each project needs keys and mapped history, and large prompt version counts lengthen import checks. | Map projects to target keys before import. Migrate active prompt versions and labels first, then decide on older history. |
| Deployment target | Langfuse documents Docker Compose on one VM for testing only, without high availability. Kubernetes adds chart, cluster and networking work. | Rehearse on a single VM if useful, but plan production on Kubernetes with Helm or Terraform on your cloud provider. |
| Environments | Dev, staging and production each repeat the import, cutover and verification, so drift between them adds rework. | Use staging as the full rehearsal. Keep versions and data store configuration aligned across environments before cutover. |
| Edition | Core features are in the MIT open source version, while SCIM, data retention and audit logs need an Enterprise license key. | List required features before design. Confirm with the vendor which features need a key, and include key setup in scope. |
| Architecture migration (v2 to v3 or v3 to v4) | Adding ClickHouse (v2 to v3) or moving to a new data model with backfill (v3 to v4) adds a separate project phase. | Decide the target major version first. Check data store minimums, Helm chart upgrades and SDK versions in the migration guide before scheduling. |
Migration phases and outputs
The sequence moves traces, prompts, scores and integrations into a self-hosted Langfuse you operate, with each phase closing on a written output that gates the next.
Inventory current traces, prompts, scores and integrations
Your team and DeployOpen list what the current tool holds and what calls it: trace and observation volumes, prompt versions and labels, scores and evaluators, SDK and OpenTelemetry integrations, users and API keys. The output is a signed-off inventory that states what must move, what can be archived and what will be rebuilt rather than copied.
Design the target and size it against minimums
The target architecture is set in writing: Kubernetes or Docker Compose for the environment, Langfuse Web and Worker, PostgreSQL, ClickHouse, Redis or Valkey and S3-compatible storage, with sizing checked against Langfuse's published minimum resources and your expected ingestion. The output is an architecture decision record and a sizing sheet that your infrastructure and security teams approve. Docker Compose on a single VM is documented for testing only, so production designs need to plan for high availability separately.
Build the non-production environment
The target stack is deployed in a non-production environment in your infrastructure, with SSO, secrets, network policy, backups and monitoring configured as they will be in production. The output is a working environment that passes smoke tests for ingestion, the UI, the public API and a restore from backup, documented in a runbook.
Rehearse the data migration and validate results
The data move is run at least once in non-production against a representative copy of the exported data. Record counts, sampled traces, prompt versions and scores are compared between source and target, and any gaps are logged with owners. If the move crosses a major version, such as v2 to v3 or v3 to v4, the rehearsal also covers the documented migration steps and the ClickHouse disk headroom they call for. The output is a validation report that names every accepted difference.
Cut over SDKs and applications
Application teams change their SDK or OpenTelemetry exporter configuration to point at the new endpoint and keys, in staged releases behind feature flags or configuration. Each service is checked for trace arrival, user and session attributes and error handling. The output is a per-application cutover checklist with sign-off from each owning team.
Switch production and run a parallel period
Production traffic moves to the new instance while the old tool stays readable for an agreed period so teams can compare results and fall back if needed. Ingestion lag, error rates and dashboard queries are watched during this window. The output is a closed parallel-run report and a documented rollback decision, signed off by the service owner.
Decommission the old tool
Once the parallel period closes, final exports are archived under your retention policy, API keys and integrations on the old tool are revoked, and the instance is shut down. Data retention obligations are confirmed before deletion. The output is a decommissioning record covering archive location, revoked credentials and deletion date.
What to keep in-house and what to outsource
Each row names one part of a Langfuse migration, the skills it needs, and whether teams usually keep it in-house or hand it to an implementation partner, so you can mark the gaps in your own team before scoping.
| Migration part | Usually in-house | Often outsourced | Skills it needs |
|---|---|---|---|
| Application instrumentation | Yes, by application owners who know traces and user or session context | Partly, as a review of SDK or OTLP setup | LLM application engineering, OpenTelemetry or native Langfuse SDK use |
| Prompt and evaluation content | Yes, prompt owners and evaluators keep their own prompts, scores and datasets | No, unless a partner helps move existing content | Prompt design, evaluation methods, domain knowledge of the application |
| Sign-off on trace data | Yes, data owners decide what may be stored, masked or retained | No, partners can document options but cannot approve data use | Data classification, privacy review, retention policy ownership |
| Kubernetes or Compose deployment | Only if you already run Kubernetes production well | Often, including Helm or Terraform setup and environment parity | Kubernetes operations, Helm, ingress, secrets management |
| ClickHouse and PostgreSQL setup | Only if your DBA team already runs both at the sizes planned | Often, covering sizing, backups and version requirements | ClickHouse administration, PostgreSQL operations, backup and restore testing |
| Migration tooling and cutover | Shared, since your team must confirm which data moves and when | Often, for scripts, dry runs and rollback steps | Data engineering, scripting, change management for tracing |
| v3 to v4 backfill planning | Shared, with owners approving the historic data window | Often, for headroom checks and backfill runbooks | ClickHouse capacity planning, Langfuse upgrade guide knowledge, observability operations |
What usually goes wrong
Most Langfuse migration problems come from version sequencing, storage sizing and cutover planning. Each card names a failure mode and the check that prevents it.
Backfill without disk headroom
The v3 to v4 upgrade guide advises about 3x ClickHouse disk headroom when backfilling historic data. Teams that size disks for steady-state ingestion can run out of space partway through the backfill, leaving the migration incomplete. Before starting, measure current ClickHouse data size, apply the 3x guidance, and confirm free space on every node.
ClickHouse below the 25.12 minimum
The v4 upgrade requires ClickHouse 25.12 or later, and the guide recommends 26.4. Clusters deployed from older images or pinned in Helm values during the v2 era can fail the upgrade or run an unsupported version. Check the running server version on every replica and update the image tag as a planned step.
Skipping the Helm v1 to v2 chart upgrade
Helm users with bundled data stores must move the chart from v1 to v2 before upgrading Langfuse to v4. Teams that jump straight to the application version can end up with bundled PostgreSQL, Redis or ClickHouse settings that no longer match the chart. Plan the chart step as its own change, test it in a non-production environment and document a rollback.
SDK versions below the required minimums
Python SDK v5 and JS/TS SDK v6 need Langfuse v4.59.0 or later. Upgrading clients before the server, or upgrading the server without reviewing client code, can cause trace calls to fail. Inventory every service and notebook that sends traces, record each SDK version, and sequence client upgrades after the server reaches the required release.
Trace gaps and duplicates during cutover
Gaps appear when applications switch endpoints or keys before the self-hosted instance is verified, leaving a window with no traces. Duplicates appear when the old and new backends receive the same traffic during a parallel run. Set a switch time for each service, compare trace counts in both systems across the overlap, and name the authoritative backend for reporting.
Assuming Enterprise features on open source
Project-level RBAC roles, protected prompt labels, data retention policies, audit logs, server-side data masking and SCIM need an Enterprise license key. Teams that plan access control, retention or audit evidence around the open source edition often find gaps late. Map each access and compliance requirement to an edition before design sign-off, and confirm current terms with Langfuse.
How the work changes by starting point
Your traces, prompts and scores already sit in Langfuse Cloud, so the work centers on moving data and repointing applications. The self-hosted version uses the same codebase, so features carry over, but identities, keys and licensing need separate planning.
- Export path: Confirm with Langfuse which export formats and API endpoints cover traces, observations, scores, datasets and prompt versions for each project.
- Data inventory: Ask for a per-project inventory so the backfill plan reflects what is stored.
- Endpoints: Update SDK host settings and OTLP endpoints in each application, and plan a window where both hosts receive traffic.
- Identity and keys: Confirm how user accounts and project API keys are handled, then map users to your SSO provider.
- Enterprise features: Check which Cloud features you rely on, such as project RBAC, protected labels, retention and audit logs, since these need an Enterprise license key when self-hosted.
Moving from another LLM observability tool usually means re-instrumenting applications, because existing traces rarely map cleanly into Langfuse. Two routes exist: OpenTelemetry over OTLP to the Langfuse OTEL endpoint, or the native Langfuse SDKs.
- Instrumentation route: Use OTLP where your frameworks, such as LangChain, LlamaIndex, CrewAI or AutoGen, already emit OpenTelemetry, and native SDKs where you need Langfuse-specific objects.
- Historic data: Ask the vendor which export formats exist and whether they map to Langfuse observations before promising any history.
- Prompts and datasets: Export prompt versions and evaluation datasets separately from traces, since they often need different handling.
- Parallel running: Send telemetry to both tools for a period so teams can compare traces and dashboards before retiring the old tool.
- Ownership: Each application team changes its own code, so count the services early and assign owners for each change.
Version 3 adds ClickHouse as an analytical store alongside PostgreSQL, so this migration changes the architecture as well as the version. The work is mostly infrastructure planning before the cutover.
- ClickHouse: Plan sizing, memory, disk, backups and an operations owner for the new database before the upgrade window.
- Cache layer: Confirm whether your v2 deployment already runs Redis or Valkey, and at what version, before you set the target.
- Data movement: Confirm in the upgrade guide how existing v2 data is handled and whether historic data needs a separate backfill into ClickHouse.
- Blob storage and networking: Check the S3-compatible storage and network paths that the new containers will use.
- Upgrade sequence: Confirm the required steps and whether any intermediate version must be applied first.
Version 4 moves to an observations-first ClickHouse data model and requires backfilling historic data, so the work is weighted toward data planning and version alignment across the stack.
- Data store versions: Confirm ClickHouse 25.12 or later (26.4 recommended), PostgreSQL 15 or later and Redis 7.0 or later before you schedule the upgrade.
- Backfill headroom: Plan for the additional ClickHouse disk headroom that the v3 to v4 upgrade guide advises for backfilling historic data.
- Helm chart: If you use bundled data stores through Helm, upgrade the chart from v1 to v2 before upgrading Langfuse to v4.
- SDK alignment: Python SDK v5 and JS/TS SDK v6 need Langfuse v4.59.0 or later, so coordinate application releases with the platform upgrade.
- Target version: Confirm the release to pin, since the GitHub releases page lists v4.63.0 as published October 16, 2026.
Langfuse documents Docker Compose on a single VM for testing, without high availability, and Kubernetes with Helm or Terraform on AWS, Azure and GCP for production. The migration logic stays the same, but the verification and ownership differ.
- Rehearsal target: Use Compose to rehearse the upgrade on a copy of your data, then plan the production cutover on Kubernetes.
- Resource minimums: Compare the scaling guide minimums, including 2 CPU and 4 GiB for web, worker and PostgreSQL, and 2 CPU and 8 GiB for ClickHouse, against your target nodes.
- Scaling layout: On Kubernetes, plan separate scaling for web and worker containers and where stateful stores run.
- Version match: Confirm that the chart, Terraform module or Compose file matches the Langfuse version under test.
- Ownership: Confirm who operates the cluster and who signs off each rehearsal result before production.
What you need to provide
Most of the scope for a Langfuse migration is set before any installation begins. The items below are what we need from your side, and each one changes the work. Confirm them early, because a missing answer usually turns into a longer discovery phase or a change to the cutover plan. Start with access. We need cloud or data center accounts that your organization owns, with administrative roles for the platform team, so the Kubernetes or Docker host, PostgreSQL, ClickHouse, Redis or Valkey and S3-compatible blob storage can be provisioned inside your environment. Decide the target infrastructure too: a single VM is suitable only for testing, while production deployments run on Kubernetes with Helm or Terraform, so that choice sets the build.
Next, the source side. Provide an inventory of every application and service that sends traces today, including the SDK or OpenTelemetry path each one uses. Pair it with an export path from Langfuse Cloud or the current observability tool, and a list of the prompts, datasets and scores that must move. Named owners matter here: each application needs an owner who approves its cutover, and prompt content needs an owner who signs off on what is migrated and which versions stay active. Data classification and residency rules decide where traces and prompts may be stored, how long they are kept, and whether masking is required before data lands in ClickHouse. Ask your security and legal teams to answer these before the design is frozen. Finally, agree on a change window for cutover and decide whether the Enterprise license key is needed, since features such as project-level RBAC, protected prompt labels, data retention policies and audit logs depend on it.
Frequently asked questions
What drives the cost of a Langfuse migration?
Scope and data volume drive most of the cost. Four parts make up the spend: the migration design, the infrastructure you run, the instrumentation work in your applications, and the internal time your team spends on reviews and testing. Infrastructure is recurring and sized by trace volume. The Langfuse scaling guide lists minimums of 2 CPU and 4 GiB for web, worker and PostgreSQL, 1 CPU and 1.5 GiB for Redis or Valkey, and 2 CPU and 8 GiB for ClickHouse, with at least 16 GiB of ClickHouse memory for larger deployments. Ask for a quote that separates one-time project work from recurring infrastructure and support.
Can our in-house team run a Langfuse migration without a partner?
Yes, if your team has Kubernetes or Docker operations experience, PostgreSQL and ClickHouse administration skills, and time for a cutover. Langfuse publishes Docker Compose for testing on a single VM, which has no high availability, and Helm or Terraform deployments on AWS, Azure and GCP for production. The harder work is usually the planning around the install: sizing ClickHouse, deciding how to handle historic data, changing instrumentation in each application, and proving the stack holds up under load. Check whether your team can staff a planned cutover and a rollback path, beyond the install itself.
What sets the length of a self-hosted Langfuse migration?
The length depends on how many applications send traces, how much history you carry over, and how much of the target infrastructure is new. Work that often adds time includes building the Kubernetes environment, setting up PostgreSQL, ClickHouse and S3-compatible storage with backups, moving applications to new SDKs or OpenTelemetry pipelines, and running a parallel period to compare results. Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. Confirm each assumption about your environment before you accept a timeline.
Can we move historic traces from Langfuse Cloud or another tool into self-hosted Langfuse?
It depends on the source system and its export options, so confirm this before you commit to a plan. Ask Langfuse or your current vendor which data, such as traces, scores, prompts and datasets, can be exported and in what format. Some teams keep the old system as a read-only reference and send new traces to the self-hosted instance from cutover. Historic data also adds ClickHouse storage and backfill work, so decide early how much history is worth carrying into the new stack.
Do we have to backfill historic data when moving from Langfuse v3 to v4?
The v3 to v4 upgrade guide describes a backfill of historic data into the new observations-first ClickHouse data model. Whether your instance needs it depends on how much history you want to keep and how you query it. The guide advises about 3x ClickHouse disk headroom when backfilling, so size storage before you start. The upgrade also requires ClickHouse 25.12 or later (26.4 recommended), PostgreSQL 15 or later and Redis 7.0 or later. If you use Helm with bundled data stores, upgrade the chart from v1 to v2 first. Review the guide against your retention requirements.
Does the open source edition of Langfuse cover what we need?
For many teams, yes. Langfuse states that all core features and APIs are available in the MIT-licensed version without limits, and self-hosted deployments use the same codebase as Langfuse Cloud. The gaps are specific features that need an Enterprise license key, including project-level RBAC roles, protected prompt labels, data retention policies, audit logs, server-side data masking, SCIM and the instance management API. Regulated teams usually check these first. Map your access, retention and audit requirements against that list, then price the custom Self-Hosted Enterprise plan separately from infrastructure.
How DeployOpen delivers Langfuse migrations
DeployOpen plans and runs Langfuse migrations in infrastructure you control, from Langfuse Cloud or another LLM observability tool, and for the architecture changes Langfuse itself requires between major versions. Each step is agreed in writing and checked against the Langfuse version and data store requirements that apply to your environment.
How we scope
- The written scope names the source system, the Langfuse target version and the data to move, such as traces, scores and prompts.
- Scope records the ClickHouse, PostgreSQL, Redis or Valkey and blob storage choices, and which deployment method applies.
- Engagements are fixed-scope, so deliverables and timelines are agreed in writing before migration work starts.
How we build
- We stand up the target environment with Docker Compose for testing or Kubernetes with Helm or Terraform for production.
- For v2 to v3 moves, we add and validate ClickHouse alongside the existing PostgreSQL and blob storage configuration.
- For v3 to v4 moves, we check ClickHouse 25.12 or later, PostgreSQL 15 or later and Redis 7.0 or later, then plan the backfill with disk headroom.
How we hand over
- Handover covers the migration runbook, rollback steps, validation results and the configuration used in your infrastructure.
- We document the Helm chart upgrade, SDK version dependencies and instrumentation changes your teams need to make.
- Your team receives the operational notes for backups, scaling signals and the steps for future updates within a major version.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after the migration is complete.
- Post-migration support can cover monitoring of ingestion, backfill follow-up and planning the next major Langfuse upgrade.
- Confirm with DeployOpen which support level fits your environment, and whether a Langfuse Enterprise license or vendor support plan is needed.
