Migrate from Braintrust to Langfuse

Migrate from Braintrust to Langfuse: what the move involves

The move from Braintrust to self-hosted Langfuse comes down to three workstreams: export your history, re-instrument your applications, and rebuild your evaluators and CI gates. Teams usually start this work at a contract renewal, when a data residency review or a security questionnaire asks who holds the control plane, or when they want traces and datasets inside their own cloud account. The effort is driven by two things: how much historical log and experiment volume you need to carry over, and how tightly your deployment pipeline depends on Braintrust's SDK, scorers and experiment results. Your platform engineering team typically owns the infrastructure and export tooling, while ML and application owners decide which datasets, scorers and baselines matter enough to rebuild.

Langfuse is open core, and its self-hosted deployment runs the same codebase as Langfuse Cloud. Core tracing, datasets and evaluation features are part of the MIT-licensed open source version, so you do not need an Enterprise license key to run the migration. The keys apply to features such as project-level RBAC, audit logs, data retention policies and SCIM provisioning, which you should check against your governance requirements in the Langfuse license key documentation. Confirm early which of those controls your security review actually requires, because that decision determines whether you need an enterprise contract at all.

Before you change any application code, decide what counts as a successful cutover. Plan to run both systems in parallel for a defined period, compare scores on the same test cases, and map Braintrust scores and metadata fields to Langfuse equivalents so reviewers can read the results. Each re-instrumented service and each CI gate that reads evaluation output should have a named owner and a rollback path. Ask your Langfuse deployment partner or internal team to confirm the export format and API limits for your Braintrust plan at the start, since those set how long the history transfer takes.

Which Braintrust capabilities map to Langfuse, and what needs rework

This table maps each Braintrust capability to its closest self-hosted Langfuse equivalent and marks it as clean, needs rework or gap. Read the status column first, then the notes, to size the engineering work before you set a cutover date. Several Langfuse features that matter for governance sit behind an Enterprise license key, so confirm those against your own requirements before you commit.

Braintrust capability	Langfuse equivalent	Status and notes
Tracing and logs	Traces and observations via Langfuse SDKs or OpenTelemetry	Needs rework. Logging calls and span names must be re-instrumented in each application; plan for a parallel run.
Datasets	Langfuse datasets with items and linked runs	Needs rework. Export items from Braintrust as JSON or Parquet, then re-import and check IDs and metadata fields.
Experiments	Experiments run through the SDK, compared in the UI	Needs rework. Experiment history does not transfer as a native object; keep exported results as reference files.
Scores and feedback	Scores attached to traces, observations or runs	Needs rework. Map Braintrust score names and value types to Langfuse score configs before backfilling.
Prompt management	Prompt versions with labels	Needs rework. Recreate prompts and labels, then point applications at the new names. Protected prompt labels need an Enterprise key.
Online scoring	LLM-as-a-judge and custom scores on incoming traces	Needs rework. Rebuild each online evaluator and confirm its judge model, prompt and sampling rate in your environment.
AI proxy	Not provided by Langfuse	Gap. The Braintrust proxy maps to LiteLLM or Portkey, which handle routing, keys and fallbacks; Langfuse only receives the traces.
CI evaluation gates	Experiment runs triggered from CI pipelines using the SDK	Needs rework. Rebuild pass or fail thresholds and scorers in your pipeline; confirm your CI runner can reach the self-hosted endpoint.
Governance controls (RBAC roles, retention, audit logs, data masking, SCIM)	Enterprise license key features in self-hosted Langfuse	Confirm before cutover. These need an Enterprise key; check them against your access, retention and audit requirements.

What data can be exported from Braintrust and where it lands in Langfuse

Braintrust holds your history in several places that need different export paths: logs, datasets, experiments, and the scores and metadata attached to them. This section sorts each one by export method and by where it lands in Langfuse, so you know what moves as data, what you rebuild, and what to confirm in your own Braintrust organization before the contract ends.

Bulk export through the BTQL API

The BTQL API is the route for full history. Query logs, datasets and experiments in paged queries, write each page to JSON or Parquet, and record the last cursor or timestamp so an interrupted run resumes without duplicate rows. Keep each request small enough to finish inside the request timeout Braintrust documents for the API. Confirm the current limits and export permissions for your organization before you start. Parquet suits analytical reloads, while JSON keeps nested inputs and outputs intact for re-import into Langfuse.

UI export for small sets

The export button in the Braintrust UI produces JSON or CSV for a single view. It suits a small dataset, a reviewer sample or a spot check of recent traces. CSV flattens nested fields, so inputs, outputs and metadata with nested objects may need reshaping before import. Use the UI for evidence copies and sample reviews, and use the BTQL route for everything else. Check which roles can run the export in your organization, because the button depends on the same project permissions as the rest of the data.

Datasets and experiments

Datasets move as records of inputs, expected outputs and metadata, and you can load those rows into Langfuse through its API or SDK. Experiments need more care. Historical runs tie results to a specific scorer version and model configuration, so import them as archived JSON for audit and re-run the evaluations in Langfuse to produce comparable results. Store the original experiment files with checksums so the baseline you compare against stays fixed through the migration.

Scores and metadata mapping

Braintrust scores attach to spans, and Langfuse scores attach to traces or observations, so each score needs a target, a name, a data type and a value range. Write a mapping table with one row per score name, and confirm that boolean, numeric and categorical values convert without loss. Metadata keys usually become trace or observation metadata, but confirm which fields Langfuse exposes as dedicated attributes, such as user and session identifiers, and map those explicitly. Review the table with the team that owns each scorer.

Integrations to rebuild

Exports carry data, not the code that produces it. Every application that calls the Braintrust SDK needs instrumentation pointed at Langfuse, and services that send OpenTelemetry spans need their exporters redirected. If requests pass through a gateway such as LiteLLM, enable its Langfuse logging setting and turn off the Braintrust logging during the parallel run, so each request is recorded once. Test each integration against a known prompt before you retire the old path.

How the migration sequence runs from inventory to decommission

The sequence moves Braintrust work to self-hosted Langfuse in controlled stages, so each stage produces evidence that the next one can rely on. Each step has a named output, and the old platform is only decommissioned after the archives are verified.

Inventory projects, datasets, scorers and CI gates
Your team lists every Braintrust project, dataset, scorer, prompt, online scoring rule and CI job that reads from or writes to Braintrust, including the owner of each. Record which SDK version and which tracing calls each application uses, and which pipelines fail the build when a score drops. The output is a signed-off inventory with a keep, rebuild or retire decision for each item, which becomes the scope document for the rest of the sequence.
Export a pilot project from Braintrust
Using the export method the inventory supports, your team pulls logs, datasets and experiments for one low-risk project from the Braintrust API, checking page sizes against the 30-second request timeout and keeping raw JSON or Parquet files unchanged. An engineer confirms row counts and a sample of record IDs against the Braintrust UI. The output is a verified export set for the pilot project, stored in your own object storage.
Stand up the pilot on Docker Compose
Your platform team runs the Langfuse self-hosting Docker Compose setup on a single VM, which Langfuse documents for testing without high availability. Only non-production data goes here. The team re-instruments the pilot application, maps Braintrust scores and metadata to Langfuse scores and trace attributes, and imports the pilot export. The output is a working pilot where traces, scores and datasets from the pilot project appear in Langfuse and match the source records.
Deploy production Langfuse on Kubernetes with Helm
Your platform team deploys Langfuse on Kubernetes with Helm, provisioning PostgreSQL, ClickHouse, Redis or Valkey and S3-compatible storage in your own cloud or data center. Size the components against Langfuse's scaling guide, separate web and worker scaling, and configure SSO and the Enterprise license key only if a required feature needs it. The output is a production instance with documented resource settings, backup and restore tests for each data store, and a signed-off security review.
Run Braintrust and Langfuse in parallel
Teams run the same evaluation dataset and scorers through Braintrust and Langfuse for the same application versions, then compare the scores, scorer outputs and experiment results side by side. Differences are traced to scorer logic, model parameters, tokenization or data mapping, and fixed before cutover. The output is a written parity report that lists each evaluation, the accepted tolerance and the evaluators or CI gates that have been rebuilt and approved.
Cut over SDK keys and base URLs
Application owners change the Langfuse host, public and secret keys and any OpenTelemetry exporter endpoints in each service, deploying through the normal release pipeline. CI gates move to the rebuilt evaluators in Langfuse. Braintrust write access is removed from the services first, so no new data goes to the old platform. The output is a change record that lists each service, its new configuration and confirmation that traces arrive in Langfuse from production traffic.
Decommission Braintrust with verified archives
Once the parity report is signed and a retention period set by your compliance owner has passed, your team takes a final complete export of the Braintrust projects in JSON or Parquet, checks checksums and record counts, and stores the archive under your retention policy. Only after an independent check of the archive does the team remove Braintrust API keys, CI secrets and the project itself. The output is a dated archive register and a closure record that confirms no service still calls Braintrust.

How the self-hosted Langfuse stack is laid out

A self-hosted Langfuse deployment is not one service. It runs two application containers, Langfuse Web (the UI and APIs) and Langfuse Worker (asynchronous event processing), alongside PostgreSQL, ClickHouse, Redis or Valkey, and S3-compatible blob storage. Each has a different operational owner. The Braintrust export you run will land trace and score data in ClickHouse and object storage, so the sizing decisions you make now determine whether the import succeeds. The scaling guide gives minimum resources 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. Treat these as floors, not sizing for your volume, and confirm your expected ingestion with the team that will run the cluster.

Deployment shape is the first real decision. Docker Compose on a single VM is documented for testing and has no high availability, so it suits a proof of concept that runs your exported datasets in parallel with Braintrust. Production runs on Kubernetes with Helm or Terraform-based deployments on AWS, Azure and GCP. Under heavy ingestion, Langfuse recommends scaling workers on CPU load and splitting langfuse-web into separate ingestion and user interface deployments. Decide which of these your platform team will support before you start the import, because backfilling historic logs adds load that a test VM will not absorb.

Plan the version path before you install. Langfuse v3 to v4 upgrades require ClickHouse 25.12 or later (26.4 recommended), PostgreSQL 15 or later and Redis 7.0 or later, and move to an observations-first ClickHouse data model. The upgrade guide advises about 3x ClickHouse disk headroom when backfilling historic data, so size the volume for the import, not only for steady state. The license key is needed only for the Enterprise features listed in Langfuse's license key documentation, such as project-level RBAC, audit logs, data retention policies and SCIM. Core tracing, datasets and experiments run on the MIT-licensed code, so confirm which of those controls your security review requires before you buy a key.

What drives cost and duration in this migration

This table lists the factors that change the effort and recurring cost of moving from Braintrust to self-hosted Langfuse, with the reason each matters and how to keep it down. Read it before requesting a quote, because the same driver can be cheap in one environment and expensive in another. Most of the one-time effort sits in rebuilding evaluators and CI gates, while most of the recurring cost sits in ClickHouse, PostgreSQL and storage.

Driver	Why it changes cost or effort	How to keep it down
Log and trace volume	Storage and ClickHouse sizing grow with the number of traces, observations and payload size, and the export must page through all of them under the 30-second request timeout.	Export by time window and project, drop low-value debug payloads before migrating, and agree retention limits before the first load.
Dataset and experiment volume	Every dataset row and historical experiment must be exported, reshaped and reloaded, and mismatched fields cause rework.	Migrate only datasets still in use, keep a manifest of row counts per dataset, and validate a sample after each import.
Scorers and LLM-as-a-judge metrics	Each scorer must be rewritten as a Langfuse evaluator or external job, re-tested against known outputs, and its judge prompt and model choice reviewed.	Inventory scorers first, retire unused ones, and keep one reference set of outputs with expected scores to compare against.
CI gates	Each gate that reads Braintrust results needs a new query path, new thresholds and a rerun to confirm pass and fail behavior matches.	Count gates in the pipeline configuration, group those that share a score, and run old and new gates side by side until results agree.
Applications to re-instrument	Each service needs SDK or OpenTelemetry changes, environment configuration and tests, and teams with several languages multiply the work.	Start with the applications that produce the most traces, reuse one instrumentation pattern, and document the environment variables per service.
ClickHouse sizing and backfill headroom	ClickHouse is the largest self-hosted component. The Langfuse v3 to v4 guide advises about 3x ClickHouse disk headroom when backfilling historic data, and the scaling guide recommends at least 16 GiB of memory for larger deployments.	Size from the exported volume, plan backfill in batches, and ask the vendor or integrator to show disk and memory figures for your data.
PostgreSQL, Redis or Valkey and object storage	These run alongside ClickHouse and add recurring infrastructure, backups and upgrade work. Langfuse's scaling guide lists minimum resources for each.	Use managed services where your cloud policy allows, and confirm backup and restore tests are in the scope.
In-house ClickHouse and PostgreSQL skills	Without these skills, the team pays for an integrator or hires for on-call work, and upgrades like v3 to v4 need a dedicated plan.	Name an owner for each database, train on the upgrade guide, and ask whether the quote includes handover and runbooks.
Enterprise license key features	Features such as SCIM, audit logs, data retention policies and server-side masking need an Enterprise license key, which adds a recurring license cost.	List which controls your auditors need before choosing the tier, and confirm the license terms in writing.

What usually goes wrong and how to prevent it

Most failed Braintrust to Langfuse migrations fail quietly rather than loudly: a partial export, a score that means something different, or a CI gate that no longer runs. The cards below cover the risks that tend to surface after cutover, each with a check to run before the old project is switched off.

Paging past the 30-second timeout

Large BTQL export requests can hit the 30-second request timeout, and a loop that silently skips failed pages leaves gaps in logs and experiments. Use stable paging, write each page to storage with its cursor, and retry failed pages. Count rows per experiment in both systems before accepting an export as complete.

Score semantics that drift

A Braintrust score scale, direction (higher is better or lower is better) or null handling may not match the score you create in Langfuse. A pass rate of 0.8 can mean different things in each tool. Document each score's range, direction and pass threshold, then replay a sample of past runs and confirm both systems produce the same values.

CI gates that pass without running

A CI job that still points at the Braintrust project, or that finds no matching experiment, can exit green while evaluating nothing. Treat a missing result as a failure. Re-create each gate against the Langfuse dataset, then deliberately break one example and confirm the pipeline fails before you trust it.

Metadata fields lost in mapping

Fields such as model version, prompt version, user segment or environment often live in Braintrust metadata and never become Langfuse attributes. Filters and dashboards then return empty results for historical data. Build a field inventory from a sample export, map each field to a Langfuse trace, observation or score attribute, and check that filters return the same counts.

ClickHouse sizing and backfill failures

Self-hosted Langfuse runs on ClickHouse, and backfilling historic data needs spare disk. The v3 to v4 guide advises about 3x ClickHouse disk headroom for backfill, and the scaling guide recommends at least 16 GiB of memory for larger deployments. Size storage and memory before importing history, run the backfill against a copy first, and confirm the disk alert thresholds are set.

Applications still sending to the old project

Services, notebooks and scheduled jobs that still use the Braintrust SDK or an old API key keep writing logs to the retired project, so new production traces never reach Langfuse. Inventory every service that holds a Braintrust key, switch them in a staged rollout, and keep the old project read-only for a fixed period while you confirm that no new writes arrive.

How the migration differs by team size and starting point

A small team with a few Braintrust projects and a single application usually has a contained migration. The main work is exporting logs, datasets and experiments, then replacing one tracing SDK integration and rebuilding a handful of evaluators. Because Langfuse's core features and APIs are available in the MIT-licensed version without limits, a small team can often start on the open-source release and avoid an enterprise contract at the outset.

Export scope: Confirm how many projects, datasets and experiments exist, since a small set can be exported from the UI as JSON or CSV before the contract ends.
Instrumentation: Expect one application to be re-instrumented, with traces sent to a single Langfuse project.
Evaluators: Rebuild a short list of scorers and compare results against the exported Braintrust experiments before retiring them.
Deployment: Docker Compose on a single VM is documented for testing and has no high availability, so confirm whether a production target needs the Kubernetes path with Helm or Terraform.
Operations: One person may own upgrades, so check the major-version migration guides before scheduling them.

Before cutover, confirm with your team which features you actually need, since that decision determines whether a license key is required.

Questions teams ask before moving from Braintrust to Langfuse

How long does a migration from Braintrust to Langfuse take?

The duration depends on how much history you must move, how many applications send traces, and how many evaluators and CI gates you need to rebuild. Teams with a small number of applications and a short list of scorers usually finish faster than teams with many services, large Braintrust datasets and dozens of experiments they want to keep comparable. The export step is bounded by the 30-second request timeout on BTQL queries, so large logs are pulled in paged batches, which adds time. Ask any provider to break the work into discovery, data export, re-instrumentation, evaluator rebuild and parallel run, and to tie each phase to a written deliverable before work starts.

Can our team migrate from Braintrust to Langfuse without outside help?

Yes, if you have engineers who can change SDK instrumentation, a platform team that can run Kubernetes, PostgreSQL, ClickHouse, Redis or Valkey and S3-compatible storage, and time to rebuild evaluators. Langfuse's code is MIT licensed outside its enterprise directories, so the tooling itself has no license cost for the core features. The harder parts are operating the stack and reproducing scoring logic. Outside help is most useful for a fixed-scope engagement that covers hardening, backups, upgrades and documentation, so the internal team is not learning under production pressure.

What does the migration require from engineers and ML owners?

Application engineers must replace Braintrust SDK calls or OpenTelemetry exporters with Langfuse instrumentation and confirm that trace structure, user identifiers and metadata arrive correctly. ML owners must translate each Braintrust scorer, dataset and LLM-as-a-judge prompt into a Langfuse experiment or evaluator and agree on baseline runs that prove the results match. Platform engineers own the deployment, secrets, network access and backups. Plan for review time on both sides, because scores that look equivalent can differ in prompt wording, model version or the way inputs are mapped.

Does self-hosting Langfuse require an Enterprise license?

No. Langfuse states that all core features and APIs are available in the MIT-licensed open source version without limits, and self-hosted deployments use the same codebase as Langfuse Cloud. An enterprise license key is needed only for specific features, including project-level RBAC roles, protected prompt labels, data retention policies, audit logs, server-side data masking, UI customization, the org management API with SCIM and the instance management API. Check your requirements against that list. If you need SCIM provisioning or audit logs for a compliance review, budget for the Enterprise key or confirm an alternative with your auditor. Code inside the enterprise directories falls under a separate commercial license, so review the LICENSE file with legal.

What cannot be exported from Braintrust, and how do we archive it?

Export covers logs, datasets and experiments as JSON or Parquet through the BTQL API and as JSON or CSV from the UI, but some items may not come across in a usable form. Confirm with Braintrust which objects, such as scorer code, project settings, user and permission records, prompt versions and dashboard configurations, are included in your export. Keep a dated archive of every export, its query, row counts and checksums, plus a written record of each scorer's logic and the model versions used for past runs. Store that archive in encrypted object storage under your retention policy so past results remain auditable after the Braintrust contract ends.

How do we run Braintrust and Langfuse in parallel?

Run both systems on the same traffic for a defined period, sending traces from each application to Braintrust and to Langfuse, either by adding a second exporter or by routing through an OpenTelemetry Collector that fans out to both backends. Run the same evaluation dataset through each evaluator and compare scores, latency and token counts. Cut over one application at a time once the results match within a tolerance you agree in advance. Keep the Braintrust export job running until the Langfuse retention and backup routine is proven. Dual running doubles ingestion for the overlap, so confirm the cost of that period with your Braintrust account team.

What should we ask for in a fixed-scope quote for this migration?

Ask for a written scope that lists the applications to re-instrument, the number of datasets, experiments and evaluators to rebuild, and the environments to deploy, such as a single VM for testing or Kubernetes with Helm or Terraform for production. Require the quote to state who operates ClickHouse, PostgreSQL, Redis or Valkey and object storage, what backup and restore testing is included, and how upgrades will be handled, including the v3 to v4 guide's ClickHouse 25.12 or later requirement. Ask which Langfuse Enterprise features are in scope, what acceptance tests prove parity, and what documentation and handover sessions you receive. DeployOpen provides a fixed-scope quote from this written scope, and it does not publish a price list.

What drives the cost of moving from Braintrust to Langfuse?

Cost has two parts. The one-time work covers export, instrumentation changes, evaluator rebuilds, parallel testing and hardening. The recurring part covers infrastructure and operations: compute and storage for Langfuse Web, Worker, PostgreSQL, ClickHouse, Redis or Valkey and object storage, plus staff time for upgrades, backups and monitoring. Costs rise with trace volume, the number of applications, retention length and the need for high availability. Your Braintrust bill also changes during the parallel run. Request an itemized quote that separates one-time engagement fees from ongoing infrastructure and support, and ask which items you would pay to a cloud provider rather than to DeployOpen.

How DeployOpen scopes, runs and supports this migration

DeployOpen is a Chainscore Labs company that plans, implements, hardens and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For a move from Braintrust to a self-hosted Langfuse, we start with a written scope that names the log, dataset and experiment exports, the score mappings and the CI gates to rebuild.

How we scope

Inventory the Braintrust projects, logs, datasets, experiments and scorers that must move, and record which ones are still in active use
Agree in writing which data exports, SDK or OpenTelemetry changes, evaluator rebuilds and CI gate changes are included in the fixed scope
Confirm where the Langfuse deployment will run, including the ClickHouse, PostgreSQL, Redis or Valkey and S3-compatible storage you will operate

How we build

Deploy self-hosted Langfuse with Helm or Terraform in your environment, sized against the published minimum resources for web, worker and ClickHouse
Export Braintrust data through BTQL in paged requests that stay under the 30-second timeout, then load it into Langfuse and verify record counts
Map Braintrust scores and metadata to Langfuse equivalents, re-instrument applications, and rebuild evaluators and CI gates with tests that compare results

How we hand over

Document the deployment, configuration, migration runbook, score mapping tables and the parallel-run results that justified cutover
Walk your platform, security and evaluation teams through operating Langfuse, including upgrade paths such as the documented v3 to v4 guide
Hand over the Braintrust decommissioning checklist, including what to verify before deleting the old project and retaining exported data

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover, scoped in writing
Plan Langfuse upgrades and backups as recurring work, so the ClickHouse, PostgreSQL and storage operations have a named owner
Ask for a quote built from the written scope, which states the one-time migration work separately from any recurring support

Migrate from Braintrust to Langfuse