Custom Tracing

Demonstrates advanced tracing patterns including custom traces, spans, and workflow organization for complex multi-agent systems.

🎯 What This Demonstrates

• Custom Traces: Grouping multiple agent runs in single workflows
• Custom Spans: Adding business logic monitoring points
• Hierarchical Tracking: Nested spans for complex operations
• Trace Metadata: Organizing traces with groups and metadata

🚀 Quick Start

1. Install OpenAI Agents SDK:

   pip install openai-agents
   

2. Set up environment:

   cp ../env.example .env
   # Edit .env and add your OpenAI API key
   

3. Run the agent:

   import asyncio
   from agent import main
   
   # Test custom tracing patterns
   asyncio.run(main())
   

💡 Key Concepts

• trace() Context Manager: Creating custom workflow groupings
• custom_span(): Adding business logic monitoring
• Trace Metadata: Workflow naming and organization
• Hierarchical Structure: Nested spans for complex operations

🧪 Custom Tracing Patterns

Multi-Step Workflow Traces

with trace("Research and Analysis Workflow") as workflow_trace:
    # Step 1: Research
    research_result = await Runner.run(research_agent, "Research AI in healthcare")
    
    # Step 2: Analysis  
    analysis_result = await Runner.run(analysis_agent, f"Analyze: {research_result.final_output}")
    
    # Step 3: Summary
    summary_result = await Runner.run(analysis_agent, f"Summarize: {analysis_result.final_output}")

Custom Business Logic Spans

with trace("Document Processing Workflow") as doc_trace:
    
    with custom_span("Data Preparation") as prep_span:
        # Your business logic here
        data = prepare_data()
        prep_span.add_event("Data loaded", {"records": 100})
        prep_span.add_event("Data validated", {"errors": 0})
        
    with custom_span("AI Processing") as ai_span:
        result = await Runner.run(agent, "Process the data")
        ai_span.add_event("Processing complete", {
            "output_length": len(result.final_output)
        })

Hierarchical Spans

with trace("E-commerce Order Processing") as order_trace:
    
    with custom_span("Order Validation") as validation_span:
        
        # Nested span for inventory check
        with custom_span("Inventory Check") as inventory_span:
            inventory_span.add_event("Stock verified", {"available": True})
        
        # Nested span for payment validation
        with custom_span("Payment Validation") as payment_span:
            payment_span.add_event("Payment authorized", {"amount": 99.99})

💻 Advanced Features

Trace Metadata and Grouping

conversation_id = "conv_12345"

# First interaction in conversation
with trace(
    "Customer Support - Initial Inquiry",
    group_id=conversation_id,
    metadata={"customer_id": "cust_789", "priority": "high"}
) as trace1:
    result1 = await Runner.run(support_agent, "How do I reset my password?")

# Follow-up interaction in same conversation
with trace(
    "Customer Support - Follow-up",
    group_id=conversation_id,
    metadata={"customer_id": "cust_789", "interaction": 2}
) as trace2:
    result2 = await Runner.run(support_agent, f"Based on this context: {result1.final_output}")

Event Tracking

with custom_span("Business Process") as span:
    span.add_event("Process started", {"timestamp": datetime.now()})
    # Business logic here
    span.add_event("Milestone reached", {"progress": "50%"})
    # More business logic
    span.add_event("Process completed", {"status": "success"})

🔍 Benefits of Custom Tracing

Workflow Organization

• Group Related Operations: Multiple agent runs in single trace
• Business Logic Visibility: Monitor custom processes alongside AI
• Performance Analysis: Track end-to-end workflow performance

Production Monitoring

• Error Correlation: Link failures across multiple components
• Performance Optimization: Identify bottlenecks in complex workflows
• User Journey Tracking: Follow conversations across interactions

Debugging and Analysis

• Complex Workflow Understanding: Visualize multi-step processes
• Context Preservation: Maintain relationship between related operations
• Metadata Organization: Filter and search traces by business criteria

🔗 Next Steps

• Default Tracing - Basic tracing fundamentals
• Tutorial 11: Production Patterns - Real-world deployment