Add A365 telemetry correlation for WebSocket invocations by yulin-li · Pull Request #48007 · Azure/azure-sdk-for-python

Yulin Li (yulin-li) · 2026-07-11T15:45:16Z

Description

invocations_ws previously excluded WebSocket scopes from W3C trace propagation and did not attach the Agent 365 session baggage used to enrich spans created by customer handler code. This aligns WebSocket telemetry with the existing REST invocations behavior.

The change propagates incoming traceparent, tracestate, and baggage through the WebSocket lifecycle; attaches the canonical azure.ai.agentserver.session_id; and maps that context onto exported child spans and close-event logs. REST and WebSocket now share the existing core session key instead of defining protocol-specific duplicates.

Customer-code coverage creates and exports an explicit customer.websocket.process_message span, verifying its remote parent, instrumentation scope, custom attributes, A365 session correlation, and Foundry project identity. A hosted dual-protocol E2E run also confirmed the customer-created invocations_ws_a365_e2e span in Application Insights with session, agent, blueprint, and project enrichment.

The shared microsoft-opentelemetry optional OpenAI Agents instrumentation warning (ModuleNotFoundError: agents) reproduces for both REST and WebSocket and is intentionally unchanged.

Validation:

Invocations test suite: 190 passed, 2 skipped
Package pylint and pyright checks passed
Hosted Agent 365 E2E marker: customer-ws-span-20260711T153708Z

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

Propagate W3C context through WebSocket scopes and attach the hosted session ID as A365 baggage for the connection lifecycle. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 811a430b-62e7-49b3-b426-45d1f28b04ef

Use the cross-protocol azure.ai.agentserver.session_id field for invocations_ws close-event telemetry, matching REST invocations and A365 correlation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 811a430b-62e7-49b3-b426-45d1f28b04ef

Remove the duplicate WebSocket session attribute constant and use the core tracing key in both invocation transports. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 811a430b-62e7-49b3-b426-45d1f28b04ef

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 811a430b-62e7-49b3-b426-45d1f28b04ef

Copilot

Pull request overview

Aligns WebSocket telemetry with REST invocation tracing and Agent 365 correlation.

Changes:

Propagates W3C context through WebSocket connections.
Adds canonical session baggage to handler spans and close logs.
Adds tracing tests and updates documentation.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`core/CHANGELOG.md`	Records WebSocket propagation support.
`core/_base.py`	Documents WebSocket middleware behavior.
`core/_tracing.py`	Enables context extraction for WebSockets.
`invocations/CHANGELOG.md`	Records Agent 365 correlation.
`invocations/README.md`	Updates WebSocket telemetry documentation.
`invocations/_constants.py`	Removes protocol-specific session key.
`invocations/_invocation.py`	Reuses the shared baggage constant.
`invocations/_invocation_ws.py`	Attaches session baggage throughout connections.
`tests/conftest.py`	Updates close-log filtering.
`tests/test_ws_close_event.py`	Checks the canonical session field.
`tests/test_ws_session_id.py`	Updates session-log assertions.
`tests/test_ws_tracing.py`	Tests baggage, parenting, and enrichment.

Bump core to 2.0.0b8 and invocations to 1.0.0b7, and raise the invocations core dependency to >=2.0.0b8. The repo core was still 2.0.0b7, identical to the published PyPI 2.0.0b7 which lacks the new WebSocket scope handling, so CI resolved the constraint to the published wheel and the WS trace-context/baggage tests failed. The version bumps also align _version.py with the top CHANGELOG entries so Verify-ChangeLogs passes. Fix _FoundryEnrichmentSpanProcessor._on_ending for opentelemetry-sdk 1.43.0+, which now marks span attributes immutable before the on-ending hook; temporarily clear the flag so agent identity attributes are applied. Correct the invocations README to describe the actual per-connection telemetry (context/baggage propagation + close-event log) instead of a non-existent websocket_session span, and update the stale close-event comment to note the session-ID key comes from the shared _BAGGAGE_SESSION_ID in core. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 05a86c59-4ebd-4ec8-a42b-73b2e4ce94e0

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-invocations/CHANGELOG.md

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-core/azure/ai/agentserver/core/_tracing.py # sdk/agentserver/azure-ai-agentserver-invocations/pyproject.toml

Copilot

Pull request overview

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

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-core/CHANGELOG.md

Copilot

Pull request overview

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

Comments suppressed due to low confidence (1)

sdk/agentserver/azure-ai-agentserver-invocations/azure/ai/agentserver/invocations/_invocation_ws.py:398

This replaces the previously documented azure.ai.agentserver.invocations_ws.session_id close-event field rather than adding the shared key alongside it. Existing structured-log queries and processors will therefore lose session correlation, which contradicts the PR's “no breaking changes” declaration (the old field is documented in the 1.0.0b4 changelog). Preserve compatibility by emitting both keys for a transition period, or explicitly classify and document the schema change as breaking.

            _BAGGAGE_SESSION_ID: session_id,

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-core/CHANGELOG.md

Copilot

Pull request overview

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

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-invocations/CHANGELOG.md # sdk/agentserver/azure-ai-agentserver-invocations/pyproject.toml

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

Copilot review overview

🟡 Changes recommended

Unresolved critical and moderate fail-open regressions can abort Voice host construction and generic WebSocket connections.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

Preserve fail-open handling for CancelledError during observability setup · New

Resolved since last review (1)

Narrow BaseException handler to let SystemExit propagate

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

Copilot review overview

🔵 Needs a closer look

Cross-package telemetry propagation changes warrant final human review despite no unresolved comments.

Review effort: Balanced
Findings: None

Resolved since last review (1)

Preserve fail-open handling for CancelledError during observability setup

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

Copilot review overview

🟡 Changes recommended

The core API metadata hash does not match the committed API snapshot.

Review effort: Balanced
Findings: 1

Open (1)

API metadata hash does not match committed api.md · New

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

Copilot review overview

🟢 Approval recommended

The implementation, dependency versions, API metadata, documentation, and targeted regression coverage are consistent.

Review effort: Balanced
Findings: None

Resolved since last review (1)

API metadata hash does not match committed api.md

Resolve AgentServer release metadata against the active core 2.3.0b1 and invocations 1.3.0b1 preview lines. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🔵 Needs a closer look

Cross-package ASGI context propagation and Voice routing changes warrant final human validation.

0 open findings

🧠 Review effort: Balanced

Preserve the AgentServer telemetry changes alongside the new lifecycle APIs and record the normalized combined API snapshot. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🟢 Approval recommended

The implementation and focused regressions consistently cover generic and Voice WebSocket correlation, sanitization, and compatibility behavior.

0 open findings

🧠 Review effort: Balanced

Preserve the WebSocket telemetry changes alongside the latest Foundry tracing enrichment from main. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🔵 Needs a closer look

Cross-package propagation and Voice telemetry privacy boundaries warrant human security review, particularly with incomplete privacy regression coverage.

1 open finding

Test does not exercise session baggage enrichment · New

🧠 Review effort: Balanced

Exercise callback export through an isolated Foundry enrichment processor so unsafe session baggage would fail the test if attached. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🔵 Needs a closer look

Cross-package context propagation and security-sensitive Voice baggage filtering warrant final human review.

0 open findings

1 resolved since last review

Test does not exercise session baggage enrichment

🧠 Review effort: Balanced

Preserve the WebSocket telemetry release note alongside the latest streaming and durable-task fixes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🔵 Needs a closer look

Shared trace-context handling and Voice baggage privacy boundaries warrant final human review.

0 open findings

🧠 Review effort: Balanced

Move the core telemetry fix to unreleased 2.3.0b2 after the 2.3.0b1 release and align the invocations dependency floor. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🔵 Needs a closer look

Shared propagation and Voice baggage-isolation changes affect telemetry privacy boundaries and warrant human security review.

0 open findings

🧠 Review effort: Balanced

Preserve the core 2.3.0b2 changelog template and the WebSocket telemetry fix. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🔵 Needs a closer look

Cross-package propagation and Voice telemetry isolation warrant final human review.

0 open findings

🧠 Review effort: Balanced

Integrate the new Voice conversation-engine route with the existing propagation privacy boundary and preserve current API metadata and release notes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🔵 Needs a closer look

Connection-wide propagation and Voice header filtering affect telemetry privacy boundaries and warrant final human security review.

No open issues 🎉

_{Review effort: Balanced}

Integrate protocol-scoped task runtime changes with shared identifier sanitization and WebSocket telemetry propagation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🟡 Changes recommended

Caller baggage can overwrite server-generated close-event attributes in exported WebSocket logs.

1 open issue

Prevent baggage from overwriting WebSocket close-event attributes · New

_{Review effort: Balanced}

Prevent caller baggage from overwriting server-authored telemetry fields and cover exported WebSocket close records with colliding baggage. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🟡 Changes recommended

The new close-event regression selects both the handler-error and close-event logs, invalidating its single-record assertion.

1 open issue

Filter close-event regression by SDK message · New

1 resolved since last review

Prevent baggage from overwriting WebSocket close-event attributes

_{Review effort: Balanced}

Filter the collision regression by the SDK close-event message so caller baggage on an earlier error log cannot select the wrong record. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot

🔵 Needs a closer look

Caller-supplied session-alias baggage can still make exported WebSocket logs disagree with the SDK session used by handler spans.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Baggage alias overrides canonical WebSocket session correlation

sdk/agentserver/azure-ai-agentserver-core/azure/ai/agentserver/core/_tracing.py:936

Incoming baggage: microsoft.session.id=caller-session still breaks A365 session correlation for generic WebSocket handlers. Close-event extras contain the canonical and legacy session keys, but not microsoft.session.id, so this loop inserts the caller's alias. The session-resolution block below then skips the canonical session because the alias already exists. Exported close logs consequently use caller-session while handler spans use the SDK session. Skip the baggage alias when canonical session baggage is present, while preserving genuinely pre-existing log attributes. Extend the exporter regression to inject this alias and assert that exported microsoft.session.id matches the canonical session.

1 resolved since last review

Filter close-event regression by SDK message

_{Review effort: Balanced}

Yulin Li added 4 commits July 11, 2026 22:44

Reuse shared session baggage key

95acc69

Remove the duplicate WebSocket session attribute constant and use the core tracing key in both invocation transports. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 811a430b-62e7-49b3-b426-45d1f28b04ef

Test customer WebSocket telemetry span

4951d52

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 811a430b-62e7-49b3-b426-45d1f28b04ef

github-actions Bot added the Hosted Agents sdk/agentserver/* label Jul 11, 2026

Generalize trace middleware description

b8b2120

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 811a430b-62e7-49b3-b426-45d1f28b04ef

Yulin Li (yulin-li) marked this pull request as ready for review July 11, 2026 15:50

Yulin Li (yulin-li) requested a review from Ankit Sinha (ankitbko) as a code owner July 11, 2026 15:50

Copilot AI balanced review requested due to automatic review settings July 11, 2026 15:50

Yulin Li (yulin-li) requested review from Ravi Teja Pidaparthi (RaviPidaparthi) and Pranav Pandit (vangarp) as code owners July 11, 2026 15:50

Copilot started reviewing on behalf of Yulin Li (yulin-li) July 11, 2026 15:51

View session

Copilot AI reviewed Jul 11, 2026

View reviewed changes

Comment thread sdk/agentserver/azure-ai-agentserver-invocations/CHANGELOG.md Outdated

Comment thread sdk/agentserver/azure-ai-agentserver-invocations/README.md Outdated

Comment thread ...ntserver/azure-ai-agentserver-invocations/azure/ai/agentserver/invocations/_invocation_ws.py Outdated

Yulin Li and others added 4 commits July 12, 2026 11:00

Merge branch 'main' into yulin-li/verify-ws-a365-telemetry

77469e9

Merge remote-tracking branch 'origin/main' into yulin-li/verify-ws-a3…

20fb884

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-invocations/CHANGELOG.md

Merge remote-tracking branch 'origin/main' into yulin-li/verify-ws-a3…

8fd9158

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-core/azure/ai/agentserver/core/_tracing.py # sdk/agentserver/azure-ai-agentserver-invocations/pyproject.toml

Copilot AI review requested due to automatic review settings July 21, 2026 12:11

Yulin Li (yulin-li) requested a review from Shiva S (Shivakishore14) as a code owner July 21, 2026 12:11

Copilot started reviewing on behalf of Yulin Li (yulin-li) July 21, 2026 12:12

View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into yulin-li/verify-ws-a3…

3e4349c

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-core/CHANGELOG.md

Copilot AI review requested due to automatic review settings July 22, 2026 07:33

Copilot started reviewing on behalf of Yulin Li (yulin-li) July 22, 2026 07:34

View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into yulin-li/verify-ws-a3…

b4e0383

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-core/CHANGELOG.md

Copilot AI review requested due to automatic review settings July 22, 2026 09:49

Copilot started reviewing on behalf of Yulin Li (yulin-li) July 22, 2026 09:51

View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into yulin-li/verify-ws-a3…

b869811

…65-telemetry # Conflicts: # sdk/agentserver/azure-ai-agentserver-invocations/CHANGELOG.md # sdk/agentserver/azure-ai-agentserver-invocations/pyproject.toml

Fix Voice control-flow propagation

f5dfbd6

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot AI reviewed Sep 22, 2026

View reviewed changes

Comment thread ...erver/azure-ai-agentserver-invocations/azure/ai/agentserver/invocations/voice/_voice_host.py Outdated

Restore Voice observability fail-open behavior

c6f747f

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot AI reviewed Sep 22, 2026

View reviewed changes

Merge main into WebSocket telemetry branch

28bbcf3

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot AI reviewed Sep 29, 2026

View reviewed changes

Comment thread sdk/agentserver/azure-ai-agentserver-core/api.metadata.yml Outdated

Fix core API metadata hash

a140056

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot AI reviewed Sep 29, 2026

View reviewed changes

Merge main into WebSocket telemetry branch

c76fc5a

Resolve AgentServer release metadata against the active core 2.3.0b1 and invocations 1.3.0b1 preview lines. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot AI reviewed Oct 13, 2026

View reviewed changes

Merge latest main into WebSocket telemetry branch

287fa1d

Preserve the WebSocket telemetry changes alongside the latest Foundry tracing enrichment from main. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot AI reviewed Oct 15, 2026

View reviewed changes

Comment thread sdk/agentserver/azure-ai-agentserver-invocations/tests/voice/test_voice_tracing.py Outdated

Copilot AI reviewed Oct 15, 2026

View reviewed changes

Merge latest main into WebSocket telemetry branch

9a07971

Preserve the WebSocket telemetry release note alongside the latest streaming and durable-task fixes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot AI reviewed Oct 15, 2026

View reviewed changes

Merge latest main into WebSocket telemetry branch

aef58c6

Preserve the core 2.3.0b2 changelog template and the WebSocket telemetry fix. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b94aa89c-e288-46f2-8802-4f266ba8830e

Copilot AI reviewed Oct 16, 2026

View reviewed changes

Copilot AI reviewed Oct 22, 2026

View reviewed changes

Comment thread ...ntserver/azure-ai-agentserver-invocations/azure/ai/agentserver/invocations/_invocation_ws.py

Copilot AI reviewed Oct 22, 2026

View reviewed changes

Comment thread sdk/agentserver/azure-ai-agentserver-invocations/tests/test_ws_close_event.py Outdated

Copilot AI reviewed Oct 22, 2026

View reviewed changes

Conversation

Yulin Li (yulin-li) commented Jul 11, 2026

Description

All SDK Contribution checklist:

General Guidelines and Best Practices

Testing Guidelines

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment