docs: improve tracing module docstrings in source files

- Add detailed class and method descriptions
- Include practical usage examples
- Add implementation notes and best practices
- Document attributes and parameters
- Fix according to review feedback

Author: abdul-kabir-jawed

docs/ref/tracing/setup.md

@@ -1,147 +1,3 @@
-# Tracing Setup
+# `Setup`
 
-The tracing setup module provides functions to configure and initialize tracing for OpenAI Agents.
-
-## Functions
-
-### `set_tracing_disabled(disabled: bool) -> None`
-
-Disables or enables tracing globally.
-
-```python
-from agents import set_tracing_disabled
-
-# Disable tracing globally
-set_tracing_disabled(True)
-
-# Re-enable tracing
-set_tracing_disabled(False)
-```
-
-### `set_tracing_export_api_key(api_key: str) -> None`
-
-Sets the API key used for exporting traces to OpenAI's backend.
-
-```python
-from agents import set_tracing_export_api_key
-
-# Set a specific API key for tracing
-set_tracing_export_api_key("sk-your-openai-api-key")
-```
-
-### `add_trace_processor(processor: TraceProcessor) -> None`
-
-Adds an additional trace processor to the existing processors.
-
-```python
-from agents import add_trace_processor
-from agents.tracing.processors import TraceProcessor
-
-class CustomTraceProcessor(TraceProcessor):
-    def process_trace(self, trace):
-        # Custom processing logic
-        print(f"Processing trace: {trace.trace_id}")
-
-# Add custom processor
-add_trace_processor(CustomTraceProcessor())
-```
-
-### `set_trace_processors(processors: list[TraceProcessor]) -> None`
-
-Replaces all existing trace processors with the provided list.
-
-```python
-from agents import set_trace_processors
-from agents.tracing.processors import BatchTraceProcessor, BackendSpanExporter
-
-# Replace with custom processors
-custom_processors = [
-    BatchTraceProcessor(BackendSpanExporter()),
-    CustomTraceProcessor()
-]
-set_trace_processors(custom_processors)
-```
-
-## Environment Variables
-
-### `OPENAI_AGENTS_DISABLE_TRACING`
-
-Set to `1` to disable tracing globally.
-
-```bash
-export OPENAI_AGENTS_DISABLE_TRACING=1
-```
-
-## Common Setup Patterns
-
-### Basic Setup with Custom API Key
-
-```python
-import os
-from agents import set_tracing_export_api_key, Agent, Runner
-
-# Set up tracing with custom API key
-tracing_api_key = os.environ.get("OPENAI_TRACING_API_KEY")
-if tracing_api_key:
-    set_tracing_export_api_key(tracing_api_key)
-
-agent = Agent(name="Assistant", instructions="You are helpful")
-result = await Runner.run(agent, "Hello world")
-```
-
-### Setup with Custom Processor
-
-```python
-from agents import add_trace_processor, Agent, Runner
-from agents.tracing.processors import TraceProcessor
-import json
-
-class LoggingTraceProcessor(TraceProcessor):
-    def process_trace(self, trace):
-        # Log trace to file
-        with open("traces.log", "a") as f:
-            f.write(json.dumps({
-                "trace_id": trace.trace_id,
-                "workflow_name": trace.workflow_name,
-                "timestamp": trace.started_at.isoformat()
-            }) + "\n")
-
-# Add logging processor
-add_trace_processor(LoggingTraceProcessor())
-
-agent = Agent(name="Assistant")
-result = await Runner.run(agent, "Test message")
-```
-
-### Disable Tracing for Specific Runs
-
-```python
-from agents import Agent, Runner, RunConfig
-
-agent = Agent(name="Assistant")
-
-# Disable tracing for this specific run
-result = await Runner.run(
-    agent, 
-    "Hello world",
-    run_config=RunConfig(tracing_disabled=True)
-)
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **401 Unauthorized Error**: Make sure you have a valid OpenAI API key set
-2. **Tracing Not Working**: Check if `OPENAI_AGENTS_DISABLE_TRACING=1` is set
-3. **Custom Processors Not Receiving Data**: Ensure processors are added before running agents
-
-### Debug Mode
-
-Enable verbose logging to debug tracing issues:
-
-```python
-from agents import enable_verbose_stdout_logging
-
-enable_verbose_stdout_logging()
-```
+::: agents.tracing.setup

src/agents/tracing/processor_interface.py

@@ -7,52 +7,125 @@
 
 
 class TracingProcessor(abc.ABC):
-    """Interface for processing spans."""
+    """Interface for processing and monitoring traces and spans in the OpenAI Agents system.
+
+    This abstract class defines the interface that all tracing processors must implement.
+    Processors receive notifications when traces and spans start and end, allowing them
+    to collect, process, and export tracing data.
+
+    Example:
+        ```python
+        class CustomProcessor(TracingProcessor):
+            def __init__(self):
+                self.active_traces = {}
+                self.active_spans = {}
+
+            def on_trace_start(self, trace):
+                self.active_traces[trace.trace_id] = trace
+                
+            def on_trace_end(self, trace):
+                # Process completed trace
+                del self.active_traces[trace.trace_id]
+                
+            def on_span_start(self, span):
+                self.active_spans[span.span_id] = span
+                
+            def on_span_end(self, span):
+                # Process completed span
+                del self.active_spans[span.span_id]
+
+            def shutdown(self):
+                # Clean up resources
+                self.active_traces.clear()
+                self.active_spans.clear()
+
+            def force_flush(self):
+                # Force processing of any queued items
+                pass
+        ```
+
+    Notes:
+        - All methods should be thread-safe
+        - Methods should not block for long periods
+        - Handle errors gracefully to prevent disrupting agent execution
+    """
 
     @abc.abstractmethod
     def on_trace_start(self, trace: "Trace") -> None:
-        """Called when a trace is started.
+        """Called when a new trace begins execution.
 
         Args:
-            trace: The trace that started.
+            trace: The trace that started. Contains workflow name and metadata.
+
+        Notes:
+            - Called synchronously on trace start
+            - Should return quickly to avoid blocking execution
+            - Any errors should be caught and handled internally
         """
         pass
 
     @abc.abstractmethod
     def on_trace_end(self, trace: "Trace") -> None:
-        """Called when a trace is finished.
+        """Called when a trace completes execution.
 
         Args:
-            trace: The trace that finished.
+            trace: The completed trace containing all spans and results.
+
+        Notes:
+            - Called synchronously when trace finishes
+            - Good time to export/process the complete trace
+            - Should handle cleanup of any trace-specific resources
         """
         pass
 
     @abc.abstractmethod
     def on_span_start(self, span: "Span[Any]") -> None:
-        """Called when a span is started.
+        """Called when a new span begins execution.
 
         Args:
-            span: The span that started.
+            span: The span that started. Contains operation details and context.
+
+        Notes:
+            - Called synchronously on span start 
+            - Should return quickly to avoid blocking execution
+            - Spans are automatically nested under current trace/span
         """
         pass
 
     @abc.abstractmethod
     def on_span_end(self, span: "Span[Any]") -> None:
-        """Called when a span is finished. Should not block or raise exceptions.
+        """Called when a span completes execution.
 
         Args:
-            span: The span that finished.
+            span: The completed span containing execution results.
+
+        Notes:
+            - Called synchronously when span finishes
+            - Should not block or raise exceptions
+            - Good time to export/process the individual span
         """
         pass
 
     @abc.abstractmethod
     def shutdown(self) -> None:
-        """Called when the application stops."""
+        """Called when the application stops to clean up resources.
+
+        Should perform any necessary cleanup like:
+        - Flushing queued traces/spans
+        - Closing connections
+        - Releasing resources
+        """
         pass
 
     @abc.abstractmethod
     def force_flush(self) -> None:
-        """Forces an immediate flush of all queued spans/traces."""
+        """Forces immediate processing of any queued traces/spans.
+
+        Notes:
+            - Should process all queued items before returning
+            - Useful before shutdown or when immediate processing is needed
+            - May block while processing completes
+        """
         pass