LangGraph SDK Quick Start - Fiddler Documentation

Instrument your LangGraph or LangChain application with the Fiddler LangGraph SDK in under 10 minutes.

What You’ll Learn

By completing this quick start, you’ll:

Set up monitoring for a LangGraph or LangChain application
Send your first traces to Fiddler
Verify data collection in the Fiddler dashboard
Understand basic conversation tracking

Prerequisites

Before you begin, ensure you have:

Python 3.10 or higher (up to Python 3.13)
Valid Fiddler account with access to your instance
A LangGraph or LangChain application ready for instrumentation
Network connectivity to your Fiddler instance

Version Compatibility

Supported Python Versions:

Python 3.10, 3.11, 3.12, or 3.13

Framework Compatibility:

LangGraph/LangChain: >= 0.3.28 and <= 1.1.0

Core Dependencies:The SDK automatically installs these OpenTelemetry components:

opentelemetry-api (>= 1.19.0, <= 1.39.1)
opentelemetry-sdk (>= 1.19.0, <= 1.39.1)
opentelemetry-instrumentation (>= 0.40b0, <= 0.60b1)
opentelemetry-exporter-otlp-proto-http (>= 1.19.0, <= 1.39.1)
langgraph (>= 0.3.28, <= 1.1.0)
langchain (>= 0.3.26)

Set Up Your Fiddler Application

Create your application in Fiddler Log in to your Fiddler instance and navigate to GenAI Applications, then click Add Application and follow the onboarding wizard to create your application.
Copy your Application ID After creating your application, copy the Application ID from the GenAI Applications page using the copy icon next to the ID. This must be a valid UUID4 format (for example, 550e8400-e29b-41d4-a716-446655440000). You’ll need this for Step 3.
Get Your Access Token Go to Settings > Credentials and copy your access token. You’ll need this for Step 3. Refer to the documentation for more details.

Install the Fiddler LangGraph SDK

Standard InstallationFor the stable release, install the Fiddler LangGraph SDK using pip:

pip install fiddler-langgraph

Instrument Your Application

Add the Fiddler LangGraph SDK to your LangGraph or LangChain application with just a few lines of code:

from fiddler_langgraph import FiddlerClient, LangGraphInstrumentor

# Initialize the FiddlerClient. Replace the placeholder values below.
fdl_client = FiddlerClient(
    application_id='<FIDDLER_APPLICATION_ID>',  # Application ID copied from UI in Step 1
    api_key='<FIDDLER_API_KEY>',  # Your API key
    url='<FIDDLER_URL>',  # https://your-instance.fiddler.ai
)

# Instrument your application
instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

# Invoke your agent here
# You MUST instrument your application BEFORE invoking

# Your existing LangGraph code runs normally
# Traces will automatically be sent to Fiddler

Add Context and Conversation TrackingThe main goal of context setting is to enrich the telemetry data sent to Fiddler:

from fiddler_langgraph import set_llm_context, set_conversation_id
import uuid

# Set descriptive context for LLM processing
set_llm_context(model, 'Customer support conversation')

# Set conversation ID for tracking multi-turn conversations
conversation_id = str(uuid.uuid4())
set_conversation_id(conversation_id)

For AI engineers: The conversation tracking feature supports multi-turn agent interactions and helps trace decision flows across agent sessions.

Need more control? This Quick Start uses auto-instrumentation, which captures traces from LangGraph and LangChain automatically. The SDK also supports decorator-based and manual instrumentation for custom functions, non-LangGraph code, and fine-grained span control. See Instrumentation Methods in the integration guide.

Run a Complete Example

This example requires an OpenAI API key. You can create or find your key on the API keys page of your OpenAI account.

Here’s a complete working example to verify your setup:

import os
import uuid
from fiddler_langgraph import FiddlerClient, LangGraphInstrumentor, set_llm_context, set_conversation_id
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# Initialize the FiddlerClient. Replace the placeholder values below.
fdl_client = FiddlerClient(
    application_id='<FIDDLER_APPLICATION_ID>',  # Application ID copied from UI in Step 1
    api_key='<FIDDLER_API_KEY>',  # Your API key
    url='<FIDDLER_URL>',  # https://your-instance.fiddler.ai
)

# Instrument the application
instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

# Create your agent
model = ChatOpenAI(model="gpt-4o-mini")
agent = create_react_agent(model, tools=[])

# Set descriptive context for this interaction
set_llm_context(model, "Quick start example conversation")

# Generate and set a conversation ID
conversation_id = str(uuid.uuid4())
set_conversation_id(conversation_id)

# Run your agent - automatically instrumented
result = agent.invoke({
    "messages": [{"role": "user", "content": "Hello! How are you?"}]
})

print("Response received:", result)
print("Conversation ID:", conversation_id)

Short-lived scripts: The SDK batches spans in memory and exports them on a schedule. If your script exits before the batch is sent, call fdl_client.shutdown() (or use with FiddlerClient(...) as client:) to flush pending spans. Long-running servers handle this automatically via atexit. See Flush and shutdown handling for details.

Verify Monitoring is Working

Run your application using the example above or your own instrumented code
Check the Fiddler dashboard: Navigate to GenAI Applications in your Fiddler instance
Confirm active status: If Fiddler successfully receives telemetry, your application will show as Active

Success CriteriaYou should see:

Application status changed to Active in the Fiddler dashboard
Trace data appearing within 1-2 minutes of running your example
Context labels match what you set in your code
Conversation ID visible in the trace details

Grant Team Access (optional)

Provide access to other users by assigning teams and users to the project that contains your applications. Managing permissions through Teams is recommended as a best practice. For more access control details, refer to the Teams and Users Guide and the Role-based Access Guide.

Open the Settings page and select the Access tab
For both Users and Teams, select the “Edit” option to the right of the name
Add appropriate team members with the required permission levels

Configuration Options

Basic Configuration

from fiddler_langgraph import FiddlerClient

fdl_client = FiddlerClient(
    application_id="your-app-id",  # Must be valid UUID4
    api_key="your-api-key",
    url="https://your-instance.fiddler.ai"
)

Advanced Configuration

Customize Limits for High-Volume Applications

Set limits for your events, spans, and associated attributes. This is helpful for tuning reporting data to manageable numbers for highly attributed and/or high-volume applications.

from opentelemetry.sdk.trace import SpanLimits
from fiddler_langgraph import FiddlerClient

# Custom span limits for high-volume applications
custom_limits = SpanLimits(
    max_events=64,            # Default: 32
    max_links=64,             # Default: 32
    max_span_attributes=64,   # Default: 32
    max_event_attributes=64,  # Default: 32
    max_link_attributes=64,   # Default: 32
    max_span_attribute_length=4096, # Default: 2048
)

client = FiddlerClient(
    application_id="your-app-id",  # Must be valid UUID4
    api_key="your-api-key",
    url="https://your-instance.fiddler.ai",
    span_limits=custom_limits,
)

Sampling Traffic

Set a specific sampling percentage for incoming data.

from opentelemetry.sdk.trace import sampling
from fiddler_langgraph import FiddlerClient

# Sampling strategy for production
sampler = sampling.TraceIdRatioBased(0.1)  # Sample 10% of traces

client = FiddlerClient(
    application_id="your-app-id",  # Must be valid UUID4
    api_key="your-api-key",
    url="https://your-instance.fiddler.ai",
    sampler=sampler,
)

Environment Variables for Batch Processing

Adjust the following environment variables that the FiddlerClient will use when processing the OpenTelemetry traffic.

import os
from fiddler_langgraph import FiddlerClient

# Configure batch processing
os.environ['OTEL_BSP_MAX_QUEUE_SIZE'] = '500'         # Default: 100
os.environ['OTEL_BSP_SCHEDULE_DELAY_MILLIS'] = '500'  # Default: 1000
os.environ['OTEL_BSP_MAX_EXPORT_BATCH_SIZE'] = '50'   # Default: 10
os.environ['OTEL_BSP_EXPORT_TIMEOUT'] = '10000'       # Default: 5000

client = FiddlerClient(
    application_id="your-app-id",  # Must be valid UUID4
    api_key="your-api-key",
    url="https://your-instance.fiddler.ai",
)

Compression Options

The SDK supports data compression to help reduce the overall data volume transmitted over the network. This can help improve network latency.

from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
from fiddler_langgraph import FiddlerClient

# Enable gzip compression (default, recommended for production)
client = FiddlerClient(
    application_id="your-app-id",  # Must be valid UUID4
    api_key="your-api-key",
    url="https://your-instance.fiddler.ai",
    compression=Compression.Gzip,
)

# Disable compression (useful for debugging or local development)
client = FiddlerClient(
    application_id="your-app-id",  # Must be valid UUID4
    api_key="your-api-key",
    url="https://your-instance.fiddler.ai",
    compression=Compression.NoCompression,
)

# Use deflate compression (alternative to gzip)
client = FiddlerClient(
    application_id="your-app-id",  # Must be valid UUID4
    api_key="your-api-key",
    url="https://your-instance.fiddler.ai",
    compression=Compression.Deflate,
)

Environment Variables Reference

Configure OpenTelemetry batch processor behavior through environment variables:

Variable	Default	Description
`OTEL_BSP_MAX_QUEUE_SIZE`	`100`	Maximum spans in queue before export
`OTEL_BSP_SCHEDULE_DELAY_MILLIS`	`1000`	Delay between batch exports (milliseconds)
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	`10`	Maximum spans exported per batch
`OTEL_BSP_EXPORT_TIMEOUT`	`5000`	Export timeout (milliseconds)
`FIDDLER_API_KEY`	-	Your Fiddler API key (recommended for production)
`FIDDLER_APPLICATION_ID`	-	Your application UUID4 (recommended for production)
`FIDDLER_URL`	-	Your Fiddler instance URL (recommended for production)

Example: Tuning for high-volume applications

import os

os.environ['OTEL_BSP_MAX_QUEUE_SIZE'] = '500'
os.environ['OTEL_BSP_SCHEDULE_DELAY_MILLIS'] = '500'
os.environ['OTEL_BSP_MAX_EXPORT_BATCH_SIZE'] = '50'
os.environ['OTEL_BSP_EXPORT_TIMEOUT'] = '10000'

LangChain Application Support

The SDK supports both LangGraph and LangChain applications. While agent names are automatically extracted from LangGraph applications by the SDK, LangChain applications need the agent name to be explicitly set using the configuration parameter:

from langchain_core.output_parsers import StrOutputParser

# Define your LangChain runnable using LangChain Expression Language (LCEL)
chat_app_chain = prompt | llm | StrOutputParser()

# Run with agent name configuration
response = chat_app_chain.invoke({
    "input": user_input,
    "history": messages,
}, config={"configurable": {"agent_name": "service_chatbot"}})

Important: If you don’t provide an agent name for LangChain applications, it will appear as “UNKNOWN_AGENT” in the Fiddler UI. All other features, including conversation ID, LLM context, and attribute structure, work the same as with LangGraph.

Troubleshooting

Common Installation Issues

Problem: ModuleNotFoundError: No module named 'fiddler_langgraph'

Solution: Ensure you’ve installed the correct package: pip install fiddler*langgraph

Problem: Version conflicts with existing packages

Solution: Use a virtual environment or update conflicting packages

Common Configuration Issues

Problem: ValueError: application_id must be a valid UUID4

Solution: Ensure your Application ID is a valid UUID4 format (e.g., 550e8400-e29b-41d4-a716-446655440000)

Example:

# ❌ This will fail
client = FiddlerClient(
    application_id="invalid-id",  # Not a valid UUID4
    api_key="your-access-token",
    url="https://instance.fiddler.ai"
)
# Raises: ValueError: application_id must be a valid UUID4 string

# ✅ Correct format
client = FiddlerClient(
    application_id="550e8400-e29b-41d4-a716-446655440000",  # Valid UUID4
    api_key="your-access-token",
    url="https://instance.fiddler.ai"
)

Problem: ValueError: URL must have a valid scheme and netloc

Solution: Ensure your URL includes the protocol (e.g., https://your-instance.fiddler.ai)

Problem: Connection errors or timeouts

Solution: Check your network connectivity and Fiddler instance URL

Example: Handling connection failures gracefully

try:
    client = FiddlerClient(
        application_id=os.getenv("FIDDLER_APPLICATION_ID"),
        api_key=os.getenv("FIDDLER_API_KEY"),
        url="https://your-instance.fiddler.ai"
    )
    instrumentor = LangGraphInstrumentor(client)
    instrumentor.instrument()
except Exception as e:
    print(f"Fiddler instrumentation failed: {e}")
    # Your application continues running without tracing

Problem: Debugging trace generation

Solution: Enable console tracer for local debugging:

fdl_client = FiddlerClient(
    application_id="your-app-id",
    api_key="your-api-key",
    url="https://your-instance.fiddler.ai",
    console_tracer=True  # Also prints spans to console; OTLP export to Fiddler still active
)

console_tracer=True is additive — span data is printed to stdout and continues to be exported to Fiddler via OTLP. Setting this to True does not disable or suppress the OTLP export to Fiddler. Use it to visually confirm spans are being created during local development.

Problem: ImportError: cannot import name 'LangGraphInstrumentor'

Solution: Ensure you have the correct import path:

from fiddler_langgraph import LangGraphInstrumentor

Verification Issues

Problem: Application not showing as “Active” in Fiddler

Solution: Check the following:
1. Ensure your application executes instrumented code
2. Verify that your Fiddler access token and application ID are correct
3. Check network connectivity to your Fiddler instance
4. Enable console tracer to see if traces are being generated locally

Next Steps

Now that your application is instrumented:

Explore the data: Check your Fiddler dashboard for traces, metrics, and performance insights
Custom instrumentation: Use decorator-based and manual instrumentation for fine-grained control
Learn advanced features: See our Advanced Guide for multi-agent scenarios and production patterns
Review the SDK reference: Check the Fiddler LangGraph SDK Reference for complete documentation
Optimize for production: Review configuration options for high-volume applications

Documentation Index

​What You’ll Learn

​Grant Team Access (optional)

​Configuration Options

​Basic Configuration

​Advanced Configuration

​Customize Limits for High-Volume Applications

​Sampling Traffic

​Environment Variables for Batch Processing

​Compression Options

​Environment Variables Reference

​LangChain Application Support

​Troubleshooting

​Common Installation Issues

​Common Configuration Issues

​Verification Issues

​Next Steps

What You’ll Learn

Grant Team Access (optional)

Configuration Options

Basic Configuration

Advanced Configuration

Customize Limits for High-Volume Applications

Sampling Traffic

Environment Variables for Batch Processing

Compression Options

Environment Variables Reference

LangChain Application Support

Troubleshooting

Common Installation Issues

Common Configuration Issues

Verification Issues

Next Steps