LangGraph SDK Advanced - Fiddler Documentation

What You’ll Learn

This interactive notebook demonstrates advanced monitoring patterns for production LangGraph applications through a realistic travel planning system with multiple specialized agents. Key Topics Covered:

Multi-agent workflow monitoring and orchestration
Custom instrumentation with decorators and span wrappers
Combining auto-instrumentation with fine-grained manual spans
Conversation tracking across complex interactions
Production configuration for high-volume scenarios
Advanced error handling and recovery patterns
Business intelligence integration and analytics

Interactive Tutorial

The notebook walks through building a comprehensive travel planning application featuring hotel search, weather analysis, itinerary planning, and supervisor agents working together. Open the Advanced Observability Notebook in Google Colab → Or download the notebook directly from GitHub →

Custom Instrumentation Tutorial

For hands-on examples of decorator-based and manual instrumentation, including @trace(), span wrappers, and async support: Open the Custom Instrumentation Notebook in Google Colab → Or download the notebook directly from GitHub →

Custom Instrumentation Patterns

The SDK supports three instrumentation approaches. You can use them individually or combine them in the same application. For complete API reference, see the Instrumentation Methods section in the integration guide.

Combining Auto-Instrumentation with Decorators

Use LangGraphInstrumentor for automatic LangGraph/LangChain tracing, then add @trace() decorators to capture custom business logic that runs outside the framework:

from fiddler_langgraph import FiddlerClient, LangGraphInstrumentor, trace, get_current_span

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

# Auto-instrument LangGraph nodes
instrumentor = LangGraphInstrumentor(client)
instrumentor.instrument()

# Add custom tracing to business logic outside LangGraph
@trace(name="validate_input", as_type="chain")
def validate_user_input(user_message: str) -> dict:
    span = get_current_span(as_type="chain")
    if span:
        span.set_input(user_message)

    result = {"valid": True, "sanitized": user_message.strip()}

    if span:
        span.set_output(result)
    return result

# Both auto-instrumented LangGraph spans and custom spans
# appear together in Fiddler's trace view
validated = validate_user_input(user_message)
result = agent.invoke({"messages": [{"role": "user", "content": validated["sanitized"]}]})

Multi-Agent Decorator Patterns

When building multi-agent systems, @trace() decorators automatically establish parent-child span relationships through nested function calls:

import asyncio
from fiddler_langgraph import trace, get_current_span

@trace(name="supervisor", as_type="chain")
async def supervisor_agent(state: dict) -> dict:
    """Top-level orchestrator — creates parent span."""
    span = get_current_span(as_type="chain")
    if span:
        span.set_attribute("agent_count", len(state.get("tasks", [])))

    # Child spans nest automatically under the supervisor span
    results = await asyncio.gather(
        research_agent(state),
        analysis_agent(state),
    )

    if span:
        span.set_output({"completed": len(results)})
    return {"results": results}

@trace(name="research_agent", as_type="chain")
async def research_agent(state: dict) -> dict:
    """Child span nested under supervisor."""
    span = get_current_span(as_type="chain")
    if span:
        span.set_attribute("data_sources", 3)
    # ... research logic ...
    return {"findings": "..."}

@trace(name="analysis_agent", as_type="chain")
async def analysis_agent(state: dict) -> dict:
    """Child span nested under supervisor."""
    span = get_current_span(as_type="chain")
    if span:
        span.set_attribute("analysis_type", "comparative")
    # ... analysis logic ...
    return {"analysis": "..."}

Using Span Wrappers for Typed Attributes

Span wrapper classes provide typed helper methods for setting semantic attributes on LLM calls, tool invocations, and chain operations. Use them with start_as_current_span() for fine-grained control:

from fiddler_langgraph import FiddlerClient

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

# as_type="generation" returns a FiddlerGeneration wrapper with LLM-specific helper methods
with client.start_as_current_span("llm_call", as_type="generation") as gen:
    gen.set_model("gpt-4o")
    gen.set_system_prompt("You are a travel planning assistant.")
    gen.set_user_prompt(user_input)

    response = call_llm(user_input)

    gen.set_completion(response.content)
    gen.set_usage(response.usage.prompt_tokens, response.usage.completion_tokens)

# as_type="tool" returns a FiddlerTool wrapper with tool-specific helper methods
with client.start_as_current_span("search_hotels", as_type="tool") as tool:
    tool.set_tool_name("hotel_search")
    tool.set_tool_input({"city": "Paris", "dates": "2026-03-01"})

    results = search_hotels("Paris", "2026-03-01")

    tool.set_tool_output(results)

For the complete list of helper methods on each span wrapper class, see the Span Types and Helper Methods reference.

Production Configuration Best Practices

Before deploying LangGraph applications to production, configure the SDK for your specific workload characteristics.

High-Volume Applications

Optimize for applications processing thousands of traces per minute:

import os
from opentelemetry.sdk.trace import SpanLimits, sampling
from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
from fiddler_langgraph import FiddlerClient

# Configure batch processing BEFORE initializing FiddlerClient
os.environ['OTEL_BSP_MAX_QUEUE_SIZE'] = '500'         # Increased from default 100
os.environ['OTEL_BSP_SCHEDULE_DELAY_MILLIS'] = '500'  # Faster export than default 1000ms
os.environ['OTEL_BSP_MAX_EXPORT_BATCH_SIZE'] = '50'   # Larger batches than default 10
os.environ['OTEL_BSP_EXPORT_TIMEOUT'] = '10000'       # Longer timeout than default 5000ms

# Increase span limits to capture more data
production_limits = SpanLimits(
    max_events=128,                   # Default: 32
    max_links=64,                     # Default: 32
    max_span_attributes=128,          # Default: 32
    max_event_attributes=64,          # Default: 32
    max_link_attributes=32,           # Default: 32
    max_span_attribute_length=8192,   # Default: 2048
)

# Sample 5-10% of traces to manage data volume
production_sampler = sampling.TraceIdRatioBased(0.05)

client = FiddlerClient(
    application_id=os.getenv("FIDDLER_APPLICATION_ID"),
    api_key=os.getenv("FIDDLER_API_KEY"),
    url=os.getenv("FIDDLER_URL"),
    span_limits=production_limits,
    sampler=production_sampler,
    compression=Compression.Gzip,
)

Low-Latency Requirements

Optimize for applications requiring sub-second trace export:

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

# Reduce batch delay for faster exports
os.environ['OTEL_BSP_SCHEDULE_DELAY_MILLIS'] = '100'  # Export every 100ms
os.environ['OTEL_BSP_MAX_EXPORT_BATCH_SIZE'] = '5'    # Smaller batches

client = FiddlerClient(
    application_id=os.getenv("FIDDLER_APPLICATION_ID"),
    api_key=os.getenv("FIDDLER_API_KEY"),
    url=os.getenv("FIDDLER_URL"),
    compression=Compression.Gzip,  # Still use compression
)

Memory-Constrained Environments

Configure conservative limits for edge deployments or containerized environments:

import os
from opentelemetry.sdk.trace import SpanLimits, sampling
from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
from fiddler_langgraph import FiddlerClient

memory_constrained_limits = SpanLimits(
    max_events=16,                  # Minimal event capture
    max_links=16,                   # Minimal linking
    max_span_attributes=32,         # Reduced attributes
    max_event_attributes=16,        # Reduced event attributes
    max_link_attributes=16,         # Reduced link attributes
    max_span_attribute_length=1024, # Shorter attribute values
)

os.environ['OTEL_BSP_MAX_QUEUE_SIZE'] = '50'           # Smaller queue
os.environ['OTEL_BSP_MAX_EXPORT_BATCH_SIZE'] = '5'    # Smaller batches

client = FiddlerClient(
    application_id=os.getenv("FIDDLER_APPLICATION_ID"),
    api_key=os.getenv("FIDDLER_API_KEY"),
    url=os.getenv("FIDDLER_URL"),
    span_limits=memory_constrained_limits,
    sampler=sampling.TraceIdRatioBased(0.1),  # Sample 10%
    compression=Compression.Gzip,
)

Development vs Production Configurations

Development Configuration:

import os
from fiddler_langgraph import FiddlerClient

# Capture everything with verbose debugging
# console_tracer=True prints spans to stdout AND continues to export to Fiddler (additive)
dev_client = FiddlerClient(
    application_id=os.getenv("FIDDLER_APPLICATION_ID"),
    api_key=os.getenv("FIDDLER_API_KEY"),
    url=os.getenv("FIDDLER_URL"),
    console_tracer=True,    # Also prints spans to console; does NOT disable OTLP export
    sampler=None,           # Capture 100% of traces
)

Production Configuration:

import os
from opentelemetry.sdk.trace import SpanLimits, sampling
from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
from fiddler_langgraph import FiddlerClient

# Define production limits (see High-Volume Applications above for full example)
production_limits = SpanLimits(
    max_events=128, max_span_attributes=128, max_span_attribute_length=8192
)

# Optimized for performance and cost
prod_client = FiddlerClient(
    application_id=os.getenv("FIDDLER_APPLICATION_ID"),
    api_key=os.getenv("FIDDLER_API_KEY"),
    url=os.getenv("FIDDLER_URL"),
    sampler=sampling.TraceIdRatioBased(0.05),  # Sample 5%
    compression=Compression.Gzip,              # Reduce bandwidth
    span_limits=production_limits,             # Controlled limits
)

Best Practices for Context and Conversation IDs

Structure your identifiers for maximum analytical value:

from fiddler_langgraph import set_llm_context, set_conversation_id
import uuid

# Set meaningful, searchable context labels
set_llm_context(model, 'Customer Support - Tier 1 - Billing Inquiries')
set_llm_context(model, 'Content Generation - Marketing Copy - Blog Posts')
set_llm_context(model, 'Data Analysis - Financial Reports - Q4 2025')

# Use structured conversation IDs with metadata
user_id = 'user-12345'
session_type = 'support'
timestamp = '2026-06-15'
conversation_id = f'{user_id}_{session_type}_{timestamp}_{uuid.uuid4()}'
set_conversation_id(conversation_id)

# Example: user-12345_support_2026-06-15_550e8400-e29b-41d4-a716-446655440000

Prerequisites

Fiddler account with API credentials
OpenAI API key for example interactions
Basic familiarity with LangGraph concepts

Time Required

Complete tutorial: 45-60 minutes
Quick overview: 15-20 minutes

Telemetry Data Reference

Understanding the data captured by the Fiddler LangGraph SDK.

Span Attributes

The SDK automatically captures these OpenTelemetry attributes:

Attribute	Type	Description
`gen_ai.agent.name`	`str`	Name of the AI agent (auto-extracted from LangGraph, configurable for LangChain)
`gen_ai.agent.id`	`str`	Unique identifier (format: `trace_id:agent_name`)
`gen_ai.conversation.id`	`str`	Session identifier set via `set_conversation_id()`
`fiddler.span.type`	`str`	Span classification: `chain`, `tool`, `llm`, or `agent`
`gen_ai.llm.input.system`	`str`	System prompt content
`gen_ai.llm.input.user`	`str`	User input/prompt
`gen_ai.llm.output`	`str`	Model response text
`gen_ai.llm.context`	`str`	Custom context set via `set_llm_context()`
`gen_ai.request.model`	`str`	Model identifier (e.g., “gpt-4o-mini”)
`gen_ai.llm.token_count`	`int`	Token usage metrics
`gen_ai.tool.name`	`str`	Tool function name
`gen_ai.tool.input`	`str`	Tool input parameters (JSON)
`gen_ai.tool.output`	`str`	Tool execution results (JSON)
`gen_ai.tool.definitions`	`str`	Tool definitions available to the LLM (JSON array of OpenAI-format tool schemas)
`gen_ai.input.messages`	`str`	Complete message history provided as input to the LLM (JSON array)
`gen_ai.output.messages`	`str`	Output messages generated by the LLM, including tool calls (JSON array)
`duration_ms`	`float`	Span duration in milliseconds
`fiddler.error.message`	`str`	Error message (if span failed)
`fiddler.error.type`	`str`	Error type classification

Setting Attributes with Span Wrappers

When using manual instrumentation, span wrapper classes provide typed helper methods that set these attributes automatically. For example, FiddlerGeneration.set_model("gpt-4o") sets gen_ai.request.model, and FiddlerTool.set_tool_name("search") sets gen_ai.tool.name.

Span Wrapper	Key Methods	Attributes Set
`FiddlerGeneration`	`set_model()`, `set_system_prompt()`, `set_user_prompt()`, `set_completion()`, `set_usage()`, `set_messages()`, `set_output_messages()`, `set_tool_definitions()`	`gen_ai.request.model`, `gen_ai.llm.input.`, `gen_ai.llm.output`, `gen_ai.usage.`, `gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.tool.definitions`
`FiddlerTool`	`set_tool_name()`, `set_tool_input()`, `set_tool_output()`, `set_tool_definitions()`	`gen_ai.tool.name`, `gen_ai.tool.input`, `gen_ai.tool.output`, `gen_ai.tool.definitions`
`FiddlerChain`	`set_input()`, `set_output()`	Input/output data attributes
`FiddlerSpan`	`set_attribute()`, `set_agent_name()`, `set_conversation_id()`	Any custom or standard attribute

For the complete method reference, see Span Types and Helper Methods.

Querying and Filtering in Fiddler

Use these attributes in the Fiddler UI to:

Filter by agent: gen_ai.agent.name = "hotel_search_agent"
Find conversations: gen_ai.conversation.id = "user-123_support_2026-06-15..."
Analyze by model: gen_ai.request.model = "gpt-4o"
Track errors: fiddler.error.type EXISTS

Who Should Use This

AI engineers building production LangGraph applications
DevOps teams monitoring agentic systems
Technical leaders evaluating observability strategies

Limitations and Considerations

Current Limitations

Framework Support: LangGraph is fully supported with automatic agent name extraction
- LangChain applications require manual agent name configuration
- Non-LangGraph Python code can use @trace() decorators or manual context managers for custom instrumentation (see Instrumentation Methods)
Protocol Support: Currently uses HTTP-based OTLP
- gRPC support planned for future releases
Attribute Limits: Default OpenTelemetry limits apply
- Configurable via span_limits parameter
- Very large attribute values may be truncated

Performance Considerations

Overhead: Typical performance impact is < 5% with default settings

Use sampling to reduce overhead in high-volume scenarios
Adjust batch processing delays based on latency requirements

Memory: Span queue size affects the memory footprint

Default queue (100 spans) uses ~1-2MB
Increase OTEL_BSP_MAX_QUEUE_SIZE for high throughput
Decrease for memory-constrained environments

Network: Compression significantly reduces bandwidth usage

Gzip compression: ~70-80% reduction
Use Compression.NoCompression only for debugging

Production Deployment Checklist

Before deploying to production:

Set appropriate sampling rate (typically 5-10% for high-volume apps)
Configure span limits based on your data characteristics
Tune batch processing parameters for your traffic patterns
Enable Gzip compression (default, recommended)
Use environment variables for credentials (not hardcoded)
Test instrumentation in staging environment first
Monitor SDK performance impact
Set up alerts for instrumentation failures
Document your configuration for team knowledge sharing

When to Tune Each Setting

Scenario	Configuration
High-volume production	Increase queue size, batch size, sampling rate
Low-latency requirements	Decrease schedule delay, smaller batches
Memory constraints	Decrease span limits, queue size, batch size
Development/debugging	Disable sampling, enable console tracer
Cost optimization	Increase sampling (lower %), enable compression

Next Steps

After completing the tutorial:

Custom Instrumentation Notebook: Hands-on decorator and span wrapper examples
Integration Guide: Instrumentation Methods reference for @trace(), manual instrumentation, and span wrapper APIs
Technical Reference: Fiddler LangGraph SDK Documentation
Production Deployment: Adapt the demonstrated patterns for your specific use case

​What You’ll Learn

​Interactive Tutorial

​Custom Instrumentation Tutorial

​Custom Instrumentation Patterns

​Combining Auto-Instrumentation with Decorators

​Multi-Agent Decorator Patterns

​Using Span Wrappers for Typed Attributes

​Production Configuration Best Practices

​High-Volume Applications

​Low-Latency Requirements

​Memory-Constrained Environments

​Development vs Production Configurations

​Best Practices for Context and Conversation IDs

​Prerequisites

​Time Required

​Telemetry Data Reference

​Span Attributes

​Setting Attributes with Span Wrappers

​Querying and Filtering in Fiddler

​Who Should Use This

​Limitations and Considerations

​Current Limitations

​Performance Considerations

​Production Deployment Checklist

​When to Tune Each Setting

​Next Steps