feat: support OTEL GenAI semconv

[Michael-RZ-Berri]

Relevant issues

This PR adds an opt-in (OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental, or OpenTelemetryConfig(semconv_stability_opt_in=...)) that switches the emitted traces to the experimental OTEL GenAI semantic conventions. Default behavior is unchanged when the opt-in is not set; the table below shows exactly what flips when it is.

Aspect	Default (opt-in off)	With opt-in
Top span name	litellm_request	<operation> <model> (e.g. chat gpt-4)
Span kind	internal	CLIENT
raw_gen_ai_request child span	emitted	dropped (non-standard)
Provider attribute	gen_ai.system	gen_ai.provider.name (gen_ai.system dropped)
llm.is_streaming	emitted	dropped
Extra request attrs	—	gen_ai.request.{frequency_penalty,presence_penalty,top_k,seed}, gen_ai.request.stop_sequences (array), gen_ai.request.stream (only when streaming), gen_ai.request.choice.count (only when n>1), gen_ai.usage.cache_{creation,read}.input_tokens
Content events	per-message gen_ai.content.prompt / per-choice gen_ai.content.completion	single gen_ai.client.inference.operation.details event
gen_ai.input/output.messages, gen_ai.cost.*	emitted	unchanged (base behavior, not gated by the opt-in)

Linear ticket

Resolves LIT-3166

Pre-Submission checklist

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

• I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
• 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

Screenshots / Proof of Fix

Send a POST request to v1/chat/completions

curl -s $BASE/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"What is 2+2?"}],"mock_response":"2+2 is 4."}' \
  | jq '.choices[0].message.content'
"ok"

OTEL_SEMCONV_STABILITY_OPT_IN not set

OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

Type

🆕 New Feature
✅ Test

Changes

Opt-in

A new opt-in selects the experimental OTEL GenAI semantic conventions. It can be set via:

• env: OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental (comma-separated, per the OTEL spec), or
• programmatically: OpenTelemetryConfig(semconv_stability_opt_in={OTELSemconvCategory.GEN_AI_LATEST_EXPERIMENTAL}).

The env and programmatic values are resolved/unioned once in OpenTelemetryConfig.__post_init__, so config.semconv_stability_opt_in (a typed Set[OTELSemconvCategory]) is the single source of truth. When the opt-in is not set, span/event output is unchanged.

Structure

The semconv-specific behavior lives in a new module litellm/integrations/opentelemetry_utils/gen_ai_semconv.py:

• OTELSemconvCategory + parse_semconv_opt_in (opt-in primitives used by OpenTelemetryConfig)
• OTELGenAISemconvMixin, mixed into OpenTelemetry, holding the semconv span/event behavior. The mixin↔host contract is documented in the class docstring.

Span changes (when opted in)

• name is {operation} {model} (e.g. chat gpt-4) instead of litellm_request; span kind=CLIENT
• gen_ai.operation.name is the actual operation (chat / text_completion / embeddings) instead of always chat
• provider is reported as gen_ai.provider.name; the superseded gen_ai.system and the legacy llm.is_streaming are not emitted in this mode
• adds gen_ai.request.{frequency_penalty,presence_penalty,top_k,seed}, gen_ai.request.stop_sequences (a string array), gen_ai.request.stream (only when streaming), gen_ai.request.choice.count (only when n > 1), and gen_ai.usage.cache_{creation,read}.input_tokens
• the non-standard raw_gen_ai_request child span is no longer created

Event changes (when opted in)

• the per-message gen_ai.content.prompt / per-choice gen_ai.content.completion log events are replaced by a single gen_ai.client.inference.operation.details log event carrying gen_ai.input.messages / gen_ai.output.messages in the spec parts shape (multi-choice preserved; message content still gated by the existing content kill-switch)

Conditional-attribute rules and the span-vs-event split follow the OTEL GenAI spec.

[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]

Greptile Summary

Introduces an opt-in GenAI semantic-conventions mode for the OpenTelemetry integration, enabled via OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental (or OpenTelemetryConfig.semconv_stability), with no behavioural change when the flag is absent.

• Span changes: primary spans get SpanKind.CLIENT, a semconv-style name (<operation> <model>), and skip the non-standard raw_gen_ai_request child; gen_ai.provider.name is emitted alongside the legacy gen_ai.system alias.
• Attribute additions: new request attributes (frequency_penalty, presence_penalty, top_k, seed, stop_sequences, stream as bool, choice.count) and Anthropic cache-token usage attributes are added only in semconv mode.
• Log event consolidation: per-message/per-choice log events are replaced with a single gen_ai.client.inference.operation.details record; the legacy path is completely unchanged.

Confidence Score: 5/5

Safe to merge — the entire feature is behind a new opt-in flag and the existing default code path is completely unmodified.

All new behaviour is strictly gated behind _gen_ai_semconv_latest_experimental, which is False by default. The legacy span naming, raw_gen_ai_request child span, per-message/choice log events, and all existing attributes are unchanged when the flag is not set. The new code paths are well-tested with mocks and an in-memory exporter (no live network calls). The or {} guard on metadata in _set_semconv_cache_token_attributes handles None correctly, and the if value: zero-skip on cache tokens is deliberate and covered by an explicit test.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/integrations/opentelemetry.py	Adds opt-in GenAI semconv mode: new span naming/kind, provider alias, request/cache-token attributes, and a consolidated inference-details log event — all gated cleanly behind _gen_ai_semconv_latest_experimental. No regressions to the default code path.
tests/test_litellm/integrations/test_opentelemetry.py	Adds comprehensive unit tests for every new semconv behaviour (env/config opt-in, span naming, raw-span skip, request attributes, cache token attributes, consolidated log event). Tests use mocks and InMemoryLogExporter — no real network calls.

_{Reviews (2): Last reviewed commit: "honor OTEL_SEMCONV_STABILITY_OPT_IN" | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 95.45455% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/integrations/opentelemetry.py	90.69%	4 Missing ⚠️
...integrations/opentelemetry_utils/gen_ai_semconv.py	98.50%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Michael-RZ-Berri]

@greptile-ai

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Semconv event bypasses message logging kill switch
  • Replaced the semconv inference event content gate with _capture_in_event() and added a regression test for the global message logging kill switch.

Preview (65cc84ed43)

diff --git a/litellm/integrations/opentelemetry.py b/litellm/integrations/opentelemetry.py
--- a/litellm/integrations/opentelemetry.py
+++ b/litellm/integrations/opentelemetry.py
@@ -67,6 +67,8 @@
     CAPTURE_MODE_EVENT_ONLY,
     CAPTURE_MODE_SPAN_AND_EVENT,
 }
+OTEL_SEMCONV_STABILITY_OPT_IN_ENV = "OTEL_SEMCONV_STABILITY_OPT_IN"
+GEN_AI_LATEST_EXPERIMENTAL = "gen_ai_latest_experimental"
 
 
 @dataclass
@@ -85,6 +87,8 @@
     # Programmatic override for OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT.
     # One of NO_CONTENT, SPAN_ONLY, EVENT_ONLY, SPAN_AND_EVENT (or "true" as legacy alias).
     capture_message_content: Optional[str] = None
+    # Programmatic override for OTEL_SEMCONV_STABILITY_OPT_IN.
+    semconv_stability: Optional[str] = None
 
     def __post_init__(self) -> None:
         # If endpoint is specified but exporter is still the default "console",
@@ -199,6 +203,9 @@
         # Sample env-var / config / message_logging at init so subsequent
         # _capture_in_span / _capture_in_event calls are deterministic.
         self._capture_mode_cached = self._compute_capture_mode_from_init_state()
+        self._gen_ai_semconv_latest_experimental = (
+            self._compute_gen_ai_semconv_latest_experimental()
+        )
         self._init_otel_logger_on_litellm_proxy()
 
     @staticmethod
@@ -379,6 +386,125 @@
             CAPTURE_MODE_SPAN_AND_EVENT,
         )
 
+    def _compute_gen_ai_semconv_latest_experimental(self) -> bool:
+        # Comma-separated list per the OTEL spec.
+        explicit = self.config.semconv_stability or os.getenv(
+            OTEL_SEMCONV_STABILITY_OPT_IN_ENV
+        )
+        if not explicit:
+            return False
+        return GEN_AI_LATEST_EXPERIMENTAL in {c.strip() for c in explicit.split(",")}
+
+    def _gen_ai_operation_name(self, kwargs: dict) -> str:
+        call_type = kwargs.get("call_type", "") or ""
+        if "embedding" in call_type:
+            return "embeddings"
+        if "text_completion" in call_type:
+            return "text_completion"
+        return "chat"
+
+    def _set_semconv_request_attributes(
+        self, span: Span, optional_params: dict
+    ) -> None:
+        for source_key, semconv_key in {
+            "frequency_penalty": "gen_ai.request.frequency_penalty",
+            "presence_penalty": "gen_ai.request.presence_penalty",
+            "top_k": "gen_ai.request.top_k",
+            "seed": "gen_ai.request.seed",
+        }.items():
+            value = optional_params.get(source_key)
+            if value is not None:
+                self.safe_set_attribute(span=span, key=semconv_key, value=value)
+
+        stop = optional_params.get("stop")
+        if stop is not None:
+            self.safe_set_attribute(
+                span=span,
+                key="gen_ai.request.stop_sequences",
+                value=safe_dumps(stop if isinstance(stop, list) else [stop]),
+            )
+
+        self.safe_set_attribute(
+            span=span,
+            key="gen_ai.request.stream",
+            value=bool(optional_params.get("stream", False)),
+        )
+
+        # Required only when n != 1 per spec.
+        n = optional_params.get("n")
+        if n is not None and n != 1:
+            self.safe_set_attribute(
+                span=span, key="gen_ai.request.choice.count", value=n
+            )
+
+    def _set_semconv_cache_token_attributes(
+        self, span: Span, standard_logging_payload
+    ) -> None:
+        if not standard_logging_payload:
+            return
+        usage = (standard_logging_payload.get("metadata") or {}).get(
+            "usage_object"
+        ) or {}
+        for source_key, semconv_key in (
+            ("cache_creation_input_tokens", "gen_ai.usage.cache_creation.input_tokens"),
+            ("cache_read_input_tokens", "gen_ai.usage.cache_read.input_tokens"),
+        ):
+            value = usage.get(source_key)
+            if value:
+                self.safe_set_attribute(span=span, key=semconv_key, value=value)
+
+    def _emit_inference_details_event(
+        self,
+        kwargs: dict,
+        response_obj: dict,
+        provider: str,
+        otel_logger,
+        parent_ctx,
+        LogRecordCls,
+        SeverityNumber,
+    ) -> None:
+        attrs: Dict[str, Any] = {
+            "event_name": "gen_ai.client.inference.operation.details",
+            "gen_ai.provider.name": provider,
+            "gen_ai.operation.name": self._gen_ai_operation_name(kwargs),
+        }
+
+        if self._capture_in_event():
+            input_messages = self._transform_messages_to_otel_semantic_conventions(
+                kwargs.get("messages") or []
+            )
+            output_messages = []
+            for choice in response_obj.get("choices", []):
+                body_msg = choice.get("message", {}) or {}
+                output_messages.append(
+                    {
+                        "role": body_msg.get("role", "assistant"),
+                        "parts": [
+                            {
+                                "type": "text",
+                                "content": body_msg.get("content", ""),
+                            }
+                        ],
+                        "finish_reason": choice.get("finish_reason"),
+                    }
+                )
+            if input_messages:
+                attrs["gen_ai.input.messages"] = safe_dumps(input_messages)
+            if output_messages:
+                attrs["gen_ai.output.messages"] = safe_dumps(output_messages)
+
+        log_record = LogRecordCls(
+            timestamp=self._to_ns(datetime.now()),
+            trace_id=parent_ctx.trace_id,
+            span_id=parent_ctx.span_id,
+            trace_flags=parent_ctx.trace_flags,
+            severity_number=SeverityNumber.INFO,
+            severity_text="INFO",
+            body=None,
+            attributes=attrs,
+        )
+        otel_logger.emit(log_record)
+
     def _init_tracing(self, tracer_provider):
         from opentelemetry import trace
         from opentelemetry.sdk.trace import TracerProvider
@@ -879,13 +1005,14 @@
 
         otel_tracer: Tracer = self.get_tracer_to_use_for_request(kwargs)
 
-        # Always create a new span
-        # The parent relationship is preserved through the context parameter
-        span = otel_tracer.start_span(
-            name=self._get_span_name(kwargs),
-            start_time=self._to_ns(start_time),
-            context=context,
-        )
+        span_kwargs: Dict[str, Any] = {
+            "name": self._get_span_name(kwargs),
+            "start_time": self._to_ns(start_time),
+            "context": context,
+        }
+        if self._gen_ai_semconv_latest_experimental:
+            span_kwargs["kind"] = self.span_kind.CLIENT
+        span = otel_tracer.start_span(**span_kwargs)
 
         span.set_status(Status(StatusCode.OK))
         self.set_attributes(span, kwargs, response_obj)
@@ -898,6 +1025,10 @@
         from opentelemetry import trace
         from opentelemetry.trace import Status, StatusCode
 
+        # raw_gen_ai_request is non-standard in semconv mode.
+        if self._gen_ai_semconv_latest_experimental:
+            return
+
         if not self._capture_in_span():
             return
 
@@ -923,7 +1054,11 @@
         provider = params.get("custom_llm_provider", "Unknown")
 
         common_attrs = {
-            "gen_ai.operation.name": "chat",
+            "gen_ai.operation.name": (
+                self._gen_ai_operation_name(kwargs)
+                if self._gen_ai_semconv_latest_experimental
+                else "chat"
+            ),
             "gen_ai.system": provider,
             "gen_ai.request.model": kwargs.get("model"),
             "gen_ai.framework": "litellm",
@@ -1180,6 +1315,18 @@
             "custom_llm_provider", "Unknown"
         )
 
+        if self._gen_ai_semconv_latest_experimental:
+            self._emit_inference_details_event(
+                kwargs=kwargs,
+                response_obj=response_obj,
+                provider=provider,
+                otel_logger=otel_logger,
+                parent_ctx=parent_ctx,
+                LogRecordCls=SdkLogRecord,
+                SeverityNumber=SeverityNumber,
+            )
+            return
+
         # per-message events
         for msg in kwargs.get("messages", []):
             role = msg.get("role", "user")
@@ -1366,11 +1513,14 @@
         if should_create_primary_span:
             # Span 1: Request sent to litellm SDK
             otel_tracer: Tracer = self.get_tracer_to_use_for_request(kwargs)
-            span = otel_tracer.start_span(
-                name=self._get_span_name(kwargs),
-                start_time=self._to_ns(start_time),
-                context=_parent_context,
-            )
+            span_kwargs: Dict[str, Any] = {
+                "name": self._get_span_name(kwargs),
+                "start_time": self._to_ns(start_time),
+                "context": _parent_context,
+            }
+            if self._gen_ai_semconv_latest_experimental:
+                span_kwargs["kind"] = self.span_kind.CLIENT
+            span = otel_tracer.start_span(**span_kwargs)
             span.set_status(Status(StatusCode.ERROR))
             self.set_attributes(span, kwargs, response_obj)
 
@@ -1652,11 +1802,19 @@
             )
 
             # The Generative AI Provider: Azure, OpenAI, etc.
+            provider_name = litellm_params.get("custom_llm_provider", "Unknown")
             self.safe_set_attribute(
                 span=span,
                 key=SpanAttributes.LLM_SYSTEM.value,
-                value=litellm_params.get("custom_llm_provider", "Unknown"),
+                value=provider_name,
             )
+            # gen_ai.system was renamed to gen_ai.provider.name; emit both in semconv mode.
+            if self._gen_ai_semconv_latest_experimental:
+                self.safe_set_attribute(
+                    span=span,
+                    key="gen_ai.provider.name",
+                    value=provider_name,
+                )
 
             # The maximum number of tokens the LLM generates for a request.
             if optional_params.get("max_tokens"):
@@ -1688,6 +1846,10 @@
                 value=str(optional_params.get("stream", False)),
             )
 
+            if self._gen_ai_semconv_latest_experimental:
+                self._set_semconv_request_attributes(span, optional_params)
+                self._set_semconv_cache_token_attributes(span, standard_logging_payload)
+
             if optional_params.get("user"):
                 self.safe_set_attribute(
                     span=span,
@@ -1807,14 +1969,18 @@
                         value=safe_dumps(transformed_system_instructions),
                     )
 
+            if self._gen_ai_semconv_latest_experimental:
+                operation_name = self._gen_ai_operation_name(kwargs)
+            else:
+                operation_name = (
+                    "chat"
+                    if standard_logging_payload.get("call_type") == "completion"
+                    else standard_logging_payload.get("call_type") or "chat"
+                )
             self.safe_set_attribute(
                 span=span,
                 key=SpanAttributes.GEN_AI_OPERATION_NAME.value,
-                value=(
-                    "chat"
-                    if standard_logging_payload.get("call_type") == "completion"
-                    else standard_logging_payload.get("call_type") or "chat"
-                ),
+                value=operation_name,
             )
 
             if standard_logging_payload.get("request_id"):
@@ -2151,6 +2317,10 @@
         if generation_name:
             return generation_name
 
+        if self._gen_ai_semconv_latest_experimental:
+            model = kwargs.get("model") or "unknown"
+            return f"{self._gen_ai_operation_name(kwargs)} {model}"
+
         return LITELLM_REQUEST_SPAN_NAME
 
     def get_traceparent_from_header(self, headers):

diff --git a/tests/test_litellm/integrations/test_opentelemetry.py b/tests/test_litellm/integrations/test_opentelemetry.py
--- a/tests/test_litellm/integrations/test_opentelemetry.py
+++ b/tests/test_litellm/integrations/test_opentelemetry.py
@@ -545,6 +545,285 @@
         self.assertTrue(kept._capture_in_event())
 
 
+class TestOpenTelemetrySemconvStability(unittest.TestCase):
+    """OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental opts into
+    semconv-conformant span shape (name, kind, no raw_gen_ai_request child)."""
+
+    @staticmethod
+    def _make(env=None, config_value=None):
+        env_value = env if env is not None else ""
+        with patch.dict(os.environ, {"OTEL_SEMCONV_STABILITY_OPT_IN": env_value}):
+            return OpenTelemetry(
+                config=OpenTelemetryConfig(
+                    exporter="console",
+                    semconv_stability=config_value,
+                )
+            )
+
+    def test_default_unset_keeps_legacy_span_name(self):
+        h = self._make()
+        self.assertFalse(h._gen_ai_semconv_latest_experimental)
+        kwargs = {"model": "gpt-4", "call_type": "acompletion"}
+        self.assertEqual(h._get_span_name(kwargs), "litellm_request")
+
+    def test_opt_in_emits_semconv_span_name(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        self.assertTrue(h._gen_ai_semconv_latest_experimental)
+        kwargs = {"model": "gpt-4", "call_type": "acompletion"}
+        self.assertEqual(h._get_span_name(kwargs), "chat gpt-4")
+
+    def test_opt_in_supports_comma_separated_categories(self):
+        h = self._make(env="other_category,gen_ai_latest_experimental")
+        self.assertTrue(h._gen_ai_semconv_latest_experimental)
+
+    def test_opt_in_ignores_unrelated_category(self):
+        h = self._make(env="some_other_category")
+        self.assertFalse(h._gen_ai_semconv_latest_experimental)
+
+    def test_config_field_overrides_env(self):
+        h = self._make(env="", config_value="gen_ai_latest_experimental")
+        self.assertTrue(h._gen_ai_semconv_latest_experimental)
+
+    def test_operation_name_for_embeddings(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        kwargs = {
+            "model": "text-embedding-3-small",
+            "call_type": "aembedding",
+        }
+        self.assertEqual(h._get_span_name(kwargs), "embeddings text-embedding-3-small")
+
+    def test_operation_name_for_text_completion(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        kwargs = {"model": "babbage-002", "call_type": "atext_completion"}
+        self.assertEqual(h._get_span_name(kwargs), "text_completion babbage-002")
+
+    def test_operation_name_defaults_to_chat(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        kwargs = {"model": "claude-sonnet-4-5", "call_type": "unknown"}
+        self.assertEqual(h._get_span_name(kwargs), "chat claude-sonnet-4-5")
+
+    def test_generation_name_metadata_overrides_semconv_name(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        kwargs = {
+            "model": "gpt-4",
+            "call_type": "acompletion",
+            "litellm_params": {"metadata": {"generation_name": "user-named-span"}},
+        }
+        self.assertEqual(h._get_span_name(kwargs), "user-named-span")
+
+    def test_opt_in_skips_raw_gen_ai_request_span(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        h._maybe_log_raw_request = OpenTelemetry._maybe_log_raw_request.__get__(h)
+        h.tracer = MagicMock()
+        h.set_raw_request_attributes = MagicMock()
+        kwargs = {"litellm_params": {"metadata": {}}}
+        h._maybe_log_raw_request(kwargs, {}, None, None, MagicMock())
+        h.tracer.start_span.assert_not_called()
+
+    def test_semconv_request_attributes_emit_when_present(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        span = MagicMock()
+        optional_params = {
+            "frequency_penalty": 0.5,
+            "presence_penalty": 0.2,
+            "top_k": 40,
+            "seed": 42,
+            "stop": ["\n\n"],
+            "stream": True,
+            "n": 3,
+        }
+        h._set_semconv_request_attributes(span, optional_params)
+        calls = {
+            c.args[0] if c.args else c.kwargs.get("key"): c
+            for c in span.set_attribute.call_args_list
+        }
+        self.assertIn("gen_ai.request.frequency_penalty", calls)
+        self.assertIn("gen_ai.request.presence_penalty", calls)
+        self.assertIn("gen_ai.request.top_k", calls)
+        self.assertIn("gen_ai.request.seed", calls)
+        self.assertIn("gen_ai.request.stop_sequences", calls)
+        self.assertIn("gen_ai.request.stream", calls)
+        self.assertIn("gen_ai.request.choice.count", calls)
+
+    def test_semconv_request_choice_count_omitted_when_one(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        span = MagicMock()
+        h._set_semconv_request_attributes(span, {"n": 1})
+        keys = {c.args[0] for c in span.set_attribute.call_args_list if c.args}
+        self.assertNotIn("gen_ai.request.choice.count", keys)
+
+    def test_semconv_request_stream_emitted_as_bool(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        span = MagicMock()
+        h._set_semconv_request_attributes(span, {"stream": False})
+        stream_calls = [
+            c
+            for c in span.set_attribute.call_args_list
+            if c.args and c.args[0] == "gen_ai.request.stream"
+        ]
+        self.assertEqual(len(stream_calls), 1)
+        self.assertEqual(stream_calls[0].args[1], False)
+
+    def test_semconv_request_stop_sequences_normalizes_string_to_list(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        span = MagicMock()
+        h._set_semconv_request_attributes(span, {"stop": "STOP_TOKEN"})
+        # safe_dumps(["STOP_TOKEN"]) == '["STOP_TOKEN"]'
+        stop_calls = [
+            c
+            for c in span.set_attribute.call_args_list
+            if c.args and c.args[0] == "gen_ai.request.stop_sequences"
+        ]
+        self.assertEqual(len(stop_calls), 1)
+        self.assertIn("STOP_TOKEN", stop_calls[0].args[1])
+
+    def test_semconv_cache_token_attributes(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        span = MagicMock()
+        std_log = {
+            "metadata": {
+                "usage_object": {
+                    "cache_creation_input_tokens": 12,
+                    "cache_read_input_tokens": 34,
+                }
+            }
+        }
+        h._set_semconv_cache_token_attributes(span, std_log)
+        keys = {
+            c.args[0]: c.args[1] for c in span.set_attribute.call_args_list if c.args
+        }
+        self.assertEqual(keys.get("gen_ai.usage.cache_creation.input_tokens"), 12)
+        self.assertEqual(keys.get("gen_ai.usage.cache_read.input_tokens"), 34)
+
+    def test_semconv_cache_token_attributes_handles_none_metadata(self):
+        # standard_logging_payload["metadata"] = None should not crash.
+        h = self._make(env="gen_ai_latest_experimental")
+        span = MagicMock()
+        h._set_semconv_cache_token_attributes(span, {"metadata": None})
+        span.set_attribute.assert_not_called()
+
+    def test_semconv_cache_token_attributes_omitted_when_zero(self):
+        h = self._make(env="gen_ai_latest_experimental")
+        span = MagicMock()
+        std_log = {
+            "metadata": {
+                "usage_object": {
+                    "cache_creation_input_tokens": 0,
+                    "cache_read_input_tokens": 0,
+                }
+            }
+        }
+        h._set_semconv_cache_token_attributes(span, std_log)
+        keys = {c.args[0] for c in span.set_attribute.call_args_list if c.args}
+        self.assertNotIn("gen_ai.usage.cache_creation.input_tokens", keys)
+        self.assertNotIn("gen_ai.usage.cache_read.input_tokens", keys)
+
+    def test_opt_in_emits_consolidated_inference_details_event(self):
+        from opentelemetry import _logs
+        from opentelemetry._logs._internal import ProxyLoggerProvider
+
+        log_exporter = InMemoryLogExporter()
+        # Make _init_logs see a non-SDK global (the proxy default) so it
+        # falls into the create_new branch and consults _get_log_exporter,
+        # which we patch to return our in-memory exporter.
+        with (
+            patch.dict(
+                os.environ,
+                {"OTEL_SEMCONV_STABILITY_OPT_IN": "gen_ai_latest_experimental"},
+            ),
+            patch.object(
+                _logs, "get_logger_provider", return_value=ProxyLoggerProvider()
+            ),
+            patch.object(_logs, "set_logger_provider"),
+            patch.object(OpenTelemetry, "_get_log_exporter", return_value=log_exporter),
+        ):
+            h = OpenTelemetry(
+                config=OpenTelemetryConfig(exporter="console", enable_events=True)
+            )
+        h.message_logging = True
+
+        kwargs = {
+            "model": "gpt-4",
+            "call_type": "acompletion",
+            "messages": [{"role": "user", "content": "hi"}],
+            "litellm_params": {"custom_llm_provider": "openai"},
+        }
+        response_obj = {
+            "choices": [
+                {
+                    "message": {"role": "assistant", "content": "hello"},
+                    "finish_reason": "stop",
+                }
+            ]
+        }
+        span = h.tracer.start_span("test")
+        h._emit_semantic_logs(kwargs, response_obj, span)
+        span.end()
+        h._logger_provider.force_flush(2000)
+
+        records = [r.log_record for r in log_exporter.get_finished_logs()]
+        # Exactly ONE inference details event, not the legacy per-message/choice pair.
+        self.assertEqual(len(records), 1)
+        attrs = dict(records[0].attributes or {})
+        self.assertEqual(
+            attrs["event_name"], "gen_ai.client.inference.operation.details"
+        )
+        self.assertEqual(attrs["gen_ai.provider.name"], "openai")
+        self.assertEqual(attrs["gen_ai.operation.name"], "chat")
+        self.assertIn("gen_ai.input.messages", attrs)
+        self.assertIn("gen_ai.output.messages", attrs)
+
+    def test_opt_in_inference_details_respects_content_kill_switch(self):
+        from opentelemetry import _logs
+        from opentelemetry._logs._internal import ProxyLoggerProvider
+
+        log_exporter = InMemoryLogExporter()
+        with (
+            patch.dict(
+                os.environ,
+                {"OTEL_SEMCONV_STABILITY_OPT_IN": "gen_ai_latest_experimental"},
+            ),
+            patch("litellm.turn_off_message_logging", True),
+            patch.object(
+                _logs, "get_logger_provider", return_value=ProxyLoggerProvider()
+            ),
+            patch.object(_logs, "set_logger_provider"),
+            patch.object(OpenTelemetry, "_get_log_exporter", return_value=log_exporter),
+        ):
+            h = OpenTelemetry(
+                config=OpenTelemetryConfig(exporter="console", enable_events=True)
+            )
+            h.message_logging = True
+
+            kwargs = {
+                "model": "gpt-4",
+                "call_type": "acompletion",
+                "messages": [{"role": "user", "content": "private prompt"}],
+                "litellm_params": {"custom_llm_provider": "openai"},
+            }
+            response_obj = {
+                "choices": [
+                    {
+                        "message": {
+                            "role": "assistant",
+                            "content": "private completion",
+                        },
+                        "finish_reason": "stop",
+                    }
+                ]
+            }
+            span = h.tracer.start_span("test")
+            h._emit_semantic_logs(kwargs, response_obj, span)
+            span.end()
+            h._logger_provider.force_flush(2000)
+
+        records = [r.log_record for r in log_exporter.get_finished_logs()]
+        self.assertEqual(len(records), 1)
+        attrs = dict(records[0].attributes or {})
+        self.assertNotIn("gen_ai.input.messages", attrs)
+        self.assertNotIn("gen_ai.output.messages", attrs)
+
+
 class TestOpenTelemetry(unittest.TestCase):
     POLL_INTERVAL = 0.05
     POLL_TIMEOUT = 2.0

_{You can send follow-ups to the cloud agent here.}

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

[veria-ai]

PR overview

OTEL GenAI semantic convention opt-in

This PR adds an opt-in path for the latest experimental GenAI semantic conventions and adjusts span/event attributes behind that configuration gate. I checked the changed telemetry paths, including prompt/completion capture controls, event emission, and span attribute handling; the existing content kill switch and capture modes remain enforced.

Security review

• No new security issues were flagged in the latest review.
• No review issues remain open on this pull request.

Risk: 2/10

[harish-berri]

can we define this mapping object once. this creates repeated objects, can be a class or module level variable

[yassin-berriai]

done

[harish-berri]

what if n == 0, is this strictly a n > 1 condition?

[yassin-berriai]

good catch, updated to n>1

[harish-berri]

lets create this mapping as a class or module level variable.

[yassin-berriai]

done

[harish-berri]

this can be if, elif, else and can we tack these onto a class as static methods for better organisation

[yassin-berriai]

changed to static method + match statement

[harish-berri]

can we first make a set out of the comma seprated OTEL envs and then do a O(1) lookup, set lookups are more efficient this way. If it isnt O(1) under the hood, it has be O(logN), just a good precedent to follow. I dont see this affect performance drastically just a precedent

[yassin-berriai]

yes, this was done

[ceng-p]

There's already a reference to feature in the docs or is that something else? https://docs.litellm.ai/docs/observability/opentelemetry_integration#opt-in-to-latest-genai-semantic-conventions