Mark telemetry as experimental

Author: anbuzin

examples/agents/telemetry.py

@@ -1,26 +1,28 @@
 """Agent run with telemetry: console adapter + a custom span in a tool.
 
-For an out-of-process viewer, run ``python -m ai.telemetry.utils.viewer``
-and see ``ai/telemetry/utils/viewer.py`` for the otel exporter setup.
+For an out-of-process viewer, run
+``python -m ai.experimental_telemetry.utils.viewer`` and see
+``ai/experimental_telemetry/utils/viewer.py`` for the otel exporter
+setup.
 """
 
 import asyncio
 
 import ai
-from ai.telemetry.utils import console
+from ai.experimental_telemetry.utils import console
 
 
 @ai.tool
 async def get_weather(city: str) -> str:
     """Get current weather for a city."""
-    async with ai.telemetry.span("lookup", city=city) as span:
+    async with ai.experimental_telemetry.span("lookup", city=city) as span:
         await asyncio.sleep(0.1)
         span.set(source="cache")
     return f"Sunny, 72F in {city}"
 
 
 async def main() -> None:
-    ai.telemetry.register(console.ConsoleAdapter())
+    ai.experimental_telemetry.register(console.ConsoleAdapter())
 
     model = ai.get_model("anthropic/claude-sonnet-4.6")
     my_agent = ai.Agent(tools=[get_weather])

src/ai/__init__.py

@@ -1,4 +1,4 @@
-from . import errors, models, providers, telemetry, ui, util
+from . import errors, experimental_telemetry, models, providers, ui, util
 from .agents import (
     Agent,
     AgentTool,
@@ -181,6 +181,7 @@
     "deferred_tool_result",
     "errors",
     "events",
+    "experimental_telemetry",
     "file_part",
     "get_hook_registry",
     "get_model",
@@ -195,7 +196,6 @@
     "resolve_hook",
     "stream",
     "system_message",
-    "telemetry",
     "text_part",
     "thinking",
     "tool",

src/ai/agents/agent.py

@@ -35,7 +35,8 @@
 # Use the typing_extensions backport so this works on 3.12 too.
 from typing_extensions import TypeVar
 
-from .. import models, telemetry, type_utils, types, util
+from .. import experimental_telemetry as telemetry
+from .. import models, type_utils, types, util
 from ..types import builders
 from ..types import events as events_
 from ..types.messages import MessageBundle

src/ai/agents/hooks.py

@@ -26,7 +26,8 @@
 
 import pydantic
 
-from .. import telemetry, types, util
+from .. import experimental_telemetry as telemetry
+from .. import types, util
 from ..types import messages as messages_
 from . import _middleware as middleware_
 from . import runtime as runtime_

src/ai/telemetry/__init__.py src/ai/experimental_telemetry/__init__.pysrc/ai/telemetry/__init__.py renamed to src/ai/experimental_telemetry/__init__.py

@@ -1,5 +1,7 @@
 """Telemetry: spans, adapters, and the ambient current span.
 
+Experimental: not part of the stable API, may change or be removed.
+
 See :mod:`.span` for the full story.
 """
 

src/ai/telemetry/otel.py src/ai/experimental_telemetry/otel.pysrc/ai/telemetry/otel.py renamed to src/ai/experimental_telemetry/otel.py

@@ -1,8 +1,10 @@
 """OpenTelemetry adapter: forwards spans to an otel tracer.
 
+Experimental: not part of the stable API, may change or be removed.
+
 ::
 
-    from ai.telemetry import otel
+    from ai.experimental_telemetry import otel
     otel.install()  # uses the global TracerProvider
 
 Span names and attributes follow the ``gen_ai`` semantic conventions,
@@ -22,7 +24,8 @@
 import json
 from typing import TYPE_CHECKING, Any
 
-from .. import errors, telemetry
+from .. import errors
+from .. import experimental_telemetry as telemetry
 
 try:
     from opentelemetry import context as otel_context

src/ai/telemetry/span.py src/ai/experimental_telemetry/span.pysrc/ai/telemetry/span.py renamed to src/ai/experimental_telemetry/span.py

@@ -1,11 +1,13 @@
 """Telemetry: spans, adapters, and the ambient current span.
 
+Experimental: not part of the stable API, may change or be removed.
+
 :class:`Span` is a record of work done by the application. It carries
 start, end, parent, and typed data.
 
 Same API is used to instrument the framework and define custom spans::
 
-    async with ai.telemetry.span("retrieval", query=q) as sp:
+    async with ai.experimental_telemetry.span("retrieval", query=q) as sp:
         docs = await search(q)
         sp.set(count=len(docs))
 
@@ -19,7 +21,7 @@ async def on_span_start(self, span): ...
         async def on_span_end(self, span): ...
         async def on_span_event(self, span, event): ...
 
-    ai.telemetry.register(MyAdapter())
+    ai.experimental_telemetry.register(MyAdapter())
 
 Adapters dispatch on the type of ``span.data``.  An adapter that crashes
 is logged and skipped, it never kills the run.
@@ -97,13 +99,13 @@ def use_clock(now_ns: Callable[[], int]) -> Iterator[None]:
     used to plug an approved clock function in durable execution
     settings::
 
-        with ai.telemetry.use_clock(workflow.time_ns):
+        with ai.experimental_telemetry.use_clock(workflow.time_ns):
             ...  # spans opened here read time from workflow.time_ns
 
     This can also be used as a decorator on both sync and async
     functions::
 
-        @ai.telemetry.use_clock(clock.time_ns)
+        @ai.experimental_telemetry.use_clock(clock.time_ns)
         async def run(...):
             ...
     """
@@ -131,7 +133,8 @@ class RetrievalSpanData:
 
             span_name: ClassVar[str] = "retrieval"
 
-        async with ai.telemetry.span(RetrievalSpanData(query=q)) as sp:
+        data = RetrievalSpanData(query=q)
+        async with ai.experimental_telemetry.span(data) as sp:
             docs = await search(q)
             sp.data.count = len(docs)  # typed
 
@@ -289,12 +292,12 @@ class SpanRef(pydantic.BaseModel):
     (``model_dump`` / ``model_validate``); restore by opening a span
     with ``parent=ref`` on the other side::
 
-        ref = ai.telemetry.current_ref()
+        ref = ai.experimental_telemetry.current_ref()
         job = {"task": task, "telemetry": ref.model_dump()}
 
         # elsewhere:
-        ref = ai.telemetry.SpanRef.model_validate(job["telemetry"])
-        async with ai.telemetry.span("pickup", parent=ref):
+        ref = ai.experimental_telemetry.SpanRef.model_validate(job["telemetry"])
+        async with ai.experimental_telemetry.span("pickup", parent=ref):
             ...  # everything inside continues the original trace
 
     ``sampled`` is carried so refs round-trip sampling decisions
@@ -685,7 +688,7 @@ async def vendor(span):
                     v.log_event(ev.name, timestamp=ev.time_ns)
                 v.update(output=span.data)           # span end
 
-        ai.telemetry.register(vendor)
+        ai.experimental_telemetry.register(vendor)
 
     - A span that ends with an error is thrown into the generator at
       the ``yield``, so the vendor context manager sees the failure.

src/ai/experimental_telemetry/utils/__init__.py

@@ -0,0 +1,8 @@
+"""Debugging helpers: the console adapter and the terminal trace viewer.
+
+Experimental: not part of the stable API, may change or be removed.
+
+Import the submodules directly::
+
+    from ai.experimental_telemetry.utils import console
+"""

src/ai/telemetry/utils/console.py …/experimental_telemetry/utils/console.pysrc/ai/telemetry/utils/console.py renamed to src/ai/experimental_telemetry/utils/console.py src/ai/telemetry/utils/console.py renamed to src/ai/experimental_telemetry/utils/console.py

@@ -1,9 +1,11 @@
 """Console adapter: prints spans to a terminal as they happen.
 
+Experimental: not part of the stable API, may change or be removed.
+
 Register it like any adapter::
 
-    from ai.telemetry.utils import console
-    ai.telemetry.register(console.ConsoleAdapter())
+    from ai.experimental_telemetry.utils import console
+    ai.experimental_telemetry.register(console.ConsoleAdapter())
 
 Prints one ``▸`` line when a span starts (so long runs are visible
 live) and, when a trace's root span ends, the whole tree with
@@ -15,7 +17,7 @@
 import sys
 from typing import TYPE_CHECKING
 
-from ... import telemetry
+from ... import experimental_telemetry as telemetry
 
 if TYPE_CHECKING:
     from typing import TextIO

src/ai/telemetry/utils/viewer.py …i/experimental_telemetry/utils/viewer.pysrc/ai/telemetry/utils/viewer.py renamed to src/ai/experimental_telemetry/utils/viewer.py src/ai/telemetry/utils/viewer.py renamed to src/ai/experimental_telemetry/utils/viewer.py

@@ -1,8 +1,10 @@
 """Terminal trace viewer: an OTLP/HTTP server that prints span trees.
 
+Experimental: not part of the stable API, may change or be removed.
+
 Run::
 
-    python -m ai.telemetry.utils.viewer [--port 4318]
+    python -m ai.experimental_telemetry.utils.viewer [--port 4318]
 
 and point any OTLP/HTTP exporter at ``http://127.0.0.1:4318/v1/traces``::
 
@@ -18,7 +20,7 @@
         BatchSpanProcessor(OTLPSpanExporter("http://127.0.0.1:4318/v1/traces"))
     )
     trace.set_tracer_provider(provider)
-    ai.telemetry.otel.install()
+    ai.experimental_telemetry.otel.install()
 
 Spans are buffered per trace, and the tree is printed when the trace's
 root span arrives (roots end — and therefore export — last).