otelzero 0.2.0__py3-none-any.whl

otelzero/hooks/adk.py

@@ -0,0 +1,128 @@
+"""Google ADK instrumentation: switch on the framework's *own* OpenTelemetry.
+
+`Google ADK <https://github.com/google/adk-python>`_ always traces itself
+through the global OpenTelemetry tracer provider, in the GenAI semantic
+conventions. A ``Runner`` run opens an ``invoke_workflow {app}`` span. Each
+agent that takes a turn gets an ``invoke_agent {name}`` span under it, with
+``generate_content {model}`` and ``execute_tool {tool}`` spans nested inside.
+That is more than a wrapper around ``Runner.run_async`` could see, so this hook
+wraps nothing. Instead it:
+
+* configures otelzero's OTLP provider as the global one, so ADK's spans export
+  to ``{server_url}/v1/traces``;
+* opts ADK into the latest GenAI conventions (``gen_ai_latest_experimental``
+  in ``OTEL_SEMCONV_STABILITY_OPT_IN``), which replace ADK's legacy
+  ``gcp.vertex.agent.*`` payload attributes with ``gen_ai.input.messages`` /
+  ``gen_ai.output.messages`` / ``gen_ai.tool.call.*``;
+* attaches the shared :class:`~otelzero.hooks._native.NativeRunProcessor`,
+  which stamps ``user.name`` and ``otelzero.session.name`` on every ADK span
+  and turns each ``invoke_agent`` span into ``agent_start`` / ``agent_end`` /
+  ``agent_error``. A multi-agent run reports each agent that takes a turn.
+
+**Session.** ADK writes its own session id as ``gen_ai.conversation.id`` on
+its spans, and it does so after each span starts, so the id can't be replaced
+there. It is also the right value: an ADK session *is* the conversation, and
+the caller chooses it. So for ADK the dashboard groups runs by ADK's session
+id. The events are filed under it too, so spans and events line up, and the
+``session=`` argument and ``run_context(conversation_id=...)`` don't apply.
+
+**Content.** ADK follows the standard
+``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` variable on its own
+terms. ``true`` / ``1`` mean ``EVENT_ONLY`` there, so prompts go to log records,
+not spans. ``SPAN_ONLY`` or ``SPAN_AND_EVENT`` puts them on span attributes,
+where the registry reads them. Unset, no content is recorded.
+
+``google.adk`` 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 even with ``OTELZERO_OTEL=0``.
+"""
+
+from typing import Optional
+
+from otelzero import otel
+from otelzero.hooks import _native
+from otelzero.telemetry import TelemetryClient
+
+FRAMEWORK = "Google ADK"
+
+# ADK's tracer is ``trace.get_tracer("gcp.vertex.agent")``.
+_SCOPES = ("gcp.vertex.agent", "google.adk")
+
+_LATEST = "gen_ai_latest_experimental"
+
+def install_adk_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 Google ADK monitoring via the framework's native OpenTelemetry.
+
+    Points ADK's own spans at ``{server_url}/v1/traces`` (or at
+    ``OTEL_EXPORTER_OTLP_ENDPOINT`` when set), opts them into the latest GenAI
+    semantic conventions, and sends ``agent_start`` and ``agent_end`` (or
+    ``agent_error``) for each agent turn, built from its ``invoke_agent``
+    span. May be called before or after ``google.adk`` 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: Fallback session id, used only for a run whose spans carry
+            no ADK session id; ADK's own session id groups runs otherwise
+        name: Session title shown on the dashboard and apps (no title is
+            derived from the prompt)
+
+    Raises:
+        ImportError: ``google.adk`` is not installed.
+        RuntimeError: the OpenTelemetry SDK (the ``otel`` extra) is missing.
+    """
+    try:
+        import google.adk  # noqa: F401
+    except ImportError as exc:  # pragma: no cover - exercised by hand
+        raise ImportError(
+            "install_adk_monitoring needs google.adk importable: "
+            "uv pip install google-adk"
+        ) 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="ADK Agent",
+        native_conversation_id=True,
+    )
+    # ADK reads the variable per invocation, so no refresh is needed.
+    _native.opt_in_tokens(FRAMEWORK, [_LATEST])
+
+    print(
+        f"[MONITOR] {FRAMEWORK} monitoring installed via native OpenTelemetry "
+        f"(server: {server_url})"
+    )
+    return telemetry
+
+
+def uninstall_adk_monitoring() -> None:
+    """Stop stamping identity and sending events; drop the opt-in tokens it added.
+
+    ADK keeps tracing through the global provider, since that's how it always
+    works. Only this hook's contributions stop.
+    """
+    from opentelemetry import trace
+
+    _native.detach(FRAMEWORK, otel._provider)
+    _native.detach(FRAMEWORK, trace.get_tracer_provider())
+    _native.release_opt_in(FRAMEWORK)

otelzero/hooks/base.py

@@ -0,0 +1,546 @@
+"""Shared import-hook machinery and telemetry helpers for framework hooks.
+
+This module holds everything the per-framework hooks (``crewai``, ``langchain``,
+``strands``, ``adk``, ``databricks``) build on:
+
+* :class:`_ImportInstrumenter` / :class:`_InstrumentingLoader` -- the
+  ``sys.meta_path`` plumbing that instruments a watched module right after it is
+  imported. Subclasses only declare *which* modules to watch and *how* to wrap
+  them.
+* :func:`trace_agent_run` -- the span + start/end/error telemetry pattern every
+  ``_wrap_*`` method shares, factored into one context manager.
+* :func:`start_agent_run` / :class:`AgentRun` -- the same pattern for a framework
+  whose run entry point returns *before* the run finishes, so the terminal event
+  is emitted from wherever the run actually ends.
+* :func:`install_hook` -- the ``TelemetryClient`` + register boilerplate every
+  ``install_*_monitoring`` entry point shares.
+* :func:`nesting_guard` -- the re-entrancy guard hooks need when a framework's
+  public entry points call each other, or nest a run inside a run.
+"""
+
+import contextvars
+import importlib.abc
+import importlib.util
+import sys
+import traceback as tb
+from contextlib import contextmanager
+from typing import Dict, Optional
+
+from otelzero import otel, semconv
+from otelzero.hooks import _content
+from otelzero.telemetry import TelemetryClient
+
+
+class _InstrumentingLoader(importlib.abc.Loader):
+    """Defer to the real loader, then instrument the module once it executes."""
+
+    def __init__(self, loader, hook, fullname):
+        self._loader = loader
+        self._hook = hook
+        self._fullname = fullname
+
+    def create_module(self, spec):
+        return self._loader.create_module(spec)
+
+    def exec_module(self, module):
+        self._loader.exec_module(module)
+        self._hook._instrument_once(self._fullname, module)
+
+
+class _ImportInstrumenter(importlib.abc.MetaPathFinder):
+    """Base meta-path finder that instruments watched modules after import.
+
+    Uses the modern ``find_spec`` protocol (Python >= 3.12; the legacy
+    ``find_module`` protocol was removed in 3.12). It resolves the *real* spec
+    from the rest of ``sys.meta_path`` -- guarding against re-entrancy -- and wraps
+    its loader so the module is instrumented immediately after it executes.
+
+    Subclasses set :attr:`WATCHED`, a mapping of watched module name to the name
+    of the ``_wrap_*`` method that instruments it.
+    """
+
+    # module fullname -> name of the instance method that instruments it.
+    WATCHED: Dict[str, str] = {}
+
+    def __init__(self, telemetry_client: "TelemetryClient"):
+        self.telemetry = telemetry_client
+        self.instrumented_modules = set()
+        self._finding = set()
+
+    def _watches(self, fullname: str) -> bool:
+        return fullname in self.WATCHED
+
+    def _instrument_module(self, fullname, module):
+        getattr(self, self.WATCHED[fullname])(module)
+
+    def find_spec(self, fullname, path=None, target=None):
+        if not self._watches(fullname) or fullname in self._finding:
+            return None
+        # Re-enter the import machinery to find the real spec, guarding this
+        # name so our own finder is skipped on the recursive lookup.
+        self._finding.add(fullname)
+        try:
+            spec = importlib.util.find_spec(fullname)
+        except ImportError:
+            return None
+        finally:
+            self._finding.discard(fullname)
+        if spec is None or spec.loader is None:
+            return None
+        spec.loader = _InstrumentingLoader(spec.loader, self, fullname)
+        return spec
+
+    def _instrument_once(self, fullname, module):
+        if fullname not in self.instrumented_modules:
+            self._instrument_module(fullname, module)
+            self.instrumented_modules.add(fullname)
+            print(f"[INSTRUMENT] Instrumented {fullname}")
+
+
+class RunContext:
+    """Mutable handle a wrapper uses to attach data discovered during the run.
+
+    ``trace_agent_run`` yields one of these; a hook that finds token usage on
+    the framework's response (or accumulates it across a stream) calls
+    :meth:`set_usage` so the usage lands on the terminal telemetry event and
+    the OTel span. :meth:`set_model` does the same for the model id when the
+    framework only names it in the response.
+
+    :meth:`set_input` / :meth:`set_output` / :meth:`set_system` do the same for
+    the run's prompt, response and system prompt, which land as the Opt-In
+    ``gen_ai.input.messages`` / ``gen_ai.output.messages`` /
+    ``gen_ai.system_instructions`` span attributes and as ``input_messages`` /
+    ``output_messages`` / ``system_instructions`` in the terminal event's
+    ``details``. All three are no-ops unless the user opted in to content
+    capture (see :mod:`otelzero.hooks._content`).
+    """
+
+    __slots__ = (
+        "span",
+        "usage",
+        "model",
+        "input_messages",
+        "output_messages",
+        "system_instructions",
+        "finish_reasons",
+    )
+
+    def __init__(self, span):
+        self.span = span
+        self.usage: Optional[dict] = None
+        self.model: Optional[str] = None
+        self.input_messages: Optional[list] = None
+        self.output_messages: Optional[list] = None
+        self.system_instructions: Optional[list] = None
+        self.finish_reasons: Optional[list] = None
+
+    def set_usage(self, usage: Optional[dict]) -> None:
+        if usage:
+            self.usage = usage
+
+    def set_model(self, model: Optional[str]) -> None:
+        """Name the model a run turned out to use.
+
+        For hooks that cannot read the model off the agent before the run: a
+        LangGraph node closes over its chat model, so the graph exposes nothing
+        to read, but every reply message says which model produced it. The first
+        model reported wins, so one run mixing models is labelled by its first.
+        """
+        if model and not self.model:
+            self.model = model
+
+    def set_input(self, messages) -> None:
+        """Record the prompt: a shaped message list or plain text."""
+        messages = _content.as_messages(messages, "user")
+        if messages:
+            self.input_messages = messages
+
+    def set_output(self, messages, finish_reasons=None) -> None:
+        """Record the response: a shaped message list or plain text.
+
+        ``finish_reasons`` -- one normalised reason (see
+        ``_content.finish_reason``) or a list of them, one per generation the
+        framework reported -- becomes ``gen_ai.response.finish_reasons``, where
+        the conventions want it; the field an output message used to carry is
+        deprecated. It is recorded whether or not content capture is opted in,
+        and left unset when the framework named no reason.
+        """
+        if isinstance(finish_reasons, str):
+            finish_reasons = [finish_reasons]
+        if finish_reasons:
+            self.finish_reasons = [r for r in finish_reasons if r]
+        messages = _content.as_messages(messages, "assistant")
+        if messages:
+            self.output_messages = list(messages)
+
+    def set_system(self, parts) -> None:
+        """Record the system prompt: a shaped part list or plain text."""
+        parts = _content.as_parts(parts)
+        if parts:
+            self.system_instructions = parts
+
+
+def _with_identity(telemetry: "TelemetryClient", attributes: dict) -> dict:
+    """Stamp a span's attributes with who is running it and which flow it is.
+
+    Every hook opens its span through :func:`trace_agent_run`, so doing this in
+    one place keeps ``gen_ai.conversation.id`` and ``user.name`` on every otelzero
+    span across all frameworks, plus ``otelzero.session.name`` once the session
+    has a title. They are span-level rather than resource-level because one
+    process can serve many users and many concurrent flows.
+    """
+    user, session, session_name = telemetry.run_identity()
+    attrs = dict(attributes or {})
+    if session:
+        attrs[semconv.GEN_AI_CONVERSATION_ID] = session
+    if session_name:
+        attrs[semconv.OTELZERO_SESSION_NAME] = session_name
+    if user:
+        attrs[semconv.USER_NAME] = user
+    return attrs
+
+
+def _merge_run_details(details: Optional[dict], ctx: RunContext) -> Optional[dict]:
+    """The terminal event's ``details``: the hook's own plus what the run found.
+
+    Token usage and the run's finish reasons always ride along; message content
+    only when the user opted in -- the same switch that gates the span
+    attributes, so the HTTP and OTLP paths never disagree about what was
+    recorded.
+    """
+    extra = {}
+    if ctx.usage:
+        extra["usage"] = ctx.usage
+    if ctx.finish_reasons:
+        extra["finish_reasons"] = list(ctx.finish_reasons)
+    if semconv.capture_content_enabled():
+        for key in ("input_messages", "output_messages", "system_instructions"):
+            value = getattr(ctx, key)
+            if value:
+                extra[key] = value
+    if not extra:
+        return details
+    return {**(details or {}), **extra}
+
+
+def _close_span(span, ctx: RunContext) -> None:
+    """Stamp everything the run discovered onto its span before it ends."""
+    otel.set_usage(span, ctx.usage)
+    otel.set_finish_reasons(span, semconv.finish_reasons(ctx.finish_reasons))
+    otel.set_messages(
+        span,
+        semconv.input_messages(ctx.input_messages),
+        semconv.output_messages(ctx.output_messages),
+        semconv.system_instructions(ctx.system_instructions),
+    )
+
+
+def _with_model(fields: dict, ctx: "RunContext") -> dict:
+    """Add a late-discovered model to a terminal event's log fields.
+
+    A model the hook already knew at ``*_start`` wins: it is what the run asked
+    for, whereas this one is what the response happened to report.
+    """
+    if not ctx.model or fields.get("model"):
+        return fields
+    return {**fields, "model": ctx.model}
+
+
+def _close_run(
+    telemetry: "TelemetryClient",
+    ctx: "RunContext",
+    *,
+    end_event: str,
+    error_event: str,
+    fields: dict,
+    end_details: Optional[dict],
+    exc: Optional[BaseException] = None,
+    interrupted: bool = False,
+) -> None:
+    """Emit a run's terminal telemetry and close out its span attributes.
+
+    The single place a run ends, whichever form started it: the ``with`` block
+    below, or the deferred :class:`AgentRun`. Usage and model land on the span
+    first (attributes set after ``end()`` are silently dropped), then the
+    terminal log goes out, and only then is the error recorded on the span --
+    the order the hooks' payload tests pin.
+
+    ``exc`` marks a failed run, ``interrupted`` a streaming consumer that
+    stopped early or a cancelled run; a caller-supplied ``end_details`` still
+    wins over the interrupted status, because a hook that named its own terminal
+    details (CrewAI's ``completed``) means them either way.
+    """
+    _close_span(ctx.span, ctx)  # partial usage/content on failed runs
+    otel.set_model(ctx.span, ctx.model)
+    if exc is not None:
+        telemetry.send_log(
+            event_type=error_event,
+            error=str(exc),
+            traceback="".join(tb.format_exception(exc)),
+            details=_merge_run_details(None, ctx),
+            **_with_model(fields, ctx),
+        )
+        otel.record_error(ctx.span, exc)
+        return
+    default = {"status": "interrupted"} if interrupted else {"status": "success"}
+    telemetry.send_log(
+        event_type=end_event,
+        details=_merge_run_details(
+            end_details if end_details is not None else default, ctx
+        ),
+        **_with_model(fields, ctx),
+    )
+
+
+@contextmanager
+def trace_agent_run(
+    telemetry: "TelemetryClient",
+    span_name: str,
+    span_attributes: dict,
+    *,
+    start_event: str,
+    end_event: str,
+    error_event: str,
+    log_fields: Optional[dict] = None,
+    start_details: Optional[dict] = None,
+    end_details: Optional[dict] = None,
+    session_name_hint: Optional[str] = None,
+):
+    """Open an otelzero span and emit start/success/error telemetry around a run.
+
+    Wraps the boilerplate shared by every framework hook: open an OTel span,
+    send a ``*_start`` log, then -- around the wrapped call running in the
+    ``with`` body -- send ``*_end`` on success or ``*_error`` and re-raise on
+    failure (recording the error on the span). A successful run leaves the span
+    status untouched, which the conventions require.
+
+    Yields a :class:`RunContext`; token usage attached via ``set_usage`` is
+    merged into the terminal log's ``details["usage"]`` and set as
+    ``gen_ai.usage.*`` span attributes, and a model named via ``set_model``
+    fills in ``model`` on the terminal event and the span when the hook could
+    not read one before the run. Content attached via ``set_input`` /
+    ``set_output`` / ``set_system`` lands the same way -- on the terminal log
+    (success, error or interrupted alike) and as the Opt-In ``gen_ai.*``
+    content attributes -- but only when the user opted in to content capture.
+
+    ``log_fields`` (e.g. ``agent_name``/``agent_role``/``model``) are attached
+    to every log this emits; ``start_details``/``end_details`` populate the start/end logs'
+    ``details`` (``end_details`` defaults to ``{"status": "success"}``).
+    ``session_name_hint`` -- the run's intent text (a task description, agent
+    goal, or prompt) -- names the session before the start event is sent, so the
+    dashboard and apps show a meaningful title; the first non-empty hint across a
+    session's runs wins (see :meth:`TelemetryClient.suggest_session_name`). Works for
+    sync, ``async``, and async-generator wrapped calls alike, since the wrapped
+    call lives in the caller's ``with`` body. When a streaming consumer stops
+    early (``GeneratorExit`` in an async-generator wrapper), the ``*_end``
+    event is still emitted -- with ``{"status": "interrupted"}`` unless the hook
+    provided ``end_details`` -- so interrupted runs don't dangle open.
+    """
+    fields = log_fields or {}
+    telemetry.suggest_session_name(session_name_hint)
+    with otel.span(span_name, _with_identity(telemetry, span_attributes)) as span:
+        ctx = RunContext(span)
+        telemetry.send_log(event_type=start_event, details=start_details, **fields)
+
+        def close(**outcome):
+            _close_run(
+                telemetry,
+                ctx,
+                end_event=end_event,
+                error_event=error_event,
+                fields=fields,
+                end_details=end_details,
+                **outcome,
+            )
+
+        try:
+            yield ctx
+        except GeneratorExit:
+            # Streaming consumer stopped early (break/aclose): close the run
+            # with whatever usage accumulated, then keep unwinding.
+            close(interrupted=True)
+            raise
+        except Exception as e:
+            close(exc=e)
+            raise
+        close()
+
+
+class AgentRun:
+    """A run that is started now and finished later, from wherever it ends.
+
+    :func:`trace_agent_run`'s ``with`` block assumes the wrapped call *is* the
+    run. Some frameworks break that assumption: LlamaIndex's ``Workflow.run`` is
+    synchronous, schedules an asyncio task and returns a handler immediately, so
+    a block around it would close the span before the run started. Such a hook
+    opens the run with :func:`start_agent_run`, holds :meth:`activate` around the
+    call that schedules the task -- so the task inherits the span as its parent --
+    and calls :meth:`finish` from the task's done-callback.
+
+    :meth:`finish` is idempotent: a done-callback and a teardown path may both
+    reach for a run that is already closed, and reporting it twice would show as
+    two overlapping runs of one agent.
+    """
+
+    __slots__ = ("ctx", "_telemetry", "_events", "_fields", "_end_details", "_closed")
+
+    def __init__(self, telemetry, span, *, events, fields, end_details):
+        self.ctx = RunContext(span)
+        self._telemetry = telemetry
+        self._events = events  # (end_event, error_event)
+        self._fields = fields
+        self._end_details = end_details
+        self._closed = False
+
+    @property
+    def span(self):
+        return self.ctx.span
+
+    def set_usage(self, usage: Optional[dict]) -> None:
+        self.ctx.set_usage(usage)
+
+    def set_model(self, model: Optional[str]) -> None:
+        self.ctx.set_model(model)
+
+    def set_input(self, messages) -> None:
+        self.ctx.set_input(messages)
+
+    def set_output(self, messages, finish_reasons=None) -> None:
+        self.ctx.set_output(messages, finish_reasons)
+
+    def set_system(self, parts) -> None:
+        self.ctx.set_system(parts)
+
+    @contextmanager
+    def activate(self):
+        """Make the run's span current for the block, without ending it."""
+        with otel.use_span(self.ctx.span):
+            yield self
+
+    def finish(
+        self, exc: Optional[BaseException] = None, interrupted: bool = False
+    ) -> None:
+        """Close the run exactly once: terminal event, then end the span."""
+        if self._closed:
+            return
+        self._closed = True
+        end_event, error_event = self._events
+        try:
+            _close_run(
+                self._telemetry,
+                self.ctx,
+                end_event=end_event,
+                error_event=error_event,
+                fields=self._fields,
+                end_details=self._end_details,
+                exc=exc,
+                interrupted=interrupted,
+            )
+        finally:
+            otel.end_span(self.ctx.span)
+
+
+def start_agent_run(
+    telemetry: "TelemetryClient",
+    span_name: str,
+    span_attributes: dict,
+    *,
+    start_event: str,
+    end_event: str,
+    error_event: str,
+    log_fields: Optional[dict] = None,
+    start_details: Optional[dict] = None,
+    end_details: Optional[dict] = None,
+    session_name_hint: Optional[str] = None,
+) -> AgentRun:
+    """Open a run whose end is reported later -- the deferred :func:`trace_agent_run`.
+
+    Takes the same arguments and emits the same payloads; the difference is that
+    the span is started *without* being made current and the terminal event is
+    the caller's job, via the returned :class:`AgentRun`. For a framework whose
+    run entry point returns a handle rather than a result -- see
+    :mod:`otelzero.hooks.llama_index`.
+    """
+    fields = log_fields or {}
+    telemetry.suggest_session_name(session_name_hint)
+    span = otel.start_span(span_name, _with_identity(telemetry, span_attributes))
+    run = AgentRun(
+        telemetry,
+        span,
+        events=(end_event, error_event),
+        fields=fields,
+        end_details=end_details,
+    )
+    telemetry.send_log(event_type=start_event, details=start_details, **fields)
+    return run
+
+
+def nesting_guard(name: str):
+    """Build a re-entrancy guard for a framework whose run entry points nest.
+
+    Some frameworks offer several public ways to start a run that are really one
+    run underneath: LangGraph's ``invoke`` drains its own ``stream``, and a graph
+    node holding a subgraph re-enters the runtime a level down; the OpenAI Agents
+    SDK's ``run_sync`` drives ``run``. Wrapping each entry point is still right --
+    callers use all of them -- but only the outermost call should open a span, or
+    one agent run would be reported as two overlapping ones.
+
+    Returns a context-manager factory yielding ``True`` for the outermost call on
+    the current context and ``False`` for anything nested inside it. The depth
+    lives in a :class:`~contextvars.ContextVar`, so concurrent ``asyncio`` tasks
+    and threads each track their own nesting rather than masking each other's
+    runs. Frameworks that hand node execution to a worker thread *without*
+    copying the context will not nest across that boundary; the guard degrades to
+    reporting the inner run separately, never to losing one.
+    """
+    var: contextvars.ContextVar = contextvars.ContextVar(
+        f"otelzero_depth_{name}", default=0
+    )
+
+    @contextmanager
+    def guard():
+        if var.get():
+            yield False
+            return
+        token = var.set(1)
+        try:
+            yield True
+        finally:
+            var.reset(token)
+
+    return guard
+
+
+def install_hook(
+    hook_cls,
+    *,
+    framework: str,
+    label: str,
+    server_url: str,
+    user: Optional[str],
+    api_key: Optional[str] = None,
+    session: Optional[str] = None,
+    name: Optional[str] = None,
+) -> TelemetryClient:
+    """Wire up a framework hook: build the client and register it.
+
+    Creates a :class:`TelemetryClient` for ``framework``, instantiates
+    ``hook_cls`` and inserts it at the front of ``sys.meta_path`` so subsequent
+    imports of the framework are instrumented. ``label`` is the human-readable
+    name used in the ``[MONITOR]`` console output. ``api_key`` ties events to an
+    owner (for the iOS app); ``session`` groups one run's events; ``name`` is an
+    explicit session title (else it is derived from the run's intent). Returns
+    the telemetry client.
+    """
+    telemetry = TelemetryClient(
+        server_url,
+        framework=framework,
+        user=user,
+        api_key=api_key,
+        session=session,
+        name=name,
+    )
+    hook = hook_cls(telemetry)
+    sys.meta_path.insert(0, hook)
+    print(f"[MONITOR] {label} monitoring installed (server: {server_url})")
+    return telemetry