Get Started with Langfuse Tracing

This quickstart helps you to integrate your LLM application with Langfuse Tracing. If you are looking for other features, see the overview.

Create new project in Langfuse

Create Langfuse account or self-host
Create a new project
Create new API credentials in the project settings

Integrate with Langfuse

The @observe() decorator is the recommended way to get started with Langfuse. It automatically captures traces with minimal code changes and works with any LLM provider.

pip install langfuse

.env

LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
# 🇪🇺 EU region
LANGFUSE_HOST="https://cloud.langfuse.com"
# 🇺🇸 US region
# LANGFUSE_HOST="https://us.cloud.langfuse.com"

main.py

from langfuse import observe, get_client
from langfuse.openai import openai # OpenAI integration
 
@observe()
def story():
    return openai.chat.completions.create(
        model="gpt-4o",
        messages=[
          {"role": "system", "content": "You are a great storyteller."},
          {"role": "user", "content": "Once upon a time in a galaxy far, far away..."}
        ],
    ).choices[0].message.content
 
@observe()
def main():
    return story()
 
main()

For more advanced use cases with manual control, see the Python SDK v3 documentation.

Recommended approach: Use third-party, OTEL-based instrumentation packages for automatic tracing with popular LLM providers and frameworks. The Langfuse SDK will pick up emitted spans and process them accordingly.

.env

LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
# 🇪🇺 EU region
LANGFUSE_HOST="https://cloud.langfuse.com"
# 🇺🇸 US region
# LANGFUSE_HOST="https://us.cloud.langfuse.com"

In this example, we are using the opentelemetry-instrumentation-anthropic library.

from langfuse import get_client
 
from anthropic import Anthropic
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
 
 
# This will automatically emit OTEL-spans for all Anthropic API calls
AnthropicInstrumentor().instrument()
 
# Initialize Langfuse
langfuse = get_client()
 
# This will be traced as a Langfuse generation nested under the current span
message = Anthropic().messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
 
print(message.content)

Alternative: Manual tracing with @observe(as_type="generation") for custom implementations. See decorator documentation for details.

npm i langfuse
# or
yarn add langfuse
 
# Node.js < 18
npm i langfuse-node
 
# Deno
import { Langfuse } from "https://esm.sh/langfuse"

.env

LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
# 🇪🇺 EU region
LANGFUSE_BASEURL="https://cloud.langfuse.com"
# 🇺🇸 US region
# LANGFUSE_BASEURL="https://us.cloud.langfuse.com"

Example usage, most of the parameters are optional and depend on the use case. For more information, see the JS/TS SDK docs or end-to-end example notebook.

server.ts

import { Langfuse } from "langfuse";
 
const langfuse = new Langfuse();
 
const trace = langfuse.trace({
  name: "my-AI-application-endpoint",
});
 
// Example generation creation
const generation = trace.generation({
  name: "chat-completion",
  model: "gpt-4o",
  modelParameters: {
    temperature: 0.9,
    maxTokens: 2000,
  },
  input: messages,
});
 
// Application code
const chatCompletion = await llm.respond(prompt);
 
// End generation - sets endTime
generation.end({
  output: chatCompletion,
});

The integration is a drop-in replacement for the OpenAI Python SDK. By changing the import, Langfuse will capture all LLM calls and send them to Langfuse asynchronously (for Azure OpenAI, use from langfuse.openai import AzureOpenAI).

pip install langfuse

.env

LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
# 🇪🇺 EU region
LANGFUSE_HOST="https://cloud.langfuse.com"
# 🇺🇸 US region
# LANGFUSE_HOST="https://us.cloud.langfuse.com"

.py

- import openai
+ from langfuse.openai import openai
 
Alternative imports:
+ from langfuse.openai import OpenAI, AsyncOpenAI, AzureOpenAI, AsyncAzureOpenAI

Use the OpenAI SDK as you would normally.

from langfuse.openai import openai
 
completion = openai.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a very accurate calculator."},
        {"role": "user", "content": "1 + 1 = "}
    ],
)

.env

LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
# 🇪🇺 EU region
LANGFUSE_BASEURL="https://cloud.langfuse.com"
# 🇺🇸 US region
# LANGFUSE_BASEURL="https://us.cloud.langfuse.com"

With your environment configured, call OpenAI SDK methods as usual from the wrapped client.

import OpenAI from "openai";
import { observeOpenAI } from "langfuse";
 
const openai = observeOpenAI(new OpenAI());
 
const res = await openai.chat.completions.create({
  messages: [{ role: "system", content: "Tell me a story about a dog." }],
  model: "gpt-4o",
  max_tokens: 300,
});

The integration uses the Langchain callback system. Note: Trace attributes must be set on an enclosing span.

from langfuse.callback import CallbackHandler
 
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
 
langfuse_handler = CallbackHandler()
 
llm = ChatOpenAI(model_name="gpt-4o")
prompt = ChatPromptTemplate.from_template("Tell me a joke about {topic}")
chain = prompt | llm
 
response = chain.invoke({"topic": "cats"}, config={"callbacks": [langfuse_handler]})

For more details, see the Langchain integration docs.

The integration uses the Langchain callback system to automatically capture detailed traces of your Langchain executions.

npm i langfuse-langchain

import { CallbackHandler } from "langfuse-langchain";
// Deno: import CallbackHandler from "https://esm.sh/langfuse-langchain";
 
const langfuseHandler = new CallbackHandler({
  secretKey: "sk-lf-...",
  publicKey: "pk-lf-...",
  baseUrl: "https://cloud.langfuse.com", // 🇪🇺 EU region
  // baseUrl: "https://us.cloud.langfuse.com", // 🇺🇸 US region
});
 
// Your Langchain code
 
// Add Langfuse handler as callback to `run` or `invoke`
await chain.invoke({ input: "<user_input>" }, { callbacks: [langfuseHandler] });

For more details, see the Langchain integration docs.

Use third-party OTEL-based instrumentation for LlamaIndex. In this example, we use the openinference-instrumentation-llama-index library.

pip install langfuse llama-index openinference-instrumentation-llama-index

.env

LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
# 🇪🇺 EU region
LANGFUSE_HOST="https://cloud.langfuse.com"
# 🇺🇸 US region
# LANGFUSE_HOST="https://us.cloud.langfuse.com"

from langfuse import get_client
 
from llama_index.core.llms.openai import OpenAI
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
 
# Enable OTEL-based instrumentation
LlamaIndexInstrumentor().instrument()
 
# Initialize Langfuse
langfuse = get_client()
 
response = OpenAI(model="gpt-4o").complete("Hello, world!")

Use the agent mode of your editor to integrate Langfuse into your existing codebase.

🤖

This might or might not work very well (depending on your code base). Please share any feedback or issues on GitHub.

Install the Langfuse Docs MCP Server (optional)

The agent will use the Langfuse searchLangfuseDocs tool (docs) to find the correct documentation for the integration you are looking for. This is optional, alternatively the agent can use its native websearch capabilities.

Add Langfuse Docs MCP to Cursor via the one-click install:

Install MCP Server in Cursor

Manual configuration

Add the following to your mcp.json:

{
  "mcpServers": {
    "langfuse-docs": {
      "url": "https://langfuse.com/api/mcp"
    }
  }
}

Add Langfuse Docs MCP to Copilot in VSCode via the following steps:

Open Command Palette (⌘+Shift+P)
Open “MCP: Add Server…”
Select HTTP
Paste https://langfuse.com/api/mcp
Select name (e.g. langfuse-docs) and whether to save in user or workspace settings
You’re all set! The MCP server is now available in Agent mode

Add Langfuse Docs MCP to Claude Code via the CLI:

claude mcp add \
  --transport http \
  langfuse-docs \
  https://langfuse.com/api/mcp \
  --scope user

Manual configuration

Alternatively, add the following to your settings file:

User scope: ~/.claude/settings.json
Project scope: your-repo/.claude/settings.json
Local scope: your-repo/.claude/settings.local.json

{
  "mcpServers": {
    "langfuse-docs": {
      "transportType": "http",
      "url": "https://langfuse.com/api/mcp",
      "verifySsl": true
    }
  }
}

One-liner JSON import

claude mcp add-json langfuse-docs \
  '{"type":"http","url":"https://langfuse.com/api/mcp"}'

Once added, start a Claude Code session (claude) and type /mcp to confirm the connection.

Add Langfuse Docs MCP to Windsurf via the following steps:

Open Command Palette (⌘+Shift+P)
Open “MCP Configuration Panel”
Select Add custom server

Add the following configuration:

{
  "mcpServers": {
    "langfuse-docs": {
      "command": "npx",
      "args": ["mcp-remote", "https://langfuse.com/api/mcp"]
    }
  }
}

Langfuse uses the streamableHttp protocol to communicate with the MCP server. This is supported by most clients.

{
  "mcpServers": {
    "langfuse-docs": {
      "url": "https://langfuse.com/api/mcp"
    }
  }
}

If you use a client that does not support streamableHttp (e.g. Windsurf), you can use the mcp-remote command as a local proxy.

{
  "mcpServers": {
    "langfuse-docs": {
      "command": "npx",
      "args": ["mcp-remote", "https://langfuse.com/api/mcp"]
    }
  }
}

Run Agent

Copy and execute the following prompt in the agent mode of your editor:

View prompt

# Langfuse Agentic Onboarding

## Goals

Your goal is to help me integrate Langfuse tracing into my codebase.

## Rules

Before you begin, you must understand these three fundamental rules:

1. Do Not Change Business Logic: You are strictly forbidden from changing, refactoring, or altering any of my existing code's logic. Your only task is to add the necessary code for Langfuse integration, such as decorators, imports, handlers, and environment variable initializations.
2. Adhere to the Workflow: You must follow the step-by-step workflow outlined below in the exact sequence.
3. If available, use the langfuse-docs MCP server and the `searchLangfuseDocs` tool to retrieve information from the Langfuse docs. If it is not available, please use your websearch capabilities to find the information.

## Integration Workflow

### Step 1: Language and Compatibility Check

First, analyze the codebase to identify the primary programming language.

- If the language is Python or JavaScript/TypeScript, proceed to Step 2.
- If the language is not Python or JavaScript/TypeScript, you must stop immediately. Inform me that the codebase is currently unsupported for this AI-based setup, and do not proceed further.

### Step 2: Codebase Discovery & Entrypoint Confirmation

Once you have confirmed the language is compatible, explore the entire codebase to understand its purpose.

- Identify all files and functions that contain LLM calls or are likely candidates for tracing.
- Present this list of files and function names to me.
- If you are unclear about the main entry point of the application (e.g., the primary API route or the main script to execute), you must ask me for confirmation on which parts are most critical to trace before proceeding to the next step.

### Step 3: Discover Available Integrations

After I confirm the files and entry points, get a list of available integrations from the Langfuse docs by calling the `getLangfuseOverview` tool.

### Step 4: Analyze Confirmed Files for Technologies

Based on the files we confirmed in Step 2, perform a deeper analysis to identify the specific LLM frameworks or SDKs being used (e.g., OpenAI SDK, LangChain, LlamaIndex, Anthropic SDK, etc.). Search the Langfuse docs for the integration instructions for these frameworks via the `searchLangfuseDocs` tool.

If you are unsure, repeatedly query the Langfuse docs via the `searchLangfuseDocs` tool.

### Step 5: Propose a Development Plan

Before you write or modify a single line of code, you must present me with a clear, step-by-step development plan. This plan must include:

- The Langfuse package(s) you will install.
- The files you intend to modify.
- The specific code changes you will make, showing the exact additions.
- Instructions on where I will need to add my Langfuse API keys after your work is done.

I will review this plan and give you my approval before you proceed.

### Step 6: Implement the Integration

Once I approve your plan, execute it. First, you must use your terminal access to run the necessary package installation command (e.g., pip install langfuse, npm install langfuse) yourself. After the installation is successful, modify the code exactly as described in the plan.

When done, please review the code changes. The goal here is to keep the integration as simple as possible.

### Step 7: Request User Review and Wait

After you have made all the changes, notify me that your work is complete. Explicitly ask me to run the application and confirm that everything is working correctly and that you can make changes/improvements if needed.

### Step 8: Debug and Fix if Necessary

If I report that something is not working correctly, analyze my feedback. Use the knowledge you have to debug the issue. If required, re-crawl the relevant Langfuse documentation to find a solution, propose a fix to me, and then implement it.

✅

Done. After running your application, visit the Langfuse interface to view the trace you just created.

All Langfuse platform features

This was a very brief introduction to get started with Langfuse. Explore all Langfuse platform features in detail.

Develop

Tracing Prompt Management Export & Fine-tuning

Monitor

Analytics Model Usage & Cost Evaluation

Test

Datasets

References

Python Decorator Python SDK (v3)JS/TS SDK OpenAI SDK 🦜🔗Langchain 🦙LlamaIndex API reference Flowise Langflow Litellm

FAQ

Data Model Sessions

Was this page helpful?

Support