chore(release): backport #42388 and #41462 to stable/1.102.x

[devin-ai-integration]

TLDR

Problem this solves:

• stable/1.102.x closes realtime clients with 1006 and no event when the upstream handshake is refused
• stable/1.102.x cannot promote nested caller metadata (requester_metadata.trace_id) to OTEL span attributes
• the line's lock still carries anyio 4.13.0 and soupsieve 2.8.4

How it solves it:

• cherry-pick fix(realtime): surface an upstream handshake refusal as an error event and policy close #42388 (2bab39e): catch InvalidStatus, send an error event, close 1008/1013/1011 by upstream HTTP status
• cherry-pick feat(otel): promote nested request metadata keys to litellm.metadata.* span attributes #41462 (79fc515): flatten nested request metadata, promote allowlisted paths as litellm.metadata.<path> on OTEL v1 and v2
• cherry-pick test(realtime): drop legacy InvalidStatusCode tests and pin websockets imports #42624 (54dbe8e): test-only, drops two tests that asserted the pre-fix(realtime): surface an upstream handshake refusal as an error event and policy close #42388 close code
• lock-only bump of anyio to 4.14.2 and soupsieve to 2.9.0, no pyproject change

User Flow

Before: a developer connecting to a realtime deployment whose Azure credential is rejected sees the socket vanish with no explanation, and a platform team cannot join the gateway's LLM span to their own trace

1. They run wscat -c "wss://litellm-domain/v1/realtime?model=azure-realtime" -H "Authorization: Bearer sk-..."
2. wscat prints Connected (press CTRL+C to quit)
3. Nothing arrives, then wscat prints Disconnected (code: 1006, reason: "")
4. Separately, the proxy admin sets callback_settings.otel.baggage_metadata_keys: [requester_metadata.trace_id] and the developer sends POST https://litellm-domain/v1/chat/completions with "metadata": {"trace_id": "abc"}
5. The request returns 200, but the LLM-call span in their tracing backend has no litellm.metadata.trace_id attribute

After: the realtime client is told what the upstream said and the caller's trace id lands on the span

1. They run wscat -c "wss://litellm-domain/v1/realtime?model=azure-realtime" -H "Authorization: Bearer sk-..."
2. wscat prints Connected (press CTRL+C to quit)
3. They receive {"type": "error", "error": {"type": "server_error", "message": "Upstream realtime handshake rejected with HTTP 401"}}, then wscat prints Disconnected (code: 1008, reason: "Upstream realtime handshake rejected with HTTP 401")
4. The proxy admin sets the same baggage_metadata_keys and the developer sends the same POST https://litellm-domain/v1/chat/completions with "metadata": {"trace_id": "abc"}
5. The request returns 200 and the same LLM-call span now carries litellm.metadata.trace_id=abc; non-allowlisted metadata stays off the span

Relevant issues

Backport of #42388 (customer report via Pylon #8933) and #41462 (customer request via Pylon #8571) to stable/1.102.x, plus the test-only follow-up #42624. All three are merged on main and reachable from origin/main. #42152 and #42288 from the original backport list are already on the line via #42538. The Jev passthrough backport stays on #42595

Affected release

Backport target stable/1.102.x, tip version 1.102.1 (not yet tagged or published, so no version bump in this PR)

Linear ticket

Resolves LIT-7058, LIT-7760

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• The handful of test files covering my change pass locally, e.g. uv run pytest tests/test_litellm/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
• My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Shared setup: two proxies with the same config, real Azure and OpenAI keys, OTel v2 on (LITELLM_OTEL_V2=true) with callback_settings.otel.baggage_metadata_keys: [requester_metadata.trace_id, requester_metadata.nested.deep] and a console span exporter writing to the proxy log. azure-realtime-badkey is a real Azure realtime deployment with a wrong key. Before runs the merge base on port 4100, After runs this PR's tip on port 4200. The chat payload is {"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with exactly: pong"}],"max_tokens":5,"metadata":{"trace_id":"abc","nested":{"deep":"x"}}}. Screen recording of this exact run is in the Slack proof thread: https://berriaillm.slack.com/archives/D0BE48UMS58/p1790114060712649?thread_ts=1790114060.712649&cid=D0BE48UMS58

Before (89000e4)

Realtime handshake refused upstream

1. wscat -c "ws://127.0.0.1:4100/v1/realtime?model=azure-realtime-badkey" -H "Authorization: Bearer sk-bp1102"
2. Connected (press CTRL+C to quit) then Disconnected (code: 1006, reason: ""), no event received

Nested metadata promoted to OTEL span attributes

1. curl -s http://127.0.0.1:4100/v1/chat/completions -H "Authorization: Bearer sk-bp1102" -H "Content-Type: application/json" -d '<payload above>'
2. assistant: pong
3. grep -cE "litellm.metadata.(trace_id|nested)" proxy-before.log prints 0

After (5aa45f1)

Realtime handshake refused upstream

1. wscat -c "ws://127.0.0.1:4200/v1/realtime?model=azure-realtime-badkey" -H "Authorization: Bearer sk-bp1102"
2. Connected (press CTRL+C to quit)
3. < {"type": "error", "error": {"type": "server_error", "message": "Upstream realtime handshake rejected with HTTP 401"}}
4. Disconnected (code: 1008, reason: "Upstream realtime handshake rejected with HTTP 401")

Nested metadata promoted to OTEL span attributes

1. curl -s http://127.0.0.1:4200/v1/chat/completions -H "Authorization: Bearer sk-bp1102" -H "Content-Type: application/json" -d '<payload above>'
2. assistant: pong
3. grep -oE "\"litellm.metadata.(trace_id|nested)[^,]*" proxy-after.log | tail -3 prints "litellm.metadata.nested.deep": "x", "litellm.metadata.trace_id": "abc", "litellm.metadata.nested.deep": "x" (24 matches)

Proxy sanity on the tip: /health/liveliness 200, /v1/models 200 listing the three deployments, a plain chat completion answers Ok!. OpenAI realtime with a bad key behaves the same before and after because OpenAI accepts the upgrade and returns its own error event over the socket, so only the Azure leg exercises the handshake path

Type

🐛 Bug Fix
🆕 New Feature
🚄 Infrastructure

Caveats (if any)

Low

• feat(otel): promote nested request metadata keys to litellm.metadata.* span attributes #41462 is picked as its merge commit (-m 1), so its commit subject reads Merge pull request #41462; the body carries the feat title and the cherry-pick footer
• fix(realtime): surface an upstream handshake refusal as an error event and policy close #42388 pick is adapted for context drift only in llm_http_handler.py (await vs return await on the line before the changed hunk); changed lines identical, patch-id differs for that reason alone
• fix(realtime): surface an upstream handshake refusal as an error event and policy close #42388 narrows the per-provider realtime catch from the deprecated InvalidStatusCode to InvalidStatus, which on the line's pinned websockets 15.0.1 is not a superclass of InvalidStatusCode. Two tests on the line raised the deprecated class and asserted a 403 close code; test(realtime): drop legacy InvalidStatusCode tests and pin websockets imports #42624 removes them on main and is picked here so the branch tracks main exactly
• soupsieve resolves as 2.9 in uv.lock (upstream tag name), equal to 2.9.0, and only ships in the ci group, so it does not appear in the default runtime venv
• two scanner findings (mlflow 3.15.0 High, diskcache 5.6.3 Medium) have no upstream fix and are unchanged versus main

Backport qualification

Base 89000e4 (origin/stable/1.102.x tip). All picks applied with zero conflicts, .github untouched, every referenced identifier resolves on the line. Targeted tests: 910 passed at base, 924 passed after the picks with zero new failures; every unit test from both source PRs passes; the three test files touched by #42624 pass alone and together (25/25). ruff check clean on touched files, mypy error count unchanged versus base (76 both sides), ruff format debt unchanged versus base. Lock diff is confined to the anyio and soupsieve entries

Full tests/test_litellm run on both trees (four sequential chunks each, same test list, whole-suite runs OOM on this box): base 71 failed + 1 error / 55598 passed, branch before #42624 76 failed + 1 error / 55636 passed. The 13 new-on-branch ids were rerun alone: 9 pass alone (flaky settings and batch tests), 2 fail alone on base too (external mode lookup and tokenizer env), 2 were the stale redaction tests now removed by the #42624 pick. No unresolved regression remains at the tip

Scanner: baseline Critical and Medium anyio findings and both soupsieve Mediums are gone after the bump; no new findings versus base

Gauntlet (universal, standard depth, five lenses, clean tree pinned at 5aa45f1) returned SURVIVED on all five sub-claims: identifier and config-key closure, both picks delivering their behavior on this line, no broken stable-only callers, anyio 4.14.2 and soupsieve 2.9 resolving as expected, and the three #42624 test files passing alone and together with no remaining InvalidStatusCode test. An earlier run at da246e9 refuted only a mis-worded dependency clause (it required soupsieve in the runtime venv, where the ci group never installs it) and was classed not a regression

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

---

Note

Medium Risk
Touches realtime WebSocket error handling and OTEL attribute/baggage promotion across proxy and integrations; behavior changes are intentional but affect observability and client-visible close semantics.

Overview
Backports two customer-facing fixes to stable/1.102.x: clearer realtime failures when the upstream WebSocket handshake is rejected, and allowlisted promotion of nested caller metadata onto OpenTelemetry spans.

Realtime: Upstream handshake failures now catch InvalidStatus (replacing deprecated InvalidStatusCode) and use shared close_after_upstream_handshake_refusal: emit an OpenAI-style error event, then close with RFC-appropriate codes (e.g. 401/403 → 1008, 429 → 1013). Applied across proxy, OpenAI/Azure handlers, and generic HTTP realtime paths; Azure also sends an error event on unexpected internal failures.

OTEL: Adds baggage_metadata_keys / LITELLM_OTEL_BAGGAGE_METADATA_KEYS on v1 and v2. Nested requester_metadata is flattened and allowlisted paths (e.g. requester_metadata.trace_id) stamp litellm.metadata.trace_id on spans and request baggage from the pre-call hook, without dumping unlisted keys.

Tests and e2e cover both behaviors; lockfile bumps anyio and soupsieve only.

^{Reviewed by Cursor Bugbot for commit 5aa45f1. Bugbot is set up for automated code reviews on this repo. Configure here.}

Link to Devin session: https://app.devin.ai/sessions/97da7793a06d4de3b4561b4a605cb3a9
Open in Devin Desktop: https://app.devin.ai/desktop/session/97da7793a06d4de3b4561b4a605cb3a9?variant=devin

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 3 committers have signed the CLA.

✅ yuneng-berri
❌ yassin-berriai
❌ devin-ai-integration[bot]
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with no outstanding previous findings or newly introduced actionable issues.

Summary

This backport improves realtime handshake-refusal reporting, adds allowlisted nested request metadata to OpenTelemetry spans, and refreshes two locked dependencies.

• Sends a structured realtime error event and maps rejected upstream handshakes to valid WebSocket close codes.
• Flattens nested caller metadata and promotes only configured paths in both OpenTelemetry implementations.
• Adds focused unit and E2E coverage for the new behavior.
• Updates anyio to 4.14.2 and soupsieve to 2.9 in the lockfile.
• The changes since the previous review only correct test imports and remove stale tests for an unsupported legacy exception path.

_{Reviews (2) · Last reviewed commit: "test(realtime): drop legacy InvalidStatu..."}

[devin-ai-integration]

@greptileai

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 5aa45f1. Configure here.}