Add QwenPaw instrumentation

[123liuziming]

Description

Adds opentelemetry-instrumentation-genai-qwenpaw, instrumentation for QwenPaw, a personal assistant application built on AgentScope. Each user turn handled by AgentRunner.query_handler is traced as one invoke_agent span (gen_ai.agent.id, gen_ai.agent.name, gen_ai.conversation.id, and opt-in input/output message content), plus the gen_ai.client.operation.duration metric, all through opentelemetry-util-genai.

QwenPaw delegates model (LLM) and tool execution to AgentScope, so this package intentionally emits no chat or execute_tool spans and the conformance suite covers none — those operations belong to the AgentScope instrumentation.

Supported range is qwenpaw >= 1.1.0, < 2.0.0 (2.0 removed AgentRunner.query_handler).

Type of change

• New feature (non-breaking change which adds functionality)

How has this been tested?

• tox -e py310-test-instrumentation-genai-qwenpaw-oldest (qwenpaw 1.1.0 via lowest-direct)
• tox -e py312-test-instrumentation-genai-qwenpaw-latest (qwenpaw 1.1.12.post3)
• tox -e py313-test-instrumentation-genai-qwenpaw-conformance (weaver live-check, 0 violations)
• tox -e lint-instrumentation-genai-qwenpaw, precommit, typecheck, readme

Checklist

See CONTRIBUTING.md
for the style guide, changelog guidance, and more.

• Followed the style guidelines of this project
• Changelog updated if the change requires an entry
• Unit tests added
• Documentation updated

Made with Cursor

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on the author · refreshed 2026-08-21 01:40 UTC

Resolve merge conflicts.

Respond to 2 review items (e.g. link a commit, explain why not, ask a follow-up):

• Inline threads: 1
• Top-level threads: 2

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
• Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

[Copilot]

Pull request overview

Adds a new GenAI instrumentation package, opentelemetry-instrumentation-genai-qwenpaw, to trace QwenPaw AgentRunner.query_handler turns as invoke_agent operations using opentelemetry-util-genai, and wires the package into the monorepo’s test/release automation.

Changes:

• Introduces the new QwenPaw instrumentor implementation (async-generator wrapping + message mapping helpers).
• Adds unit tests and a conformance scenario for the single emitted semconv operation (invoke_agent), plus tox env wiring.
• Registers the new package in workspace deps, release workflows, and per-package tooling configs.

Reviewed changes

Copilot reviewed 29 out of 32 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tox.ini	Adds tox envs/deps/commands for qwenpaw oldest/latest/conformance + lint; adjusts typecheck install.
pyproject.toml	Adds qwenpaw workspace dependency and pyright include/exclude entries.
instrumentation/README.md	Lists the new qwenpaw instrumentation in the workspace table.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/test_query_handler.py	End-to-end async tests for query_handler span/metric behavior and error cases.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/test_message_mapping.py	Unit tests for call parsing + message mapping utilities.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/test_instrumentor.py	Tests instrumentation dependency metadata and uninstrument behavior.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/test_conformance.py	Runs the per-scenario conformance runner for qwenpaw.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/requirements.oldest.txt	Defines oldest-factor test-only dependency pins (currently none).
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/requirements.latest.txt	Pins latest qwenpaw and installs editable util/instrumentation for tests.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/harness.py	Test harness to drive query_handler without real model/tool execution.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/conftest.py	Registers shared fixtures and defines package-local test fixtures.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/conformance/invoke_agent.py	Conformance scenario for one invoke_agent turn.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/conformance/init.py	Marks conformance package.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/tests/init.py	Marks tests package.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/src/opentelemetry/instrumentation/genai/qwenpaw/version.py	Adds package version module.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/src/opentelemetry/instrumentation/genai/qwenpaw/utils.py	Adds helpers for parsing/mapping input/output messages.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/src/opentelemetry/instrumentation/genai/qwenpaw/patch.py	Implements async stream wrapper + wrapt wrapper for query_handler.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/src/opentelemetry/instrumentation/genai/qwenpaw/package.py	Declares instruments metadata for the instrumentor.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/src/opentelemetry/instrumentation/genai/qwenpaw/init.py	Adds QwenPawInstrumentor implementation + package docstring.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/README.rst	Adds package README for PyPI long description.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/pyproject.toml	Adds package build metadata, deps, and instrumentor entry point.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/LICENSE	Adds Apache 2.0 license file for the new package.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/.changelog/311.added	Adds towncrier fragment for the new instrumentation.
instrumentation/opentelemetry-instrumentation-genai-qwenpaw/.changelog/.gitignore	Ensures the changelog directory is retained in git.
eachdist.ini	Adds qwenpaw to per-dist tooling configuration.
dev-requirements-conformance.txt	Adds OTLP meta/proto-http pins needed by some conformance dependencies.
.github/workflows/release-package.yml	Adds qwenpaw to the release workflow package choice list.
.github/workflows/prepare-release.yml	Adds qwenpaw to the prepare-release workflow package choice list.
.github/workflows/prepare-backport-patch.yml	Adds qwenpaw to the backport patch workflow package choice list.
.github/workflows/bump-package-minor.yml	Adds qwenpaw to the bump-minor workflow package choice list.
.github/workflows/bump-package-major.yml	Adds qwenpaw to the bump-major workflow package choice list.

[eternalcuriouslearner]

LGTM!! Minor nit and can you please resolve the merge conflicts?

[Copilot]

Pull request overview

Copilot reviewed 39 out of 42 changed files in this pull request and generated no new comments.

Suppressed comments (6)

instrumentation/opentelemetry-instrumentation-genai-qwenpaw/src/opentelemetry/instrumentation/genai/qwenpaw/patch.py:115

• Reading agent_name invokes QwenPaw's lazy property, which loads configuration and mutates its cache. This happens before the async generator starts and even on command paths that otherwise return before touching the property, so enabling instrumentation adds I/O and changes execution timing. Use only already-cached state (or omit the optional name) rather than evaluating this property, per the instrumentation transparency rule.

    agent_name = non_empty_str(getattr(instance, "agent_name", None))

instrumentation/opentelemetry-instrumentation-genai-qwenpaw/pyproject.toml:36

• The supported QwenPaw releases pin AgentScope 1.0.18–1.0.20, whose runtime dependencies include opentelemetry-api, SDK, exporter, and semantic conventions, and which ships first-party setup_tracing, trace_reply, trace_llm, and tool tracing. Before adding a separate package, this needs an explicit assessment of why AgentScope's native telemetry cannot cover the turn and how duplicate/conflicting telemetry is avoided, as required by When to add an instrumentation here.

instruments = ["qwenpaw >= 1.1.0, < 2.0.0; python_version < '3.14'"]

instrumentation/opentelemetry-instrumentation-genai-qwenpaw/src/opentelemetry/instrumentation/genai/qwenpaw/patch.py:51

• Assigning the invocation to the base class's reserved _self_invocation field opts this local INTERNAL invoke_agent span into gen_ai.client.operation.time_to_first_chunk/per-chunk metrics. Those metrics require a provider, which is why the conformance scenario has to suppress a gen_ai.provider.name violation. Keep the agent invocation in a separate field (as _AgentRunStreamWrapper does in the qwen-agent package) so the base sees no client-stream invocation, then remove the time-to-first-chunk expectation and violation.

This issue also appears on line 115 of the same file.

        self._self_invocation = invocation

instrumentation/opentelemetry-instrumentation-genai-qwenpaw/src/opentelemetry/instrumentation/genai/qwenpaw/utils.py:82

• This records finish_reason="stop" for every assistant chunk, although QwenPaw's tuple explicitly carries a last flag and early-close tests consume a chunk where last=False. Early closure therefore exports a partial response as if the agent completed normally. Only use stop when the tuple's last value is true; partial output needs a representation without a terminal finish reason (extend the util type if necessary).

    return OutputMessage(
        role="assistant",
        parts=[Text(content=text)],
        finish_reason="stop",

instrumentation/opentelemetry-instrumentation-genai-qwenpaw/examples/manual/README.rst:11

• The implementation and tests deliberately omit gen_ai.agent.id because QwenPaw's agent_id is only a local config key, so this example's claim that each span carries the agent ID is incorrect. Remove “agent id” and describe only the emitted agent name and session/conversation ID.

turn handled by the agent runner produces an ``invoke_agent`` span carrying
the agent id, agent name, and session id. Pair it with the AgentScope
instrumentation to also capture the model and tool calls QwenPaw delegates.

pyproject.toml:48

• These are global uv overrides, so every workspace sync now ignores CrewAI's declared chromadb~=1.1.0 range and the QwenPaw/oss2 jmespath<1.0 range. That makes unrelated packages install and type-check against versions their maintainers explicitly exclude, masking real dependency incompatibilities and potentially breaking the existing CrewAI/QwenPaw environments. Keep incompatible instrument extras out of the same aggregate environment or scope overrides to the one test/typecheck environment after compatibility is established, rather than weakening both constraints globally.

[lmolkova]

Telemetry is finalized only through the proxy's own methods, but the real callers do not always call them. agents/acp/server.py:572 breaks out of the async for when the client cancels, and the runner treats asyncio.CancelledError as a normal path (runner.py:863), so a half consumed turn is expected traffic. When the caller drops the proxy, GC hands the raw async generator to the event loop's finalizer, which calls aclose() on the underlying generator directly and never reaches QueryHandlerStreamWrapper.aclose(). The span is never ended and never exported.

This test fails today with zero spans collected:

@pytest.mark.asyncio
async def test_break_mid_stream_finalizes_span(
    instrument_no_content, runner_module, span_exporter
):
    async def multi_chunk(request, msgs, runner):
        for i in range(3):
            yield assistant_reply(f"chunk-{i}"), i == 2

    runner = runner_module.AgentRunner(agent_id="entry-agent")
    with patched_command_path(runner_module, multi_chunk):
        async for _ in runner.query_handler(user_command_msgs(), make_request()):
            break
    gc.collect()

    (span,) = span_exporter.get_finished_spans()
    assert span.name.startswith("invoke_agent")

Finalization has to hang off the generator's own teardown, so that GeneratorExit reaches a finally, rather than off proxy methods the caller never calls. No proxy-based wrapper can close this hole, since GC finalizes the underlying generator without going through it. Filed as #386 against util-genai, since qwen-agent has the same shape and the fix belongs there.

Fine to land as is for now: it only triggers when a caller stops consuming early, and the leaked context dies with the request task. Worth knowing that it is not purely a lost span though, as later spans in that task nest under the span that never ended.

[123liuziming]

Thanks for the thorough analysis — agreed. Since GC finalizes the underlying generator directly, no proxy-based wrapper can intercept that path, so the fix belongs in util-genai's stream wrapper as you filed in #386 (qwen-agent shares the same shape). I'll adopt the util-genai fix here (and add your break-mid-stream test) once it lands; leaving this thread open until then.

[opentelemetry-pr-dashboard]

Hi @123liuziming — just a friendly reminder that this pull request is waiting on you. The dashboard status comment has the open items and is kept current.

• Replying is enough to hand it off — answer, explain why no change is needed, or ask a follow-up. The dashboard routes it onward once nothing on the list is waiting on you.
• To hand it back for any other reason, including the dashboard getting this wrong, comment /dashboard route:reviewers.