fix(otel): accept UPPER_SNAKE_CASE OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT in v2

[yassin-berriai]

Relevant issues

Follow-up to the OTel V2 content-capture work in #30548. Once the genai mapper learned to stamp gen_ai.input.messages / gen_ai.output.messages, a second regression became visible: the capture mode env var is case-sensitive in V2.

Linear ticket

Resolves LIT-3791

Pre-Submission checklist

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

• I have added meaningful tests
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review (Greptile returned 5/5)

What's the bug

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT used to be case-insensitive. V1 (litellm/integrations/opentelemetry.py) normalizes the value with .upper() before matching, so an operator could set the documented UPPER_SNAKE_CASE form SPAN_AND_EVENT and content capture turned on.

In V2 (litellm/integrations/otel/model/config.py), OpenTelemetryV2Config.capture_span_content compares self.capture_message_content directly against the lower_snake_case canonical constants (span_only, span_and_event) with no normalization. An operator who carries their V1 setting OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT forward gets capture_span_content == False, messages_in stays empty, and gen_ai.input.messages / gen_ai.output.messages never land on the span. No error is raised; capture just silently stays off. Only the lowercase span_and_event worked.

The fix

Normalize the value to lower case once at the config boundary with a field_validator on capture_message_content, so the stored value is always canonical and every downstream comparison stays exact. This restores V1's case-insensitive behavior; SPAN_AND_EVENT and span_and_event both enable capture now.

Screenshots / Proof of Fix

Live proxy against the real OpenAI API with the OTel V2 console exporter, using the uppercase SPAN_AND_EVENT value an operator would carry over from V1. The only thing that changes between the two runs is this one-line fix.

Launch (console exporter forced so spans print to the log; only OPENAI_API_KEY is taken from .env):

export OPENAI_API_KEY=...                       # real key
export LITELLM_OTEL_V2=1
export OTEL_EXPORTER=console
export OTEL_ENDPOINT=""                          # keep the console exporter (no OTLP)
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT
python litellm/proxy/proxy_cli.py --config config.yaml --port 4000 > proxy.log 2>&1 &

# config.yaml
model_list:
  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
litellm_settings:
  callbacks: ["otel"]
general_settings:
  master_key: sk-1234

Send one real chat completion, then read the gen_ai attribute keys off the exported span:

curl -s http://localhost:4000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-1234' \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hello there reply with the single word ok"}]}'

grep -oE '"gen_ai\.[a-z_.]+":' proxy.log | sort -u

The curl returns a real completion ("content":"ok") in both runs, so the upstream call is healthy in both; the difference is purely whether the prompt/response are captured.

Before the fix, the span is exported but carries no message content:

"gen_ai.operation.name":
"gen_ai.provider.name":
"gen_ai.request.model":
"gen_ai.response.finish_reasons":
"gen_ai.response.id":
"gen_ai.response.model":
"gen_ai.system":
"gen_ai.usage.completion_tokens":
"gen_ai.usage.input_tokens":
"gen_ai.usage.output_tokens":
"gen_ai.usage.prompt_tokens":
"gen_ai.usage.total_tokens":

After the fix, the same uppercase SPAN_AND_EVENT now captures the content:

"gen_ai.input.messages":          <-- new
"gen_ai.operation.name":
"gen_ai.output.messages":         <-- new
"gen_ai.provider.name":
"gen_ai.request.model":
"gen_ai.response.finish_reasons":
"gen_ai.response.id":
"gen_ai.response.model":
"gen_ai.system":
"gen_ai.usage.completion_tokens":
"gen_ai.usage.input_tokens":
"gen_ai.usage.output_tokens":
"gen_ai.usage.prompt_tokens":
"gen_ai.usage.total_tokens":

and the stamped attribute holds the actual prompt:

"gen_ai.input.messages": "[{\"role\": \"user\", \"content\": \"hello there reply with the single word ok\"...

The regression test test_capture_span_content_resolves_modes asserts OpenTelemetryV2Config(capture_message_content="SPAN_AND_EVENT").capture_span_content is True; it fails on the unfixed config (the casing makes it False) and passes with the fix.

Type

🐛 Bug Fix

Changes

litellm/integrations/otel/model/config.py gains a mode="before" field_validator on capture_message_content that lower-cases the incoming value, so the canonical lower_snake_case constants match regardless of the casing an operator supplies. The mapped test tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py is extended to cover the UPPER_SNAKE_CASE inputs SPAN_AND_EVENT, SPAN_ONLY, and NO_CONTENT

[yassin-berriai]

@greptileai

[greptile-apps]

Greptile Summary

This PR fixes a regression in the OTel V2 integration where OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT was case-sensitive, silently disabling content capture for operators carrying over the uppercase SPAN_AND_EVENT value from V1.

• A single field_validator("capture_message_content", mode="before") normalizes the incoming string to lowercase before it reaches the stored field, so all downstream comparisons against the CaptureMessageContent constants remain exact and no callers need to change.
• The validator correctly passes non-string values through unchanged, leaving Pydantic's own type coercion to reject them with a ValidationError — verified by the new test_capture_message_content_normalizer_only_touches_strings test.

Confidence Score: 5/5

Safe to merge: the change is a one-line normalization at the config boundary with no behavioral impact on already-lowercase values and a targeted test suite that covers the regression.

The validator is applied only to capture_message_content, does not change anything for operators already using lowercase values, and is exercised by both the extended existing test and a new dedicated unit test. No other code paths are touched.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/integrations/otel/model/config.py	Adds a mode="before" field_validator on capture_message_content that lowercases incoming string values, restoring the case-insensitive env-var behavior from V1. Minimal, well-placed, and does not affect any other field.
tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py	Extends test_capture_span_content_resolves_modes with uppercase assertions for SPAN_AND_EVENT, SPAN_ONLY, and NO_CONTENT, and adds a new test verifying non-string values still fail field validation. No existing assertions are weakened.

_{Reviews (4): Last reviewed commit: "test(otel): cover non-string passthrough..." | Re-trigger Greptile}

[greptile-apps]

Greptile Summary

This PR fixes a case-sensitivity regression in the OTel V2 config where OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT set to UPPER_SNAKE_CASE values (as documented and accepted by V1) silently disabled message content capture. A single mode="before" field_validator now lowercases the incoming string at the config boundary, making the comparison against the canonical lower_snake_case constants always work.

• litellm/integrations/otel/model/config.py: Adds _normalize_capture_message_content validator that calls .lower() on the raw string before Pydantic stores it; non-string values pass through unchanged.
• tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py: Extends the existing test_capture_span_content_resolves_modes test with three new assertions covering SPAN_AND_EVENT, SPAN_ONLY, and NO_CONTENT in UPPER_SNAKE_CASE; no existing assertions are modified.

Confidence Score: 5/5

Safe to merge. The change is a one-line normalization applied once at the config boundary, with no effect on callers that already pass lowercase values.

The fix is minimal and correctly scoped: the mode="before" validator fires before Pydantic's own type coercion, so enum-typed constants (already lowercase) and raw strings alike are handled correctly. Existing tests are only extended with new assertions, never weakened. The added tests directly reproduce the reported failure mode and confirm the fix works for all three UPPER_SNAKE_CASE variants. No existing behavior changes for operators who were already using lowercase values.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/integrations/otel/model/config.py	Adds a mode="before" field_validator that lowercases capture_message_content at the config boundary, restoring V1's case-insensitive behavior for the capture-mode env var.
tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py	Extends test_capture_span_content_resolves_modes with three additional assertions covering UPPER_SNAKE_CASE inputs (SPAN_AND_EVENT, SPAN_ONLY, NO_CONTENT). Existing assertions are unchanged.

_{Reviews (2): Last reviewed commit: "fix(otel): accept UPPER_SNAKE_CASE OTEL_..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[yassin-berriai]

Greptile returned a Confidence Score of 5/5.

Heads up on CI: the lint job is red, but only at the basedpyright budget step, and it is pre-existing drift on litellm_internal_staging rather than anything from this change. basedpyright measures absolute codebase totals against committed ceilings, and the base branch is currently above them, so every open PR's lint fails identically. For example #30555 fails with the exact same per-rule counts (reportAny 25009 over cap 24964, reportUnknownArgumentType 30763 over cap 30613, reportUnknownMemberType 27375 over cap 27332, and the same overage on reportExplicitAny / reportMissingTypeArgument / reportUnknownParameterType / reportUnknownVariableType). This PR's own typed gates are green: Black, Ruff, the strict-rule budget delta, MyPy, and any-discipline all pass, and the added validator is annotated with object rather than Any so it contributes nothing to those counts. I am intentionally not bumping the ceiling here so the budget keeps ratcheting down through dedicated maintenance instead of inflating inside a feature PR.

[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.}

[yassin-berriai]

Rebased onto latest litellm_internal_staging (now includes #30563 which raised the basedpyright ceilings), so the lint job should be green here. @greptileai please re-review the rebased HEAD

[mateo-berri]

@greptileai

[mateo-berri]

LGTM; thanks!