Langfuse

3.14.5 · active · verified Sat Feb 28

Open-source LLM observability and evaluation platform. Python SDK provides tracing via @observe decorator, OpenTelemetry integration, and a low-level client for manual trace/span management. Works with any LLM framework — not tied to LangChain. Self-hostable (Docker/Kubernetes) or cloud (EU/US regions). MAJOR VERSION NOTE: SDK was completely rewritten in v3 (released June 2025). v3 is OpenTelemetry-based with a new singleton client pattern. All v2 import paths, class names, and initialization patterns are broken in v3. pip install langfuse installs v3 as of Feb 2026.

Warnings

breaking SDK v3 (June 2025) is a complete rewrite. v2 import paths, class names, and initialization patterns all changed. The most critical breaks: (1) Langfuse() is now a singleton initializer, not a per-request client. (2) from langfuse.callback import CallbackHandler → from langfuse.langchain import CallbackHandler. (3) @observe import moved. pip install langfuse now installs v3.
Fix: Follow the official v3 migration guide at langfuse.com/docs/sdk/python/sdk-v3. Pin langfuse<3 if not ready to migrate.
breaking Self-hosted Langfuse: Python SDK v3 requires Langfuse platform version ≥ 3.125.0. Running SDK v3 against a self-hosted platform older than 3.125.0 causes silent failures or API errors.
Fix: Upgrade self-hosted platform to ≥ 3.125.0 before upgrading the Python SDK to v3. Or pin langfuse<3 until the platform is updated.
breaking LANGFUSE_BASE_URL has no universal default. EU and US cloud use different endpoints. Not setting this env var causes all API calls to fail — often with a connection timeout rather than a clear auth error.
Fix: Always set LANGFUSE_BASE_URL explicitly. EU: https://cloud.langfuse.com. US: https://us.cloud.langfuse.com. Self-hosted: your instance URL.
gotcha Traces are sent asynchronously. In short-lived scripts (CLI tools, batch jobs, test suites), the process exits before traces flush, resulting in missing data in the UI with no error.
Fix: Call langfuse.flush() at the end of scripts or register it in an atexit handler. In pytest, use the langfuse pytest fixture or add flush() to teardown.
gotcha There is a separate stub package 'langfuse-sdk' on PyPI (version 1.0.0) that is NOT the current SDK — it's an old redirect stub that predates the rename. pip install langfuse-sdk installs an abandoned package.
Fix: Always install 'langfuse' (not 'langfuse-sdk'): pip install langfuse.

Install

pip install langfuse Installs v3 (current)
pip install 'langfuse<3' Pin to v2 if migrating gradually

Imports

Langfuse / get_client (v3)
```
from langfuse import Langfuse, get_client
```
In v3, Langfuse() initializes the singleton. get_client() retrieves it anywhere in the codebase. The v2 pattern of creating a new Langfuse() per request is now wrong.
@observe decorator (v3)
```
from langfuse.decorators import observe
```
v3 decorator import path. Top-level from langfuse import observe does not exist in v3.
CallbackHandler for LangChain (v3)
```
from langfuse.langchain import CallbackHandler
```
v2 used langfuse.callback. v3 uses langfuse.langchain. Both the import path and initialization changed.

Quickstart

Langfuse() must be called once at startup to initialize the singleton. get_client() retrieves it anywhere. In v3, the client is NOT created per-request. Always call langfuse.flush() before script exit or in shutdown hooks.

import os
os.environ['LANGFUSE_SECRET_KEY'] = 'sk-lf-...'
os.environ['LANGFUSE_PUBLIC_KEY'] = 'pk-lf-...'
os.environ['LANGFUSE_BASE_URL'] = 'https://cloud.langfuse.com'  # EU

from langfuse import Langfuse, get_client
from langfuse.decorators import observe

# Initialize singleton once at startup
Langfuse()

# Verify connection
langfuse = get_client()
if langfuse.auth_check():
    print('Connected!')

# @observe traces any function
@observe()
def my_llm_call(prompt: str) -> str:
    import openai
    client = openai.OpenAI()
    response = client.chat.completions.create(
        model='gpt-4o',
        messages=[{'role': 'user', 'content': prompt}]
    )
    return response.choices[0].message.content

result = my_llm_call('Hello!')

# Flush traces before exit in short-lived scripts
langfuse.flush()

# LangChain integration (v3 import path)
from langfuse.langchain import CallbackHandler
handler = CallbackHandler()
# Pass handler to chain: chain.invoke({...}, config={'callbacks': [handler]})

view raw JSON →