fix(jwt,otel): backport session conversation id and JWT team header selection to rc/1.103.0

[yuneng-berri]

TLDR

Problem this solves:

• v2 OTel spans on rc/1.103.0 carry no gen_ai.conversation.id
• JWT callers cannot pick a DB membership team when the token has a team claim

How it solves it:

• Cherry-picks four PRs from main onto rc/1.103.0, one commit each
• feat(otel): emit gen_ai.conversation.id from the caller's session id on v2 LLM spans #42486: v2 LLM spans carry the caller's session id as gen_ai.conversation.id
• fix(jwt): accept a team alias in x-litellm-team-id #42445: x-litellm-team-id accepts a team alias as well as a team id
• fix(jwt): say x-litellm-team-id matched no team id or alias in the 403 #42495: the 403 for an unmatched header says it matched no id or unique alias
• fix(jwt): let x-litellm-team-id select DB membership teams when the token also carries a team claim #43206: with fallback_to_db_teams on, the header can pick any team the caller belongs to

Intentional product change: with fallback_to_db_teams: true, a header naming a team the caller is not in now gets a 403 reading "among your team memberships" instead of listing the JWT's team ids

User Flow

Before: on rc/1.103.0 a JWT developer and an OTel user each hit a gap that main already fixed

1. A developer sends POST http://localhost:4000/v1/chat/completions with "litellm_session_id": "conv-1", and their OTel backend shows the span with no gen_ai.conversation.id
2. A developer whose JWT lists team-eng sends x-litellm-team-id: engineering, that team's alias, and gets 403
3. A developer whose Entra token resolves appid to a team sends x-litellm-team-id: team-db-1, another team they belong to, with fallback_to_db_teams on, and gets 403

After: the same requests behave the way they do on main

1. The span for the same request carries gen_ai.conversation.id: "conv-1", and a request with no session id still has none
2. The alias request returns 200 and is billed to team-eng
3. The membership request returns 200 and is billed to team-db-1, while a team they are not in still gets 403

Relevant issues

Backport of #42486, #42445, #42495 and #43206

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)

tests/test_litellm/proxy/auth and tests/test_litellm/integrations/otel pass on this branch (3067 tests with the local cost map). With the remote cost map, one unrelated imagen pricing test also fails on the rc tip. Each pick's own tests were also run with its source change reverted, and they fail there: #42486 22 failures, #42445 an import error, #42495 4, #43206 3

Adaptations from the main versions:

• fix(jwt): let x-litellm-team-id select DB membership teams when the token also carries a team claim #43206 builds on fix(jwt): accept a team alias in x-litellm-team-id #42445 and fix(jwt): say x-litellm-team-id matched no team id or alias in the 403 #42495, which rc/1.103.0 did not have, so both come along and apply unchanged
• feat(otel): emit gen_ai.conversation.id from the caller's session id on v2 LLM spans #42486: tests/integration/contracts.json conflicted because main's copy has moved on, so only this PR's 23 test entries were added
• fix(jwt): accept a team alias in x-litellm-team-id #42445: its five new patch() calls carry a test-quality-ok reason, since rc/1.103.0 is already over its TQ008 budget

Type

🆕 New Feature
🐛 Bug Fix

Caveats (if any)

Severe

• Auth behavior change for JWT deployments with fallback_to_db_teams: true
  • The header can now select any DB membership team, not only the JWT's teams
  • Membership is still checked, and a team the caller is not in still gets 403
• x-litellm-team-id now also accepts team aliases on every JWT deployment

Medium

• Live proxy proof on rc/1.103.0 is not captured yet
• feat(otel): emit gen_ai.conversation.id from the caller's session id on v2 LLM spans #42486 is a feature, not a regression fix

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[greptile-apps]

Confidence Score: 4/5

[High risk] JWT team selection and observability session tracking.

The PR is not ready to merge until the observability tests can be collected and the critical-path database-query requirement is satisfied.

Findings

1.  Observability tests cannot load ▶
2.  Alias headers repeatedly query database ▶

Summary

This backport adds caller session IDs to v2 OTel LLM spans and lets JWT team headers select aliases or, when DB fallback is enabled, DB membership teams.

• The new observability test module cannot be collected because it imports unavailable test-support symbols.
• Alias selection under DB fallback adds an avoidable database query to the JWT request path.

_{Reviews (1) · Last reviewed commit: "fix(jwt): let x-litellm-team-id select D..."}

[greptile-apps]

Observability tests cannot load

When this test file is collected, its import of OwnedProxy and owned_proxy_process fails because integration._support.process defines neither name. None of the new conversation-ID tests can run. The existing owned_proxy helper returns a Gateway, not the process wrapper these tests expect.

[greptile-apps]

Alias headers repeatedly query database

With fallback_to_db_teams enabled, a team alias outside the JWT's allowed IDs is first looked up as a team ID. A missing ID raises before that result is cached, so every request with the alias repeats the database query even if the alias itself is cached. This violates the repository directive to avoid new database requests in the critical request path; the requirement must be satisfied before merging.

Rule Used: What: Avoid creating new database requests or Router objects in the critical request path. Why: Creating these objects on every request causes performance degradation and unnecessary resource consumption. (source)