Skip to main content

Getting Started with Langfuse

This guide walks you through setting up Langfuse observability for your AI applications. By the end, you'll have traces flowing from your code to the Langfuse dashboard.

Overview​

Prerequisites​

  • BMW WebEAM account — For dashboard access
  • Python 3.12 — For running your application

Step 1: Create or Manage a Langfuse Project​

Please open a service request to create a new Langfuse Project, or to manage users and roles on an existing one.

You Become the Admin

When you submit the project request, you automatically become the Project Admin. This gives you full control over the project.

RolePermissions
AdminCreate API keys, invite members, promote others to Admin, manage settings
MemberView traces, create generations, cannot manage settings
ViewerRead-only access to traces and dashboards

Step 2: Access Langfuse & Create API Keys​

Login to Langfuse​

Navigate to the Langfuse dashboard and sign in with your BMW WebEAM credentials:

RegionEnvironmentURL
ROWProductionlangfuse.caip.bmw.cloud
CNProductionlangfuse.caip.bmwchina.cloud

Langfuse Login

Create API Keys (Admin Only)​

As a project admin, you can create API keys for your application:

  1. Navigate to Settings → API Keys
  2. Click Create new API key
  3. Copy both keys immediately:

Create API Key

Secret Key Shown Once

The secret key is displayed only at creation time. Store it securely in a password manager or secret vault. Never commit it to version control.

Add Team Members (Admin Only)​

To give your team access to view traces:

  1. Go to Settings → Members
  2. Click Invite Member
  3. Enter their BMW email address
  4. Select their role (Admin, Member, or Viewer)

Step 3: Configure Your Application​

Add Langfuse credentials to your environment:

Langfuse observability is enabled by default in the SDK. You only need to set CAIP_LANGFUSE_OBSERVABILITY=false if you want to disable tracing.

.env
# Langfuse Configuration
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
# Langfuse server URL
# ROW
LANGFUSE_HOST=https://langfuse.caip.bmw.cloud

# CN
# LANGFUSE_HOST=https://langfuse.caip.bmwchina.cloud
 
# Environment tag (appears in Langfuse UI for filtering)
LANGFUSE_ENV=prod
VariableDescription
LANGFUSE_PUBLIC_KEYYour project's public key (starts with pk-lf-)
LANGFUSE_SECRET_KEYYour project's secret key (starts with sk-lf-)
LANGFUSE_HOSTLangfuse server URL
LANGFUSE_ENVEnvironment tag for filtering (e.g., test, prod)
LANGFUSE_DEBUGSet to true for verbose trace logging (see Troubleshooting)

To disable observability explicitly:

.env
CAIP_LANGFUSE_OBSERVABILITY=false
Security Best Practice

Use environment variables or a secrets manager. Never hardcode credentials in your code.

Step 4: Choose Your Integration Method​

Langfuse can be integrated in multiple ways, depending on your use case:

Best for: Building AI agents with the CAIP platform

This is the recommended approach. The CAIP Agents SDK provides automatic tracing for all agent operations, plus the @observe decorator for custom instrumentation.

For CAIP agent routing, you can optionally set CAIP_REGION to ROW or CN. If not set, the SDK defaults to ROW.

Install​

pip install caip-agents-sdk --upgrade \
  --index-url https://packages.orbit.bmwgroup.net/artifactory/api/pypi/connected-ai-platform-pypi-local-public/simple \
  --extra-index-url https://pypi.org/simple

Example: Agent with Automatic Tracing​

agent_with_tracing.py
import asyncio, os
from caip_agents_sdk import CAIPAgentsClient
from caip_agents_sdk.observability import observe, propagate_attributes, flush
 
async def main():
    # Initialize client - Langfuse is auto-configured from env vars
    client = CAIPAgentsClient()
    
    # Create agent - all LLM calls are automatically traced
    agent = client.create_agent(
        framework="pydantic_ai",
        agent_id=os.getenv("CAIP_AGENT_ID"),
    )
    await agent.initialize()
    thread = await client.create_thread(
        agent_id=os.getenv("CAIP_AGENT_ID"),
        thread_data={"title": "Hello World", "status": "open"},
    )
    agent.thread_id = thread.threadId
    # Add user context for trace filtering
    with propagate_attributes(
        user_id="user_123",
        session_id="session_456",
        tags=["production", "chat-bot"]
    ):
        # This entire operation is traced automatically
        result = await agent.run("What is the weather in Munich?")
        print(result.output)
    
    # Flush traces before exit
    flush()
 
if __name__ == "__main__":
    asyncio.run(main())

What gets traced automatically:

  • Agent initialization
  • LLM calls (with token counts and costs) — named caip.pydantic_ai.run, caip.pydantic_ai.stream, or caip.pydantic_ai.iter
  • Tool invocations — named caip.tool.{tool_name}
  • Message persistence — named caip.api.{endpoint}

Step 5: View Your Traces​

After running your application, open the Langfuse dashboard to see your traces:

  1. Navigate to Traces in the left sidebar
  2. Your traces appear in real-time (may take a few seconds)
  3. Click any trace to see the detailed execution tree

Traces List

What You'll See​

ColumnDescription
TimestampWhen the trace started
NameThe root operation name
UserUser ID (if set via propagate_attributes)
LatencyTotal execution time
TokensInput + output token count
CostEstimated cost based on model pricing

Step 6: Filter by Environment​

Use the LANGFUSE_ENV variable to tag traces by environment:

# Tag your traces with environment name
LANGFUSE_ENV=prod

Then filter traces in the dashboard:

Environment Filter

This makes it easy to filter traces by environment when you have multiple deployments.

Troubleshooting​

Traces Not Appearing​

IssueSolution
Missing credentialsVerify LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY are set
Tracing disabled by configRemove CAIP_LANGFUSE_OBSERVABILITY=false from your .env
Wrong host URLCheck LANGFUSE_HOST matches your environment
No flush before exitCall flush() before your program ends

Debug Mode​

Enable verbose debug logging to see every span open/close and generation update:

.env
LANGFUSE_DEBUG=true

When enabled, the SDK logs detailed trace activity to your console:

🔍 Langfuse debug mode ENABLED — verbose trace logging active
▶ GENERATION OPEN: caip.pydantic_ai.run [model=gpt-4o]
⟳ GENERATION UPDATE: caip.pydantic_ai.run | keys=['input', 'output', 'usage_details']
◼ GENERATION CLOSE: caip.pydantic_ai.run [model=gpt-4o] status=OK

This is useful for verifying that traces are being created correctly during local development.

Next Steps​