Python v2 → v3

If you are on Python SDK v2, we recommend upgrading directly to v4 (the latest major). See the Python v3 → v4 migration guide. The v2 → v3 changes below still apply — complete them first, then follow the v3 → v4 guide.

The Python SDK v3 introduces significant improvements and changes compared to the legacy v2 SDK. It is not fully backward compatible. This comprehensive guide will help you migrate based on your current integration.

You can find a snapshot of the v2 SDK documentation here.

Core Changes to SDK v2:

• OpenTelemetry Foundation: v3 is built on OpenTelemetry standards
• Trace Input/Output: Now derived from root observation by default
• Trace Attributes (user_id, session_id, etc.) Can be set via enclosing spans OR directly on integrations using metadata fields (OpenAI call, Langchain invocation)
• Context Management: Automatic OTEL context propagation

Migration Path by Integration Type

@observe Decorator Users

v2 Pattern:

from langfuse.decorators import langfuse_context, observe

@observe()
def my_function():
    # This was the trace
    langfuse_context.update_current_trace(user_id="user_123")
    return "result"

v3 Migration:

from langfuse import observe, get_client # new import

@observe()
def my_function():
    # This is now the root span, not the trace
    langfuse = get_client()

# Update trace explicitly
    langfuse.update_current_trace(user_id="user_123")
    return "result"

OpenAI Integration

v2 Pattern:

from langfuse.openai import openai

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    # Trace attributes directly on the call
    user_id="user_123",
    session_id="session_456",
    tags=["chat"],
    metadata={"source": "app"}
)

v3 Migration: If you do not set additional trace attributes, no changes are needed. If you set additional trace attributes, you have two options:

Option 1: Use metadata fields (simplest migration):

from langfuse.openai import openai

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    metadata={
        "langfuse_user_id": "user_123",
        "langfuse_session_id": "session_456",
        "langfuse_tags": ["chat"],
        "source": "app"  # Regular metadata still works
    }
)

Option 2: Use enclosing span (for more control):

from langfuse import get_client, propagate_attributes
from langfuse.openai import openai

langfuse = get_client()

with langfuse.start_as_current_observation(as_type="span", name="chat-request") as span:

with propagate_attributes(
        user_id="user_123",
        session_id="session_456",
        tags=["chat"],
    ):

response = openai.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Hello"}],
            metadata={"source": "app"}
        )

# Set trace input and output explicitly
        span.update_trace(
            output={"response": response.choices[0].message.content},
            input={"query": "Hello"},
        )

Key Migration Checklist

1. Update Imports:
   • Use from langfuse import get_client to access global client instance configured via environment variables
   • Use from langfuse import Langfuse to create a new client instance configured via constructor parameters
   • Use from langfuse import observe to import the observe decorator
   • Update integration imports: from langfuse.langchain import CallbackHandler
2. Trace Attributes Pattern:
   • Option 1: Use metadata fields (langfuse_user_id, langfuse_session_id, langfuse_tags) directly in integration calls
   • Option 2: Move user_id, session_id, tags to propagate_attributes()
3. Trace Input/Output:
   • Critical for LLM-as-a-judge: Explicitly set trace input/output
   • Don't rely on automatic derivation from root observation if you need specific values
4. Context Managers:
   • Replace manual langfuse.trace(), trace.span() with context managers if you want to use them
   • Use with langfuse.start_as_current_observation() instead
5. LlamaIndex Migration:
   • Replace Langfuse callback with third-party OTEL instrumentation
   • Install: pip install openinference-instrumentation-llama-index
6. ID Management:
   • No Custom Observation IDs: v3 uses W3C Trace Context standard - you cannot set custom observation IDs
   • Trace ID Format: Must be 32-character lowercase hexadecimal (16 bytes)
   • External ID Correlation: Use Langfuse.create_trace_id(seed=external_id) to generate deterministic trace IDs from external systems
7. Initialization:
   • Replace constructor parameters:
     • enabled → tracing_enabled
     • threads → media_upload_thread_count
8. Datasets
   • The link method on the dataset item objects has been replaced by a context manager that can be accessed via the run method on the dataset items. This is a higher-level abstraction that manages trace creation and linking of the dataset item with the resulting trace.

See the datasets documentation for more details.

Future support for v2

We will continue to support the v2 SDK for the foreseeable future with critical bug fixes and security patches. We will not be adding any new features to the v2 SDK. You can find a snapshot of the v2 SDK documentation here.