Using LangWatch’s LangChain Callback Handler with LangGraph
LangGraph is built on top of LangChain, so we can use the sameLangWatchCallbackHandler
to instrument LangGraph applications. This provides comprehensive tracing of your state graphs, node executions, and workflow patterns.
setupObservability()
: Initializes LangWatch with default configuration.getLangWatchTracer()
: Creates a tracer instance for your application.tracer.withActiveSpan()
: Creates a parent LangWatch trace that encompasses the entire workflow.LangWatchCallbackHandler
: Captures LangGraph node executions and LangChain events, converting them into detailed LangWatch spans.StateGraph
: Defines the workflow structure with nodes and conditional edges.app.stream()
: Executes the workflow with streaming support for real-time tracing.- The callback handler is passed to both individual LangChain components and the compiled graph.
- Provides detailed tracing of each node execution within the state graph.
- Captures routing decisions and workflow patterns.
- Works with all LangGraph execution methods (
invoke
,stream
,batch
). - Automatically handles span lifecycle management with
withActiveSpan()
.
Why Use the LangWatch LangChain Callback Handler with LangGraph?
The LangWatch LangChain Callback Handler provides comprehensive tracing for LangGraph applications by capturing both the LangGraph workflow structure and the underlying LangChain operations. This gives you complete visibility into your multi-step AI workflows.Advanced Patterns
Node-Level Tracing
You can add custom tracing to individual nodes for more detailed observability:Common Mistakes and Caveats
1. Setup and Initialization Issues
Multiple setup calls:
setupObservability()
can only be called once per process. Subsequent calls will throw an error.2. Callback Handler Usage
Reusing callback handlers: Each workflow execution should use a fresh
LangWatchCallbackHandler
instance to avoid span conflicts.3. State Management
State mutation: Avoid directly mutating state objects in LangGraph nodes. Always return new state objects.
4. Error Handling in Workflows
Unhandled errors in nodes: Always handle errors in individual nodes to prevent workflow crashes.
5. Environment Configuration
Missing environment variables: Ensure all required environment variables are set before running your LangGraph application.
Best Practices Summary
- Call
setupObservability()
only once per process - Use fresh callback handlers for each workflow execution to avoid conflicts
- Avoid state mutation - always return new state objects from nodes
- Handle errors properly in individual nodes and workflows
- Validate environment variables before starting your application
Example Project
You can find a complete example project demonstrating LangGraph integration with LangWatch on our GitHub. This example includes:- Basic Chatbot: A simple chatbot that handles conversation flow using LangGraph
- State Management: Proper state graph management and workflow patterns
- Conversation Management: User input handling and conversation history management
- Error Handling: Comprehensive error handling and exit commands
- Full LangWatch Integration: Complete observability and tracing setup
Key Features
- Automatic Tracing: All LangGraph node executions and workflow patterns are automatically traced
- State Graph Visualization: Demonstrates proper state graph construction and execution
- Workflow Patterns: Shows how to build complex multi-step AI workflows
- Node-Level Observability: Detailed tracing of individual node executions
- Error Recovery: Handles errors gracefully with proper cleanup
Related Documentation
For more advanced LangGraph integration patterns and best practices:- Integration Guide - Basic setup and core concepts
- Manual Instrumentation - Advanced span management for LangGraph workflows
- Capturing RAG - RAG patterns within LangGraph workflows
- Semantic Conventions - LangGraph-specific attributes and conventions
- Debugging and Troubleshooting - Debug LangGraph integration issues
LangGraph’s workflow tracing works well with Manual Instrumentation for custom nodes and Semantic Conventions for consistent attribute naming across your workflow.