feat(telemetry): emit adapter-function activate/deactivate spans from a tracing plugin

[planetf1]

Pull Request

Issue

Progresses #1466 with invocation-scoped adapter-function tracing.

Description

Adapter-function metrics could report that activation had finished, but tracing could not represent the activation lifecycle as spans: the hook family had completion events only, so a plugin had no event at which to open a parent span or a phase span.

This PR adds the paired start events and lets AdapterFunctionTracingPlugin build the span tree. Backend code still fires hooks only; it does not import tracing or create spans directly.

sequenceDiagram
    participant Scope as AdapterMixin.adapter_scope
    participant Hooks as Hook dispatcher
    participant Plugin as AdapterFunctionTracingPlugin
    participant Trace as OpenTelemetry tracer

    Scope->>Hooks: invocation_start(id)
    Hooks->>Plugin: open parent
    Plugin->>Trace: adapter_function
    Scope->>Hooks: phase_start(id, activate)
    Hooks->>Plugin: open child
    Plugin->>Trace: adapter_function.activate
    Scope->>Hooks: phase_complete(id, activate)
    Hooks->>Plugin: close child
    Scope->>Hooks: phase_start(id, deactivate)
    Hooks->>Plugin: open child
    Scope->>Hooks: phase_complete(id, deactivate)
    Hooks->>Plugin: close child
    Scope->>Hooks: invocation_complete(id, outcome)
    Hooks->>Plugin: close parent

Loading

The hook calls begin in synchronous code and are dispatched to the shared async loop. Ambient OpenTelemetry context cannot cross those dispatches, so phase spans are explicitly parented from the invocation ID rather than relying on context attachment.

flowchart LR
    A[Adapter scope emits correlated lifecycle hooks] --> B[Tracing plugin builds parent and child spans]
    C[Embedded request activation emits metric-only phase completion] --> D[Metrics plugin records duration]
    C --> E[No correlation ID]
    E --> F[Tracing plugin ignores event]

Loading

The second path is deliberate. An embedded request edit has no matching invocation outcome yet, so this PR preserves its existing metric while avoiding an orphan span.

Scope

Included:

• activate and deactivate spans inside AdapterMixin.adapter_scope.
• Invocation and phase start hooks plus correlation IDs for that scope.
• Explicit parent/child span construction in the tracing plugin.
• Compatibility handling for existing metric-only phase completions.
• Regression tests for hook ordering, parentage, failures, and existing Hugging Face assertions.

Deferred:

• prepare remains metric-only. It is setup work, not an adapter-function invocation; tracing it needs a separate contract that does not alter invocation metrics.
• generate and parse remain blocked on refactor(backends): route intrinsic generation through adapter_scope (Epic #929 Phase 2) #1465.
• Content capture and metric exemplars remain deferred.
• release remains untraced because it has no invocation-scoped hook site.

Verification

• uv run pytest test/ -m "not qualitative": 4,142 passed, 47 skipped.
• Pre-commit: SPDX, Ruff, Mypy, codespell, and markdownlint passed.
• GitHub quality checks pass on Python 3.11, 3.12, and 3.13.

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code was added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

---

Adding a new component, requirement, sampling strategy, or tool?

• Component
• Requirement
• Sampling Strategy
• Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.

[planetf1]

As this touches telemetry I'm going to hold on any merge until @ajbozarth has had an opportunity to review (unless this starts blocking other changes)

[planetf1]

currently working on changes. not yet ready for review

[planetf1]

Closing this draft for now.

The reviewed implementation provides useful LocalFile activation/deactivation spans, but it is not complete adapter-function observability: prepare, generation/parsing, embedded invocation outcomes, server-mediated adapters, content capture, and exemplar linkage all remain outside the slice.

Metrics already cover the current lifecycle phases. We will return to tracing when there is a concrete operational need, when another adapter reality needs comparable visibility, or when we can define one coherent lifecycle and metric contract across adapter types.