otelzero 0.2.0__py3-none-any.whl

otelzero/hooks/microsoft.py

@@ -0,0 +1,160 @@
+"""Microsoft Agent Framework instrumentation: switch on its *own* OpenTelemetry.
+
+Microsoft's `Agent Framework <https://github.com/microsoft/agent-framework>`_
+(the ``agent-framework`` package that unifies Semantic Kernel and AutoGen)
+ships OpenTelemetry instrumentation in the GenAI semantic conventions. Each
+``Agent.run`` (streaming or not) gets an ``invoke_agent {name}`` span, with
+``chat {model}`` and ``execute_tool {tool}`` spans from its chat client and
+function-invocation layers. The span carries ``gen_ai.agent.*``,
+``gen_ai.provider.name``, ``gen_ai.tool.definitions``, ``gen_ai.usage.*`` and,
+when sensitive data is enabled, ``gen_ai.input.messages`` /
+``gen_ai.output.messages`` / ``gen_ai.system_instructions``. That is more
+than a wrapper around ``Agent.run`` could see, so this hook wraps nothing.
+Instead it:
+
+* configures otelzero's OTLP provider as the global one, which is where
+  Agent Framework's tracer sends its spans, so they export to
+  ``{server_url}/v1/traces``;
+* keeps Agent Framework on the latest GenAI conventions (its default), even
+  when ``OTEL_SEMCONV_STABILITY_OPT_IN`` is set for another library;
+* calls ``agent_framework.observability.enable_instrumentation``, with
+  ``enable_sensitive_data`` following otelzero's content opt-in
+  (``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT``), so prompts and
+  completions are never exported by accident;
+* attaches the shared :class:`~otelzero.hooks._native.NativeRunProcessor`,
+  which stamps otelzero's run identity on every Agent Framework span and turns
+  each ``invoke_agent`` span into ``agent_start`` / ``agent_end`` /
+  ``agent_error``.
+
+If the application called ``disable_instrumentation()``, that choice is kept,
+and this hook says so instead of overriding it. ``agent_framework`` may be
+imported before or after the install call. The ``otel`` extra is required: the
+lifecycle events come from spans, so tracing is always on whatever
+``OTELZERO_OTEL`` says (it stays on even with ``OTELZERO_OTEL=0``).
+"""
+
+from typing import Optional
+
+from otelzero import otel, semconv
+from otelzero.hooks import _native
+from otelzero.telemetry import TelemetryClient
+
+FRAMEWORK = "Microsoft Agent Framework"
+
+# Agent Framework's tracer is ``get_tracer("agent_framework")``.
+_SCOPES = ("agent_framework",)
+
+
+_LATEST = "gen_ai_latest_experimental"
+
+
+def _keep_latest_conventions(settings) -> None:
+    """Keep Agent Framework on the GenAI conventions above v1.36.
+
+    That is its default, but only while ``OTEL_SEMCONV_STABILITY_OPT_IN`` is
+    unset. A value set for some other library's sake (``http``, say) and
+    lacking ``gen_ai_latest_experimental`` would drop it back to the baseline,
+    so the token is appended. The framework read the variable when it was
+    imported, so the change goes on its settings object rather than the
+    environment.
+    """
+    current = getattr(settings, "otel_semconv_stability_opt_in", None)
+    if not current:
+        return
+    tokens = [t.strip() for t in current.split(",") if t.strip()]
+    if _LATEST not in tokens:
+        settings.otel_semconv_stability_opt_in = ",".join([*tokens, _LATEST])
+
+
+def install_microsoft_monitoring(
+    server_url: str = "http://localhost:8000",
+    user: Optional[str] = None,
+    api_key: Optional[str] = None,
+    session: Optional[str] = None,
+    name: Optional[str] = None,
+) -> TelemetryClient:
+    """
+    Install Microsoft Agent Framework monitoring via its native OpenTelemetry.
+
+    Points Agent Framework's own spans at ``{server_url}/v1/traces`` (or at
+    ``OTEL_EXPORTER_OTLP_ENDPOINT`` when set), enables its instrumentation,
+    and sends ``agent_start`` and ``agent_end`` (or ``agent_error``) for each
+    run, built from its ``invoke_agent`` span. May be called before or after
+    ``agent_framework`` is imported, but requires the ``otel`` extra.
+
+    Args:
+        server_url: URL of the monitoring server
+        user: Name of the executing user
+        api_key: Ingest key tying events to an owner (for the iOS app)
+        session: Per-run id used to group events in the app; exported on every
+            span as ``gen_ai.conversation.id``
+        name: Session title shown on the dashboard and apps. Agent
+            Framework's spans carry no prompt when a run starts, so no title is
+            derived when this is omitted. Pass it here or per run with
+            ``run_context(name=...)``.
+
+    Raises:
+        ImportError: ``agent_framework`` is not installed.
+        RuntimeError: the OpenTelemetry SDK (the ``otel`` extra) is missing.
+    """
+    try:
+        from agent_framework import observability
+    except ImportError as exc:  # pragma: no cover - exercised by hand
+        raise ImportError(
+            "install_microsoft_monitoring needs agent_framework importable: "
+            "uv pip install agent-framework"
+        ) from exc
+
+    telemetry = TelemetryClient(
+        server_url,
+        framework=FRAMEWORK,
+        user=user,
+        api_key=api_key,
+        session=session,
+        name=name,
+    )
+    provider = _native.start_tracing(FRAMEWORK, telemetry, server_url)
+    _native.attach_processor(
+        _native.global_provider(provider, FRAMEWORK),
+        telemetry,
+        framework=FRAMEWORK,
+        scopes=_SCOPES,
+        default_agent_name="Microsoft Agent",
+    )
+
+    observability.enable_instrumentation(
+        enable_sensitive_data=semconv.capture_content_enabled()
+    )
+    settings = getattr(observability, "OBSERVABILITY_SETTINGS", None)
+    _keep_latest_conventions(settings)
+    if settings is not None and not getattr(settings, "enable_instrumentation", True):
+        print(
+            f"[MONITOR] {FRAMEWORK}: instrumentation was disabled by the "
+            "application (disable_instrumentation()); no runs will be reported."
+        )
+
+    print(
+        f"[MONITOR] {FRAMEWORK} monitoring installed via native OpenTelemetry "
+        f"(server: {server_url})"
+    )
+    return telemetry
+
+
+def uninstall_microsoft_monitoring() -> None:
+    """Stop stamping identity and sending events; switch the tracing back off.
+
+    Uses the settings object rather than ``disable_instrumentation()``. That
+    call records an explicit user opt-out, which later
+    ``enable_instrumentation()`` calls (a reinstall included) would respect.
+    """
+    from opentelemetry import trace
+
+    _native.detach(FRAMEWORK, otel._provider)
+    _native.detach(FRAMEWORK, trace.get_tracer_provider())
+    try:
+        from agent_framework import observability
+    except ImportError:  # pragma: no cover
+        return
+    settings = getattr(observability, "OBSERVABILITY_SETTINGS", None)
+    if settings is not None:
+        settings.enable_instrumentation = False

otelzero/hooks/openai_agents.py

@@ -0,0 +1,313 @@
+"""OpenAI Agents SDK instrumentation: wrap the Runner's run chokepoints.
+
+The `OpenAI Agents SDK <https://github.com/openai/openai-agents-python>`_ (the
+``openai-agents`` package, OpenAI's production successor to the archived Swarm)
+starts every run through one of three ``Runner`` classmethods:
+
+* ``Runner.run(agent, input)`` -- the async entry point,
+* ``Runner.run_sync(agent, input)`` -- the blocking wrapper around it,
+* ``Runner.run_streamed(agent, input)`` -- which returns a ``RunResultStreaming``
+  synchronously and delivers the run through its ``stream_events()`` generator.
+
+All three are wrapped, because callers use each directly. ``run_sync`` drives
+``run`` on some versions and an internal runner on others, so a nesting guard
+keeps a run that passes through both from being reported twice.
+
+With content capture opted in, a run also records its input, the agent's
+instructions when they are a plain string, and its output: every item the run
+produced, so tool calls and their results appear alongside the final answer.
+"""
+
+from contextlib import contextmanager
+from typing import Any, Optional
+
+import wrapt
+
+from otelzero import semconv
+from otelzero.hooks import _content
+from otelzero.hooks._usage import extract_usage
+from otelzero.hooks.base import (
+    _ImportInstrumenter,
+    install_hook,
+    nesting_guard,
+    trace_agent_run,
+)
+
+# ``run_sync`` drives ``run`` on some SDK versions; only the outer call traces.
+_outermost = nesting_guard("openai_agents")
+
+# otelzero's own marker so a chokepoint is never wrapped twice.
+_MARKER = "_otelzero_wrapped"
+
+
+def _agents_model_id(agent: Any) -> Optional[str]:
+    """Best-effort model identifier for an OpenAI Agents SDK ``Agent``.
+
+    ``Agent.model`` is ``str | Model | None``: a bare model name, a model object
+    whose name hides under one of a couple of attributes, or ``None`` to take the
+    runner's default. Falls back to the model class name so a run is never
+    labelled with nothing when a model object is set.
+    """
+    model = getattr(agent, "model", None)
+    if model is None or model == "":
+        return None
+    if isinstance(model, str):
+        return model
+    for attr in ("model", "model_name"):
+        name = getattr(model, attr, None)
+        if isinstance(name, str) and name:
+            return name
+    return type(model).__name__
+
+
+def _names(items) -> list:
+    """Readable names for a list of tools or handoff targets."""
+    names = []
+    for item in items or []:
+        for attr in ("name", "agent_name", "tool_name"):
+            value = getattr(item, attr, None)
+            if isinstance(value, str) and value:
+                names.append(value)
+                break
+    return names
+
+
+def _agent_details(agent: Any) -> dict:
+    """Summarise the starting agent for a telemetry ``details`` payload."""
+    return {
+        "model": _agents_model_id(agent),
+        "tools": _names(getattr(agent, "tools", None)),
+        "handoffs": _names(getattr(agent, "handoffs", None)),
+    }
+
+
+def _agents_input_text(args, kwargs) -> Optional[str]:
+    """Best-effort intent text from a run's ``input``, to name the session.
+
+    ``input`` is either the user's prompt as a plain string or a list of input
+    items, in which case the last one carries the turn being answered. Items are
+    dicts (``{"role", "content"}``) or objects with a ``content`` attribute.
+    """
+    # Called through the classmethod, so args is (starting_agent, input, ...).
+    value = kwargs.get("input", args[1] if len(args) > 1 else None)
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (list, tuple)) and value:
+        last = value[-1]
+        content = (
+            last.get("content")
+            if isinstance(last, dict)
+            else getattr(last, "content", None)
+        )
+        if isinstance(content, str) and content:
+            return content
+    return None
+
+
+def _output_messages(result: Any) -> Any:
+    """A run's output: the items it produced, else its final output as text.
+
+    ``None`` unless content capture is opted in. ``new_items`` holds each model
+    message, tool call and tool result; ``to_input_item`` is the SDK's own
+    conversion of one into a Responses API item, which ``messages_from`` reads.
+    """
+    if not _content.enabled():
+        return None
+    try:
+        items = [item.to_input_item() for item in getattr(result, "new_items", None) or []]
+        messages = _content.messages_from(items, default_role="assistant") if items else None
+    except Exception:
+        messages = None
+    return messages or _content.text_of(getattr(result, "final_output", None))
+
+
+def _result_usage(result: Any) -> Optional[dict]:
+    """Normalized token usage off a ``RunResult`` / ``RunResultStreaming``.
+
+    The SDK accumulates a run's usage on the shared run context rather than on
+    the result itself, so read through ``context_wrapper`` first and fall back to
+    a ``usage`` attribute for versions that expose one directly.
+    """
+    wrapper = getattr(result, "context_wrapper", None)
+    usage = extract_usage(getattr(wrapper, "usage", None))
+    if usage is None:
+        usage = extract_usage(getattr(result, "usage", None))
+    return usage
+
+
+class _TracedRunResultStreaming(wrapt.ObjectProxy):
+    """Proxy a ``RunResultStreaming`` to trace its ``stream_events()`` pass.
+
+    ``run_streamed`` returns immediately, and the run is delivered as the caller
+    iterates ``stream_events()``. Only that method is overridden -- every other
+    attribute (``final_output``, ``new_items``, ``context_wrapper``) reaches the
+    real object untouched -- so the span covers exactly the streaming pass, as
+    the Microsoft Agent Framework hook does for its ``ResponseStream``.
+    """
+
+    def __init__(self, wrapped, cm_factory):
+        super().__init__(wrapped)
+        self._self_cm_factory = cm_factory
+
+    async def stream_events(self, *args, **kwargs):
+        with self._self_cm_factory() as run:
+            try:
+                async for event in self.__wrapped__.stream_events(*args, **kwargs):
+                    yield event
+            finally:
+                # Usage accumulates on the run context as events arrive, so the
+                # final read covers the whole stream -- including a consumer that
+                # broke out early, whose partial usage is still worth reporting.
+                run.set_usage(_result_usage(self.__wrapped__))
+                run.set_output(_output_messages(self.__wrapped__))
+
+
+def _wrap_classmethod(cls, name: str, decorator) -> None:
+    """Wrap a classmethod in place, leaving it a classmethod.
+
+    The decorator goes on the ``classmethod`` object itself, not on its
+    ``__func__``: wrapt's proxy then *is* the descriptor and binds ``cls`` off
+    the arguments itself. Re-wrapping a decorated function as
+    ``classmethod(deco(fn))`` instead relies on classmethod descriptor
+    chaining, which Python 3.13 removed -- there ``cls`` leaks in as the first
+    positional argument and every run is attributed to the ``Runner`` class.
+    Missing or already-wrapped methods are skipped, which is what makes
+    installing this hook twice harmless.
+    """
+    raw = cls.__dict__.get(name)
+    if raw is None:
+        return
+    func = raw.__func__ if isinstance(raw, (classmethod, staticmethod)) else raw
+    if getattr(func, _MARKER, False):
+        return
+    wrapped = decorator(raw)
+    setattr(func, _MARKER, True)
+    setattr(cls, name, wrapped)
+
+
+class OpenAIAgentsImportHook(_ImportInstrumenter):
+    """Intercept OpenAI Agents SDK imports and instrument ``Runner``.
+
+    Wraps ``agents.run.Runner``'s ``run``, ``run_sync`` and ``run_streamed`` --
+    the three documented ways to start a run -- so each is captured exactly once.
+    The SDK's own tracing is unaffected and its spans nest under otelzero's agent
+    span (tracing is on by default).
+    """
+
+    WATCHED = {"agents.run": "_wrap_runner_class"}
+
+    def _wrap_runner_class(self, module):
+        runner = getattr(module, "Runner", None)
+        if runner is None:
+            return
+
+        telemetry = self.telemetry
+
+        @contextmanager
+        def _traced(args, kwargs):
+            """Trace one run, recording its prompt as soon as it opens."""
+            agent = kwargs.get("starting_agent", args[0] if args else None)
+            agent_name = getattr(agent, "name", None) or "OpenAI Agent"
+            details = _agent_details(agent)
+            with trace_agent_run(
+                telemetry,
+                semconv.span_name(semconv.OP_INVOKE_AGENT, agent_name),
+                {
+                    semconv.GEN_AI_OPERATION_NAME: semconv.OP_INVOKE_AGENT,
+                    semconv.GEN_AI_AGENT_NAME: agent_name,
+                    semconv.GEN_AI_REQUEST_MODEL: details["model"],
+                    semconv.GEN_AI_TOOL_DEFINITIONS: semconv.tool_definitions(
+                        details["tools"]
+                    ),
+                },
+                start_event="agent_start",
+                end_event="agent_end",
+                error_event="agent_error",
+                log_fields={
+                    "agent_name": agent_name,
+                    "agent_role": agent_name,
+                    "model": details["model"],
+                },
+                start_details=details,
+                session_name_hint=_agents_input_text(args, kwargs),
+            ) as run:
+                run.set_input(
+                    _content.messages_from(
+                        kwargs.get("input", args[1] if len(args) > 1 else None)
+                    )
+                )
+                instructions = getattr(agent, "instructions", None)
+                if isinstance(instructions, str):
+                    run.set_system(instructions)
+                yield run
+
+        @wrapt.decorator
+        async def run_wrapper(wrapped, instance, args, kwargs):
+            with _outermost() as outermost:
+                if not outermost:
+                    return await wrapped(*args, **kwargs)
+                with _traced(args, kwargs) as run:
+                    result = await wrapped(*args, **kwargs)
+                    run.set_usage(_result_usage(result))
+                    run.set_output(_output_messages(result))
+                    return result
+
+        @wrapt.decorator
+        def run_sync_wrapper(wrapped, instance, args, kwargs):
+            with _outermost() as outermost:
+                if not outermost:
+                    return wrapped(*args, **kwargs)
+                with _traced(args, kwargs) as run:
+                    result = wrapped(*args, **kwargs)
+                    run.set_usage(_result_usage(result))
+                    run.set_output(_output_messages(result))
+                    return result
+
+        @wrapt.decorator
+        def run_streamed_wrapper(wrapped, instance, args, kwargs):
+            result = wrapped(*args, **kwargs)
+            # ``run_streamed`` is synchronous: it hands back the streaming result
+            # and the run is delivered as the caller iterates it, so the span is
+            # opened there rather than here.
+            return _TracedRunResultStreaming(result, lambda: _traced(args, kwargs))
+
+        for method_name, decorator in (
+            ("run", run_wrapper),
+            ("run_sync", run_sync_wrapper),
+            ("run_streamed", run_streamed_wrapper),
+        ):
+            _wrap_classmethod(runner, method_name, decorator)
+
+
+def install_openai_agents_monitoring(
+    server_url: str = "http://localhost:8000",
+    user: Optional[str] = None,
+    api_key: Optional[str] = None,
+    session: Optional[str] = None,
+    name: Optional[str] = None,
+):
+    """
+    Install OpenAI Agents SDK monitoring instrumentation.
+
+    Instruments ``agents.run.Runner.run``, ``Runner.run_sync`` and
+    ``Runner.run_streamed`` -- the three documented ways to start a run -- so
+    every run streams start/end/error telemetry with zero changes to the agent
+    code. Call this *before* ``agents`` is imported.
+
+    Args:
+        server_url: URL of the monitoring server
+        user: Name of the executing user
+        api_key: Ingest key tying events to an owner (for the iOS app)
+        session: Per-run id used to group events in the app
+        name: Explicit session title (else derived from the run's input)
+    """
+    return install_hook(
+        OpenAIAgentsImportHook,
+        framework="OpenAI Agents",
+        label="OpenAI Agents SDK",
+        server_url=server_url,
+        user=user,
+        api_key=api_key,
+        session=session,
+        name=name,
+    )

otelzero/hooks/pydantic_ai.py

@@ -0,0 +1,173 @@
+"""Pydantic AI instrumentation: switch on the framework's *own* OpenTelemetry.
+
+`Pydantic AI <https://ai.pydantic.dev>`_ ships first-party OpenTelemetry
+instrumentation (``Agent.instrument_all`` / ``InstrumentationSettings``) that
+already follows the GenAI semantic conventions: one ``invoke_agent {name}`` span
+per run with ``chat`` and ``execute_tool`` children, ``gen_ai.*`` attributes and
+Opt-In message content. That is richer than anything a wrapper around
+``Agent.run`` can see from the outside, so this hook does not wrap anything.
+Instead it points the native instrumentation at the registry's OTLP receiver and
+adds one span processor that
+
+* stamps otelzero's run identity -- ``gen_ai.conversation.id``, ``user.name``
+  and ``otelzero.session.name`` -- onto every span, and
+* turns each native ``invoke_agent`` span into the same ``agent_start`` /
+  ``agent_end`` / ``agent_error`` HTTP events the wrapping hooks send, so the
+  dashboard's event feed is unchanged.
+
+The processor is shared with the other native-OTel hooks (Strands, Agent
+Framework, ADK); see :mod:`otelzero.hooks._native`.
+
+Compared to the import-hook frameworks there is no ``sys.meta_path`` finder --
+``pydantic_ai`` is imported eagerly, so it may be imported before or after the
+install call -- and the ``otel`` extra is required: the lifecycle events are
+derived from spans, so tracing stays on even with ``OTELZERO_OTEL=0``.
+
+Pydantic AI sets its own ``gen_ai.conversation.id`` -- a fresh id per run, since
+nothing ties two runs together for it. otelzero's session is exactly that tie,
+so the processor overwrites it with the session id (from
+:func:`otelzero.context.run_context` when one is active, else the client's).
+
+What the events can carry is bounded by what Pydantic AI puts on its spans: the
+tool list and token usage are known only when the run ends, and an
+``agent_error`` names the exception *type* unless content capture is on, which
+is when Pydantic AI also records the message and traceback.
+"""
+
+from typing import Any, Optional
+
+from otelzero import otel, semconv
+from otelzero.hooks import _native
+from otelzero.telemetry import TelemetryClient
+
+FRAMEWORK = "Pydantic AI"
+
+# The provider attribute holding this hook's processor (see
+# :func:`otelzero.hooks._native.attach_processor`).
+_PROCESSOR_MARKER = _native.marker(FRAMEWORK)
+
+# Pydantic AI's tracer is named after the package.
+_SCOPES = ("pydantic-ai", "pydantic_ai")
+
+# Kept under their old names: the span parsing is now shared with the other
+# native-OTel hooks.
+_usage_from = _native.usage_from
+_tool_names = _native.tool_names
+_exception = _native.exception_of
+
+
+def _native_settings(provider: Any, include_content: bool) -> Any:
+    """Build Pydantic AI's ``InstrumentationSettings`` against our provider.
+
+    ``include_content`` follows the same opt-in as every other hook
+    (``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT``), so prompts and completions are never
+    exported by accident. Binary content stays off regardless: an image in a
+    prompt would otherwise be base64-encoded into a span attribute. ``version``
+    is pinned so an upgrade of Pydantic AI cannot silently change the span
+    shape the dashboard parses.
+    """
+    from pydantic_ai.models.instrumented import InstrumentationSettings
+
+    return InstrumentationSettings(
+        tracer_provider=provider,
+        include_content=include_content,
+        include_binary_content=False,
+        version=5,
+    )
+
+
+def install_pydantic_ai_monitoring(
+    server_url: str = "http://localhost:8000",
+    user: Optional[str] = None,
+    api_key: Optional[str] = None,
+    session: Optional[str] = None,
+    name: Optional[str] = None,
+    *,
+    settings: Any = None,
+) -> TelemetryClient:
+    """
+    Install Pydantic AI monitoring via the framework's native OpenTelemetry.
+
+    Configures a tracer provider exporting OTLP/HTTP to ``{server_url}/v1/traces``
+    (or to ``OTEL_EXPORTER_OTLP_ENDPOINT`` when set), then calls
+    ``Agent.instrument_all`` so every agent -- existing or created later --
+    emits Pydantic AI's own ``invoke_agent`` / ``chat`` / ``execute_tool`` spans
+    through it. Each run also sends ``agent_start`` and ``agent_end`` (or
+    ``agent_error``) to the server, built from those spans. Unlike the
+    import-hook frameworks, this may be called before or after ``pydantic_ai``
+    is imported, but it requires the ``otel`` extra.
+
+    Args:
+        server_url: URL of the monitoring server
+        user: Name of the executing user
+        api_key: Ingest key tying events to an owner (for the iOS app)
+        session: Per-run id used to group events in the app; exported on every
+            span as ``gen_ai.conversation.id``
+        name: Session title shown on the dashboard and apps; sent on every
+            event and exported on every span as ``otelzero.session.name``.
+            Pydantic AI's spans carry no prompt at run start, so unlike the
+            wrapping hooks no title is derived when this is omitted --
+            pass it here or per run via ``run_context(name=...)``.
+        settings: A ready-made ``InstrumentationSettings`` to pass through
+            unchanged, for callers who want a different format ``version`` or
+            content policy. Its ``tracer_provider`` should be left unset so it
+            exports through the provider configured here.
+
+    Raises:
+        ImportError: ``pydantic_ai`` is not installed.
+        RuntimeError: the OpenTelemetry SDK (the ``otel`` extra) is missing,
+            which leaves this hook with no way to report anything.
+    """
+    try:
+        from pydantic_ai import Agent
+    except ImportError as exc:  # pragma: no cover - exercised by hand
+        raise ImportError(
+            "install_pydantic_ai_monitoring needs pydantic_ai importable: "
+            "uv pip install pydantic-ai"
+        ) from exc
+
+    # The home of the run identity (user / session / title, honouring
+    # run_context), of framework-version detection, and of the HTTP channel the
+    # lifecycle events go out on.
+    telemetry = TelemetryClient(
+        server_url,
+        framework=FRAMEWORK,
+        user=user,
+        api_key=api_key,
+        session=session,
+        name=name,
+    )
+    provider = _native.start_tracing(FRAMEWORK, telemetry, server_url)
+    # Pydantic AI is handed this provider explicitly (below), so the processor
+    # goes on it rather than on whatever provider is global.
+    _native.attach_processor(
+        provider,
+        telemetry,
+        framework=FRAMEWORK,
+        scopes=_SCOPES,
+        default_agent_name="Pydantic AI Agent",
+    )
+
+    if settings is None:
+        settings = _native_settings(provider, semconv.capture_content_enabled())
+    Agent.instrument_all(settings)
+
+    print(
+        f"[MONITOR] {FRAMEWORK} monitoring installed via native OpenTelemetry "
+        f"(server: {server_url})"
+    )
+    return telemetry
+
+
+def uninstall_pydantic_ai_monitoring() -> None:
+    """Stop stamping identity and sending events; switch Pydantic AI's tracing off.
+
+    The provider keeps exporting (a provider cannot drop a processor, and other
+    hooks may share it); only this hook's contributions stop.
+    """
+    _native.detach(FRAMEWORK, otel._provider)
+    try:
+        from pydantic_ai import Agent
+    except ImportError:  # pragma: no cover
+        return
+    Agent.instrument_all(False)