Switch from Langfuse V3 to Confident AI

Overview

Langfuse Python SDK v3 already runs on OpenTelemetry. confident-trace speaks the same protocol, so the switch is an exporter swap: replace the Langfuse client wrapper with init(), rename the decorator, move get_client() updates onto update_trace(), and keep every span you emit today. Langfuse TypeScript SDK v3 still sends traces through the Langfuse ingestion API, so in TypeScript the switch replaces the Langfuse client with init(), span and updateTrace().

In this guide, you will:

• Pick a migration method: one copyable prompt for your coding agent, manual, or, in Python, adding a Confident AI exporter to the OpenTelemetry setup Langfuse already runs.
• Install confident-trace and replace the Langfuse keys with one CONFIDENT_API_KEY.
• Replace the client wrapper with init() so auto instrumentation emits the spans.
• Rename @observe to @span so every trace carries a name, an input and an output.
• Move trace and span updates onto update_trace() and update_span() so users, sessions, tags and metadata stay on your traces.
• See what changes once the traces land in Confident AI: evals on every trace, datasets curated from production, alerts when quality drops.

Prerequisites

• A Project API Key, CONFIDENT_API_KEY (for example confident_us_proj_...). Retrieve yours here.
• Python 3.10+ for the Python SDK, or Node.js 22+ for the TypeScript SDK.
• Your existing Langfuse setup on SDK v3: Python langfuse>=3,<4 (run pip show langfuse) or TypeScript langfuse@3 (run npm ls langfuse). The before snippets below follow the Langfuse v3 SDKs, last released as Python 3.15.0 and TypeScript 3.39.2.

Choose a Migration Method

Switch in One Prompt

Give the prompt below to your coding assistant, such as Claude Code, Cursor or Codex, from the root of your repository. It finds your Langfuse integration, confirms the SDK version, makes the changes from this guide, and tells you what still needs your hands. Review the diff before you merge it.

Migrate this codebase from Langfuse to Confident AI using confident-trace.

1. Find every Langfuse integration: imports of langfuse, @observe, get_client(), start_as_current_span(), langfuse.openai, observeOpenAI, new Langfuse() clients, langfuse.trace(), trace.span(), trace.generation(), the Langfuse CallbackHandler, and LANGFUSE_* environment variables.
2. Confirm the installed Langfuse SDK version with pip show langfuse or npm ls langfuse. This migration is for Langfuse SDK v3. If the major version is different, stop and tell me which version you found.
3. Make the changes from https://www.confident-ai.com/docs/guides/migrate-to-langfuse-alternative-v3:
   - install confident-trace and call init() once at startup
   - replace langfuse.openai and observeOpenAI with the plain OpenAI client
   - rename @observe() to @span, start_as_current_span() to span(...), and trace.span() to span in TypeScript
   - move update_current_trace() and langfuse.trace() fields onto update_trace() (updateTrace() in TypeScript), with session_id as thread_id (threadId)
   - move update_current_span(), update_current_generation() and span.update() onto update_span() (updateSpan())
   - keep generations for model calls auto instrumentation does not cover as LLM spans with update_span()
   - remove the Langfuse CallbackHandler from LangChain callbacks
   - replace the LANGFUSE_* variables with CONFIDENT_API_KEY, and the Langfuse flush calls with flush() / shutdown()
4. Preserve existing tracing behavior where possible: the same span names, nesting, inputs, outputs, users, sessions, tags and metadata.
5. Do not delete Langfuse prompt, dataset or score calls. List them for me instead.
6. When you are done, summarize every change and list anything that needs manual configuration, such as setting CONFIDENT_API_KEY, the EU endpoint, or model calls you could not map.

Switch Manually

1. Install confident-trace

   One package. Provider SDKs stay optional peers. CONFIDENT_API_KEY replaces the Langfuse public key, secret key and host. For the EU region, also set CONFIDENT_OTEL_ENDPOINT=https://eu.otel.confident-ai.com/v1/traces.

   pip uninstall langfuse
   pip install confident-trace
   export CONFIDENT_API_KEY=...
   # replaces LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST

2. Replace the client wrapper with init()

   Drop the Langfuse wrapper around OpenAI. Auto instrumentation emits the spans from the plain client.

   PythonTypeScript (alpha)

   from langfuse.openai import openai
   
   response = openai.chat.completions.create(
       model="gpt-4.1-mini",
       messages=[{"role": "user", "content": "Hello"}],
   )

3. Rename @observe to @span

   Same shape. Return values and exceptions pass through. In TypeScript, Langfuse v3 has no decorator, so a trace.span() you opened and ended by hand becomes a span function.

   PythonTypeScript (alpha)

   from langfuse import observe
   
   @observe()
   def answer(question: str) -> str:
       return openai.chat.completions.create(
           model="gpt-4.1-mini",
           messages=[{"role": "user", "content": question}],
       ).choices[0].message.content

   with langfuse.start_as_current_span(name="...") becomes with span("..."):.

4. Move trace and span updates onto update_trace() and update_span()

   get_client().update_current_trace() becomes update_trace(), and session_id becomes thread_id. update_current_span() and update_current_generation() become update_span(). In TypeScript, the fields you passed to langfuse.trace() move onto updateTrace(), and span.update() becomes updateSpan().

   PythonTypeScript (alpha)

   from langfuse import get_client, observe
   
   langfuse = get_client()
   
   @observe()
   def support_chat(question: str) -> str:
       langfuse.update_current_trace(
           name="support-chat",
           user_id="user-7",
           session_id="session-42",
           tags=["support"],
           metadata={"plan": "enterprise"},
       )
       langfuse.update_current_span(metadata={"region": "EU"})
       return answer(question)

   A Python function decorated with @observe(as_type="generation"), or a TypeScript generation, around an OpenAI call is now redundant: auto instrumentation records the same model span. For model calls it does not cover, use an LLM span (@span(type="llm"), or withSpan({ type: "llm" }, fn) in TypeScript) and pass the model and token counts to update_span() (updateSpan()) where you passed model and usage_details (usageDetails) before. For LangChain, remove the Langfuse CallbackHandler (from langfuse.langchain in Python, langfuse-langchain in TypeScript) from your callbacks. init() instruments LangChain directly.

Run your app once. The trace appears in your project's Observatory within seconds. If it does not, check that CONFIDENT_API_KEY is set in the same process and that the app flushes before it exits. flush() from confident-trace replaces get_client().flush() in Python, and await tracing.shutdown() replaces await langfuse.shutdownAsync() in TypeScript.

Field Mapping

Switch Using OpenTelemetry

Langfuse Python SDK v3 creates OpenTelemetry spans on the global tracer provider. Add a Confident AI exporter to that provider and every span Langfuse emits reaches Confident AI as well. Your @observe decorators, langfuse.openai and get_client() calls stay as they are. In TypeScript, Langfuse SDK v3 is not OpenTelemetry, so use Switch Manually instead.

1. Add the Confident AI exporter

   The OTLP exporter already ships with Langfuse v3, so there is nothing to install. Keep LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY set: without them, the Langfuse SDK creates no spans at all.

   import os
   
   from langfuse import get_client
   from opentelemetry import trace
   from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
   from opentelemetry.sdk.trace.export import BatchSpanProcessor
   
   langfuse = get_client()
   
   trace.get_tracer_provider().add_span_processor(
       BatchSpanProcessor(
           OTLPSpanExporter(
               endpoint="https://otel.confident-ai.com/v1/traces",
               headers={"x-confident-api-key": os.environ["CONFIDENT_API_KEY"]},
           )
       )
   )

   For the EU region, use https://eu.otel.confident-ai.com/v1/traces. If you pass your own tracer_provider to Langfuse(), add the processor to that provider instead.

2. Stop sending to Langfuse when you cut over

   While you compare, both platforms receive every trace. When you are ready, block the Langfuse SDK's own scope from the Langfuse exporter. Spans are still created and still reach Confident AI.

   from langfuse import Langfuse
   
   langfuse = Langfuse(blocked_instrumentation_scopes=["langfuse-sdk"])

Run your app once. The trace appears in your project's Observatory within seconds.

What Carries Over

Every span on the provider is exported, including spans from other instrumentations such as HTTP clients. The Langfuse SDK stays in your app. To replace it with confident-trace and its auto instrumentation later, switch manually or with a coding agent.

What Changes

Tracing is where you start. Evals are where it pays off. Every trace gets a score. Low scores become dataset rows. Dataset rows become regression tests. Your next release ships against real production failures.

Migration Questions

Related

Last updated on October 5, 2026