How to Migrate from Langfuse to Zespan (2026 Guide)

Langfuse is a capable LLM observability platform, and for teams tracing straightforward model calls it does the job well. Teams typically start looking at Zespan when their system stops being a pipeline of LLM calls and starts being a set of agents that plan, delegate, and use tools.

This guide covers what actually changes when you move, in the order you will hit it.

Before you start: is migrating worth it for you?

Be honest about your workload. If you are tracing single-model calls and want cheap, self-hostable storage, Langfuse is a reasonable place to stay, and its MIT license is genuinely permissive.

The reasons teams do move:

• Delegation is not a first-class concept. Langfuse organizes traces around observations of LLM calls. If agent A hands off to agent B, you can represent it, but the model does not natively understand handoff as an event with its own identity, cost, and outcome.
• No built-in evaluation templates. Langfuse ships a scoring API. You define the evaluators. That is flexible, and it is also work you own forever.
• Unit-based billing counts more than you expect. The billable unit includes traces, observations and scores. A single richly-instrumented agent run can be dozens of units. Teams are often surprised by the gap between "traces per month" and their actual bill.
• Self-hosting means operating ClickHouse. The software is free. The cluster is not, in either money or attention.

If none of those bite, stay where you are. If two or more do, keep reading.

Step 1: Instrument alongside, do not rip anything out

Do not remove Langfuse first. Both platforms speak OpenTelemetry, so the safe path is to emit to both and compare.

import { zespan } from "@zespan/sdk";

zespan.init({
  apiKey: process.env.ZESPAN_API_KEY
});

That is the whole Zespan setup. It auto-patches your providers and registers framework handlers, so you do not rewrite call sites. Leave your existing Langfuse initialization exactly where it is.

If you are on raw OpenTelemetry with a custom exporter, you can point spans at both backends instead, since Zespan accepts standard OTLP.

Step 2: Understand what changes in the data model

This is the part that trips people up, so map it deliberately.

Langfuse concept	Zespan equivalent	What is different
Trace	Trace	Broadly the same root container
Observation (generation / span / event)	Span	Zespan types spans by agent semantics, not just call type
Session	Session	Comparable grouping
Score	Evaluation	Zespan runs 12 LLM-as-judge templates automatically; Langfuse scores are yours to define
—	Agent	Zespan registers agents as first-class entities on first run
—	Handoff / delegation	An explicit event with its own cost and outcome
—	Issue	Recurring failures cluster into one tracked object

The practical consequence: things you previously encoded as metadata conventions (which agent ran, who it delegated to) become native fields. You can usually delete that custom metadata after cutover.

Step 3: Replace your custom evaluators

If you built scoring functions against the Langfuse scoring API, check them against Zespan's built-in evaluator templates before porting. Most teams find that a chunk of what they hand-rolled is covered by the defaults, which run automatically on new traces with no configuration.

Port only the evaluators that are genuinely specific to your domain. Deleting bespoke eval code is usually the single biggest maintenance win of the migration.

Step 4: Run parallel for a full release cycle

Keep both exporters live and compare:

• Trace counts per service. They should track closely. Meaningful divergence usually means a call path is only instrumented in one of them.
• Cost attribution totals. Compare against your provider invoice, not against each other.
• Error and failure rates.

Resist cutting over early. The point of the parallel window is to catch the one code path nobody remembered.

Step 5: Cut over

Once the numbers agree, remove the Langfuse exporter and initialization, delete the custom metadata conventions that Zespan now models natively, and keep your Langfuse instance read-only for whatever retention window you actually need.

If you self-hosted, remember to decommission the ClickHouse cluster. That is frequently the largest single line item the migration removes.

What you should expect to gain

Concretely, after cutover:

• Delegation graphs render without you encoding parent-child relationships by hand.
• Evaluations run on every trace with no evaluator code to maintain.
• Recurring failures collapse into one Issue instead of being rediscovered trace by trace.
• Billing is flat per plan rather than unit-metered, so richer instrumentation does not increase your bill.

What you should expect to give up

Being straight about the trade-offs:

• The MIT license. Langfuse's self-hosted core is MIT. Zespan self-hosting is a Scale plan feature, not an open-source option. If vendor-neutral self-hosting is a hard requirement, that is a real reason to stay.
• A very large open-source community. Langfuse has more community integrations and public examples.

If those matter more than agent-native modelling, staying on Langfuse is a defensible call. We would rather you make that decision with the trade-off in front of you.

Next steps

• Read the Zespan vs Langfuse comparison for a capability-by-capability breakdown.
• See the LangSmith vs Langfuse vs Zespan piece if you are evaluating all three.
• Start free with 10,000 traces a month, no card required.