Improve the loading of OPENAI_AGENTS_DISABLE_TRACING (#2302)

Author: seratch

src/agents/tracing/provider.py

@@ -196,10 +196,10 @@ def shutdown(self) -> None:
 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):
         """
@@ -229,7 +229,27 @@ def set_disabled(self, disabled: bool) -> None:
         """
         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."""
@@ -259,6 +279,7 @@ def create_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()
@@ -286,6 +307,7 @@ def create_span(
         """
         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}")

tests/tracing/test_tracing_env_disable.py

@@ -0,0 +1,56 @@
+from agents.tracing.provider import DefaultTraceProvider
+from agents.tracing.traces import NoOpTrace, TraceImpl
+
+
+def test_env_read_on_first_use(monkeypatch):
+    """Env flag set before first trace disables tracing."""
+    monkeypatch.setenv("OPENAI_AGENTS_DISABLE_TRACING", "1")
+    provider = DefaultTraceProvider()
+
+    trace = provider.create_trace("demo")
+
+    assert isinstance(trace, NoOpTrace)
+
+
+def test_env_cached_after_first_use(monkeypatch):
+    """Env flag is cached after the first trace and later env changes do not flip it."""
+    monkeypatch.setenv("OPENAI_AGENTS_DISABLE_TRACING", "0")
+    provider = DefaultTraceProvider()
+
+    first = provider.create_trace("first")
+    assert isinstance(first, TraceImpl)
+
+    # Change env after first use; cached value should keep tracing enabled.
+    monkeypatch.setenv("OPENAI_AGENTS_DISABLE_TRACING", "1")
+    second = provider.create_trace("second")
+
+    assert isinstance(second, TraceImpl)
+
+
+def test_manual_override_after_cache(monkeypatch):
+    """Manual toggle still works after env value is cached."""
+    monkeypatch.setenv("OPENAI_AGENTS_DISABLE_TRACING", "0")
+    provider = DefaultTraceProvider()
+
+    provider.create_trace("warmup")
+    provider.set_disabled(True)
+    disabled = provider.create_trace("disabled")
+    assert isinstance(disabled, NoOpTrace)
+
+    provider.set_disabled(False)
+    enabled = provider.create_trace("enabled")
+    assert isinstance(enabled, TraceImpl)
+
+
+def test_manual_override_env_disable(monkeypatch):
+    """Manual enable can override env disable flag."""
+    monkeypatch.setenv("OPENAI_AGENTS_DISABLE_TRACING", "1")
+    provider = DefaultTraceProvider()
+
+    env_disabled = provider.create_trace("env_disabled")
+    assert isinstance(env_disabled, NoOpTrace)
+
+    provider.set_disabled(False)
+    reenabled = provider.create_trace("reenabled")
+
+    assert isinstance(reenabled, TraceImpl)