openai-agents 0.2.8__py3-none-any.whl → 0.6.8__py3-none-any.whl

agents/tracing/provider.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 import os
 import threading
 import uuid
@@ -8,12 +9,38 @@ from datetime import datetime, timezone
 from typing import Any
 
 from ..logger import logger
+from .config import TracingConfig
 from .processor_interface import TracingProcessor
 from .scope import Scope
 from .spans import NoOpSpan, Span, SpanImpl, TSpanData
 from .traces import NoOpTrace, Trace, TraceImpl
 
 
+def _safe_debug(message: str) -> None:
+    """Best-effort debug logging that tolerates closed streams during shutdown."""
+
+    def _has_closed_stream_handler(log: logging.Logger) -> bool:
+        current: logging.Logger | None = log
+        while current is not None:
+            for handler in current.handlers:
+                stream = getattr(handler, "stream", None)
+                if stream is not None and getattr(stream, "closed", False):
+                    return True
+            if not current.propagate:
+                break
+            current = current.parent
+        return False
+
+    try:
+        # Avoid emitting debug logs when any handler already owns a closed stream.
+        if _has_closed_stream_handler(logger):
+            return
+        logger.debug(message)
+    except Exception:
+        # Avoid noisy shutdown errors when the underlying stream is already closed.
+        return
+
+
 class SynchronousMultiTracingProcessor(TracingProcessor):
     """
     Forwards all calls to a list of TracingProcessors, in order of registration.
@@ -83,7 +110,7 @@ class SynchronousMultiTracingProcessor(TracingProcessor):
         Called when the application stops.
         """
         for processor in self._processors:
-            logger.debug(f"Shutting down trace processor {processor}")
+            _safe_debug(f"Shutting down trace processor {processor}")
             try:
                 processor.shutdown()
             except Exception as e:
@@ -147,6 +174,7 @@ class TraceProvider(ABC):
         group_id: str | None = None,
         metadata: dict[str, Any] | None = None,
         disabled: bool = False,
+        tracing: TracingConfig | None = None,
     ) -> Trace:
         """Create a new trace."""
 
@@ -168,10 +196,10 @@ class TraceProvider(ABC):
 class DefaultTraceProvider(TraceProvider):
     def __init__(self) -> None:
         self._multi_processor = SynchronousMultiTracingProcessor()
-        self._disabled = os.environ.get("OPENAI_AGENTS_DISABLE_TRACING", "false").lower() in (
-            "true",
-            "1",
-        )
+        # Lazily read env flag on first use to honor env set after import but before first trace.
+        self._env_disabled: bool | None = None
+        self._manual_disabled: bool | None = None
+        self._disabled = False
 
     def register_processor(self, processor: TracingProcessor):
         """
@@ -201,7 +229,27 @@ class DefaultTraceProvider(TraceProvider):
         """
         Set whether tracing is disabled.
         """
-        self._disabled = disabled
+        self._manual_disabled = disabled
+        self._refresh_disabled_flag()
+
+    def _refresh_disabled_flag(self) -> None:
+        """Refresh disabled flag from cached env value and manual override.
+
+        The env flag is read once on first use to avoid surprises mid-run; further env
+        changes are ignored after the manual flag is set via set_disabled, which always
+        takes precedence over the env value.
+        """
+        if self._env_disabled is None:
+            self._env_disabled = os.environ.get(
+                "OPENAI_AGENTS_DISABLE_TRACING", "false"
+            ).lower() in (
+                "true",
+                "1",
+            )
+        if self._manual_disabled is None:
+            self._disabled = bool(self._env_disabled)
+        else:
+            self._disabled = self._manual_disabled
 
     def time_iso(self) -> str:
         """Return the current time in ISO 8601 format."""
@@ -226,10 +274,12 @@ class DefaultTraceProvider(TraceProvider):
         group_id: str | None = None,
         metadata: dict[str, Any] | None = None,
         disabled: bool = False,
+        tracing: TracingConfig | None = None,
     ) -> Trace:
         """
         Create a new trace.
         """
+        self._refresh_disabled_flag()
         if self._disabled or disabled:
             logger.debug(f"Tracing is disabled. Not creating trace {name}")
             return NoOpTrace()
@@ -244,6 +294,7 @@ class DefaultTraceProvider(TraceProvider):
             group_id=group_id,
             metadata=metadata,
             processor=self._multi_processor,
+            tracing_api_key=tracing.get("api_key") if tracing else None,
         )
 
     def create_span(
@@ -256,6 +307,8 @@ class DefaultTraceProvider(TraceProvider):
         """
         Create a new span.
         """
+        self._refresh_disabled_flag()
+        tracing_api_key: str | None = None
         if self._disabled or disabled:
             logger.debug(f"Tracing is disabled. Not creating span {span_data}")
             return NoOpSpan(span_data)
@@ -277,6 +330,7 @@ class DefaultTraceProvider(TraceProvider):
 
             parent_id = current_span.span_id if current_span else None
             trace_id = current_trace.trace_id
+            tracing_api_key = current_trace.tracing_api_key
 
         elif isinstance(parent, Trace):
             if isinstance(parent, NoOpTrace):
@@ -284,12 +338,14 @@ class DefaultTraceProvider(TraceProvider):
                 return NoOpSpan(span_data)
             trace_id = parent.trace_id
             parent_id = None
+            tracing_api_key = parent.tracing_api_key
         elif isinstance(parent, Span):
             if isinstance(parent, NoOpSpan):
                 logger.debug(f"Parent {parent} is no-op, returning NoOpSpan")
                 return NoOpSpan(span_data)
             parent_id = parent.span_id
             trace_id = parent.trace_id
+            tracing_api_key = parent.tracing_api_key
 
         logger.debug(f"Creating span {span_data} with id {span_id}")
 
@@ -299,6 +355,7 @@ class DefaultTraceProvider(TraceProvider):
             parent_id=parent_id,
             processor=self._multi_processor,
             span_data=span_data,
+            tracing_api_key=tracing_api_key,
         )
 
     def shutdown(self) -> None:
@@ -306,7 +363,7 @@ class DefaultTraceProvider(TraceProvider):
             return
 
         try:
-            logger.debug("Shutting down trace provider")
+            _safe_debug("Shutting down trace provider")
             self._multi_processor.shutdown()
         except Exception as e:
             logger.error(f"Error shutting down trace provider: {e}")

agents/tracing/spans.py

@@ -16,24 +16,84 @@ TSpanData = TypeVar("TSpanData", bound=SpanData)
 
 
 class SpanError(TypedDict):
+    """Represents an error that occurred during span execution.
+
+    Attributes:
+        message: A human-readable error description
+        data: Optional dictionary containing additional error context
+    """
+
     message: str
     data: dict[str, Any] | None
 
 
 class Span(abc.ABC, Generic[TSpanData]):
+    """Base class for representing traceable operations with timing and context.
+
+    A span represents a single operation within a trace (e.g., an LLM call, tool execution,
+    or agent run). Spans track timing, relationships between operations, and operation-specific
+    data.
+
+    Type Args:
+        TSpanData: The type of span-specific data this span contains.
+
+    Example:
+        ```python
+        # Creating a custom span
+        with custom_span("database_query", {
+            "operation": "SELECT",
+            "table": "users"
+        }) as span:
+            results = await db.query("SELECT * FROM users")
+            span.set_output({"count": len(results)})
+
+        # Handling errors in spans
+        with custom_span("risky_operation") as span:
+            try:
+                result = perform_risky_operation()
+            except Exception as e:
+                span.set_error({
+                    "message": str(e),
+                    "data": {"operation": "risky_operation"}
+                })
+                raise
+        ```
+
+        Notes:
+        - Spans automatically nest under the current trace
+        - Use context managers for reliable start/finish
+        - Include relevant data but avoid sensitive information
+        - Handle errors properly using set_error()
+    """
+
     @property
     @abc.abstractmethod
     def trace_id(self) -> str:
+        """The ID of the trace this span belongs to.
+
+        Returns:
+            str: Unique identifier of the parent trace.
+        """
         pass
 
     @property
     @abc.abstractmethod
     def span_id(self) -> str:
+        """Unique identifier for this span.
+
+        Returns:
+            str: The span's unique ID within its trace.
+        """
         pass
 
     @property
     @abc.abstractmethod
     def span_data(self) -> TSpanData:
+        """Operation-specific data for this span.
+
+        Returns:
+            TSpanData: Data specific to this type of span (e.g., LLM generation data).
+        """
         pass
 
     @abc.abstractmethod
@@ -67,6 +127,11 @@ class Span(abc.ABC, Generic[TSpanData]):
     @property
     @abc.abstractmethod
     def parent_id(self) -> str | None:
+        """ID of the parent span, if any.
+
+        Returns:
+            str | None: The parent span's ID, or None if this is a root span.
+        """
         pass
 
     @abc.abstractmethod
@@ -76,6 +141,11 @@ class Span(abc.ABC, Generic[TSpanData]):
     @property
     @abc.abstractmethod
     def error(self) -> SpanError | None:
+        """Any error that occurred during span execution.
+
+        Returns:
+            SpanError | None: Error details if an error occurred, None otherwise.
+        """
         pass
 
     @abc.abstractmethod
@@ -85,15 +155,39 @@ class Span(abc.ABC, Generic[TSpanData]):
     @property
     @abc.abstractmethod
     def started_at(self) -> str | None:
+        """When the span started execution.
+
+        Returns:
+            str | None: ISO format timestamp of span start, None if not started.
+        """
         pass
 
     @property
     @abc.abstractmethod
     def ended_at(self) -> str | None:
+        """When the span finished execution.
+
+        Returns:
+            str | None: ISO format timestamp of span end, None if not finished.
+        """
+        pass
+
+    @property
+    @abc.abstractmethod
+    def tracing_api_key(self) -> str | None:
+        """The API key to use when exporting this span."""
         pass
 
 
 class NoOpSpan(Span[TSpanData]):
+    """A no-op implementation of Span that doesn't record any data.
+
+    Used when tracing is disabled but span operations still need to work.
+
+    Args:
+        span_data: The operation-specific data for this span.
+    """
+
     __slots__ = ("_span_data", "_prev_span_token")
 
     def __init__(self, span_data: TSpanData):
@@ -155,6 +249,10 @@ class NoOpSpan(Span[TSpanData]):
     def ended_at(self) -> str | None:
         return None
 
+    @property
+    def tracing_api_key(self) -> str | None:
+        return None
+
 
 class SpanImpl(Span[TSpanData]):
     __slots__ = (
@@ -167,6 +265,7 @@ class SpanImpl(Span[TSpanData]):
         "_prev_span_token",
         "_processor",
         "_span_data",
+        "_tracing_api_key",
     )
 
     def __init__(
@@ -176,6 +275,7 @@ class SpanImpl(Span[TSpanData]):
         parent_id: str | None,
         processor: TracingProcessor,
         span_data: TSpanData,
+        tracing_api_key: str | None,
     ):
         self._trace_id = trace_id
         self._span_id = span_id or util.gen_span_id()
@@ -186,6 +286,7 @@ class SpanImpl(Span[TSpanData]):
         self._error: SpanError | None = None
         self._prev_span_token: contextvars.Token[Span[TSpanData] | None] | None = None
         self._span_data = span_data
+        self._tracing_api_key = tracing_api_key
 
     @property
     def trace_id(self) -> str:
@@ -251,6 +352,10 @@ class SpanImpl(Span[TSpanData]):
     def ended_at(self) -> str | None:
         return self._ended_at
 
+    @property
+    def tracing_api_key(self) -> str | None:
+        return self._tracing_api_key
+
     def export(self) -> dict[str, Any] | None:
         return {
             "object": "trace.span",

agents/tracing/traces.py

@@ -11,8 +11,35 @@ from .scope import Scope
 
 
 class Trace(abc.ABC):
-    """
-    A trace is the root level object that tracing creates. It represents a logical "workflow".
+    """A complete end-to-end workflow containing related spans and metadata.
+
+    A trace represents a logical workflow or operation (e.g., "Customer Service Query"
+    or "Code Generation") and contains all the spans (individual operations) that occur
+    during that workflow.
+
+    Example:
+        ```python
+        # Basic trace usage
+        with trace("Order Processing") as t:
+            validation_result = await Runner.run(validator, order_data)
+            if validation_result.approved:
+                await Runner.run(processor, order_data)
+
+        # Trace with metadata and grouping
+        with trace(
+            "Customer Service",
+            group_id="chat_123",
+            metadata={"customer": "user_456"}
+        ) as t:
+            result = await Runner.run(support_agent, query)
+        ```
+
+    Notes:
+        - Use descriptive workflow names
+        - Group related traces with consistent group_ids
+        - Add relevant metadata for filtering/analysis
+        - Use context managers for reliable cleanup
+        - Consider privacy when adding trace data
     """
 
     @abc.abstractmethod
@@ -25,51 +52,98 @@ class Trace(abc.ABC):
 
     @abc.abstractmethod
     def start(self, mark_as_current: bool = False):
-        """
-        Start the trace.
+        """Start the trace and optionally mark it as the current trace.
 
         Args:
-            mark_as_current: If true, the trace will be marked as the current trace.
+            mark_as_current: If true, marks this trace as the current trace
+                in the execution context.
+
+        Notes:
+            - Must be called before any spans can be added
+            - Only one trace can be current at a time
+            - Thread-safe when using mark_as_current
         """
         pass
 
     @abc.abstractmethod
     def finish(self, reset_current: bool = False):
-        """
-        Finish the trace.
+        """Finish the trace and optionally reset the current trace.
 
         Args:
-            reset_current: If true, the trace will be reset as the current trace.
+            reset_current: If true, resets the current trace to the previous
+                trace in the execution context.
+
+        Notes:
+            - Must be called to complete the trace
+            - Finalizes all open spans
+            - Thread-safe when using reset_current
         """
         pass
 
     @property
     @abc.abstractmethod
     def trace_id(self) -> str:
-        """
-        The trace ID.
+        """Get the unique identifier for this trace.
+
+        Returns:
+            str: The trace's unique ID in the format 'trace_<32_alphanumeric>'
+
+        Notes:
+            - IDs are globally unique
+            - Used to link spans to their parent trace
+            - Can be used to look up traces in the dashboard
         """
         pass
 
     @property
     @abc.abstractmethod
     def name(self) -> str:
-        """
-        The name of the workflow being traced.
+        """Get the human-readable name of this workflow trace.
+
+        Returns:
+            str: The workflow name (e.g., "Customer Service", "Data Processing")
+
+        Notes:
+            - Should be descriptive and meaningful
+            - Used for grouping and filtering in the dashboard
+            - Helps identify the purpose of the trace
         """
         pass
 
     @abc.abstractmethod
     def export(self) -> dict[str, Any] | None:
+        """Export the trace data as a serializable dictionary.
+
+        Returns:
+            dict | None: Dictionary containing trace data, or None if tracing is disabled.
+
+        Notes:
+            - Includes all spans and their data
+            - Used for sending traces to backends
+            - May include metadata and group ID
         """
-        Export the trace as a dictionary.
-        """
+        pass
+
+    @property
+    @abc.abstractmethod
+    def tracing_api_key(self) -> str | None:
+        """The API key to use when exporting this trace and its spans."""
         pass
 
 
 class NoOpTrace(Trace):
-    """
-    A no-op trace that will not be recorded.
+    """A no-op implementation of Trace that doesn't record any data.
+
+    Used when tracing is disabled but trace operations still need to work.
+    Maintains proper context management but doesn't store or export any data.
+
+    Example:
+        ```python
+        # When tracing is disabled, traces become NoOpTrace
+        with trace("Disabled Workflow") as t:
+            # Operations still work but nothing is recorded
+            await Runner.run(agent, "query")
+        ```
     """
 
     def __init__(self):
@@ -101,13 +175,32 @@ class NoOpTrace(Trace):
 
     @property
     def trace_id(self) -> str:
+        """The trace's unique identifier.
+
+        Returns:
+            str: A unique ID for this trace.
+        """
         return "no-op"
 
     @property
     def name(self) -> str:
+        """The workflow name for this trace.
+
+        Returns:
+            str: Human-readable name describing this workflow.
+        """
         return "no-op"
 
     def export(self) -> dict[str, Any] | None:
+        """Export the trace data as a dictionary.
+
+        Returns:
+            dict | None: Trace data in exportable format, or None if no data.
+        """
+        return None
+
+    @property
+    def tracing_api_key(self) -> str | None:
         return None
 
 
@@ -122,6 +215,7 @@ class TraceImpl(Trace):
     __slots__ = (
         "_name",
         "_trace_id",
+        "_tracing_api_key",
         "group_id",
         "metadata",
         "_prev_context_token",
@@ -136,9 +230,11 @@ class TraceImpl(Trace):
         group_id: str | None,
         metadata: dict[str, Any] | None,
         processor: TracingProcessor,
+        tracing_api_key: str | None,
     ):
         self._name = name
         self._trace_id = trace_id or util.gen_trace_id()
+        self._tracing_api_key = tracing_api_key
         self.group_id = group_id
         self.metadata = metadata
         self._prev_context_token: contextvars.Token[Trace | None] | None = None
@@ -153,6 +249,10 @@ class TraceImpl(Trace):
     def name(self) -> str:
         return self._name
 
+    @property
+    def tracing_api_key(self) -> str | None:
+        return self._tracing_api_key
+
     def start(self, mark_as_current: bool = False):
         if self._started:
             return