feat(otel): emit gen_ai.conversation.id from the caller's session id on v2 LLM spans

litellm/integrations/otel/logger.py

@@ -561,6 +561,7 @@ def _finish_carrier(
             time_to_first_chunk_seconds=call.time_to_first_chunk_seconds,
             request_route=request_root_http_route(),
             trace=call.trace,
+            session_id=call.session_id,
         )
         end_time_ns: Final = to_ns(end_time)
         if carrier is not None and carrier.span is not None:

litellm/integrations/otel/mappers/genai.py

@@ -43,6 +43,7 @@ class GenAIMapper:
         GenAI.OPERATION_NAME: lambda d: d.operation.value,
         GenAI.PROVIDER_NAME: lambda d: d.provider or None,
         GenAI.OUTPUT_TYPE: lambda d: d.output_type.value if d.output_type else None,
+        GenAI.CONVERSATION_ID: lambda d: d.session_id,
         GenAI.REQUEST_MODEL: lambda d: d.request_model or None,
         GenAI.REQUEST_TEMPERATURE: lambda d: d.request_params.temperature,
         GenAI.REQUEST_TOP_P: lambda d: d.request_params.top_p,

litellm/integrations/otel/model/metadata.py

@@ -41,7 +41,7 @@
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Final, cast
 
-from litellm.constants import LITELLM_LOGGING_NO_UPSTREAM_LLM_CALL
+from litellm.constants import LITELLM_LOGGING_NO_UPSTREAM_LLM_CALL, SESSION_ID_GENERATED_METADATA_KEY
 from litellm.integrations.otel.model.semconv import resolve_operation
 from litellm.integrations.otel.model.trace_controls import TraceControls, caller_trace_controls
 from litellm.integrations.otel.model.utils import as_str, as_str_mapping, to_seconds
@@ -226,13 +226,15 @@ class LLMCallEvent:
     provisional_span_name: str
     time_to_first_chunk_seconds: float | None
     trace: TraceControls
+    session_id: str | None
 
     @classmethod
     def from_dict(cls, kwargs: Mapping[str, object]) -> LLMCallEvent:
         raw_payload: Final = kwargs.get("standard_logging_object")
         payload: Final = cast("StandardLoggingPayload", raw_payload) if raw_payload else None
         operation: Final = resolve_operation(as_str(kwargs.get("call_type")))
         model: Final = as_str(kwargs.get("model")) or ""
+        trace: Final = caller_trace_controls(kwargs)
         return cls(
             call_id=_call_id(payload, kwargs),
             payload=payload,
@@ -242,10 +244,40 @@ def from_dict(cls, kwargs: Mapping[str, object]) -> LLMCallEvent:
             upstream_started=kwargs.get("api_call_start_time") is not None,
             provisional_span_name=f"{operation.value} {model}".strip(),
             time_to_first_chunk_seconds=time_to_first_chunk_seconds(kwargs),
-            trace=caller_trace_controls(kwargs),
+            trace=trace,
+            session_id=caller_session_id(kwargs, trace),
         )
 
 
+def caller_session_id(kwargs: Mapping[str, object], trace: TraceControls) -> str | None:
+    """The conversation id the caller sent (``litellm_session_id``, else the
+    ``session_id`` trace control); ``None`` when the request carried none.
+
+    ``get_litellm_params`` back-fills ``litellm_session_id`` from ``metadata.trace_id``
+    (which the proxy stamps with the OTel trace id) and ``missing_session_id: generate``
+    mints one into the body; neither is a caller conversation, so both are ignored,
+    while a ``langfuse_session_id`` header still counts under the generate policy.
+    ``StandardLoggingPayload.session_id`` is never read: the payload drops the
+    generated marker, so a replayed minted id would pass for a caller's."""
+    params: Final[Mapping[str, object]] = as_str_mapping(kwargs.get("litellm_params")) or MappingProxyType({})
+    bodies: Final = tuple(
+        metadata
+        for key in ("metadata", "litellm_metadata")
+        if (metadata := as_str_mapping(params.get(key))) is not None
+    )
+    from_body: Final = tuple(session for body in bodies if (session := as_str(body.get("session_id"))))
+    minted: Final = frozenset(
+        session
+        for body in bodies
+        if body.get(SESSION_ID_GENERATED_METADATA_KEY) and (session := as_str(body.get("session_id")))
+    )
+    if minted:
+        return next((session for session in (trace.session_id, *from_body) if session and session not in minted), None)
+    explicit: Final = as_str(params.get("litellm_session_id"))
+    echoes_trace_id: Final = explicit is not None and any(as_str(body.get("trace_id")) == explicit for body in bodies)
+    return (None if echoes_trace_id else explicit) or trace.session_id or None
+
+
 def time_to_first_chunk_seconds(kwargs: Mapping[str, Any]) -> float | None:
     """Seconds from the upstream request being issued (``api_call_start_time``)
     to the first streamed chunk (``completion_start_time``); ``None`` for

litellm/integrations/otel/model/payloads.py

@@ -407,6 +407,7 @@ class LLMCallSpanData:
     call_type: str | None = None
     request_route: str | None = None
     trace: TraceControls = field(default_factory=TraceControls)
+    session_id: str | None = None
     embedding_output: EmbeddingOutput | None = None
 
     @classmethod
@@ -417,6 +418,7 @@ def from_standard_logging_payload(
         time_to_first_chunk_seconds: float | None = None,
         request_route: str | None = None,
         trace: TraceControls | None = None,
+        session_id: str | None = None,
     ) -> LLMCallSpanData:
         params: Final = cast(Mapping[str, object], payload.get("model_parameters") or {})
         # The single parse of the request's metadata — the request-vs-provider
@@ -463,6 +465,7 @@ def from_standard_logging_payload(
             call_type=call_type or None,
             request_route=request_route or context.identity.request_route,
             trace=trace or TraceControls(),
+            session_id=session_id or None,
             embedding_output=embedding_output if capture_content else None,
         )
 

tests/integration/contracts.json

@@ -2020,6 +2020,75 @@
     "tests/integration/observability/test_callback_delivery.py::test_response_survives_raising_success_deployment_hook[videos]": [
       "other.observability.callbacks.raising_success_deployment_hook_keeps_response"
     ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_chat_completion_sdk_body_litellm_session_id_lands_as_conversation_id": [
+      "other.observability.otel.conversation_id_from_body_session_id_chat_sdk"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_chat_stream_async_sdk_x_litellm_session_id_header_lands_as_conversation_id": [
+      "other.observability.otel.conversation_id_from_header_chat_stream_async_sdk"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_messages_sdk_x_litellm_session_id_header_lands_as_conversation_id": [
+      "other.observability.otel.conversation_id_from_header_messages_sdk"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_messages_stream_async_sdk_langfuse_session_id_header_lands_as_conversation_id": [
+      "other.observability.otel.conversation_id_from_langfuse_header_messages_stream_async_sdk"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_responses_sdk_x_litellm_session_id_header_lands_as_conversation_id": [
+      "other.observability.otel.conversation_id_from_header_responses_sdk"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_responses_stream_raw_metadata_session_id_lands_as_conversation_id": [
+      "other.observability.otel.conversation_id_from_metadata_responses_stream_raw"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_chat_raw_metadata_session_id_lands_as_conversation_id": [
+      "other.observability.otel.conversation_id_from_metadata_chat_raw"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_integer_and_list_litellm_session_id_match_the_spend_row_or_are_dropped_together": [
+      "other.observability.otel.conversation_id_non_string_session_ids_match_spend_row"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_empty_string_litellm_session_id_leaves_the_span_without_a_conversation_id": [
+      "other.observability.otel.conversation_id_empty_string_session_id_is_omitted"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_five_kilobyte_session_header_round_trips_to_the_span_and_the_spend_row": [
+      "other.observability.otel.conversation_id_five_kilobyte_header_round_trips"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_duplicate_session_header_lands_once_and_unchanged": [
+      "other.observability.otel.conversation_id_duplicate_header_lands_once"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_unauthenticated_request_with_session_header_is_rejected_and_leaves_no_span": [
+      "other.observability.otel.conversation_id_unauthenticated_request_leaves_no_span"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_sink_rejecting_with_403_drops_those_spans_and_later_spans_still_land": [
+      "other.observability.otel.conversation_id_survives_sink_rejection"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_request_without_any_session_input_has_no_conversation_id": [
+      "other.observability.otel.conversation_id_absent_without_caller_session"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_generate_policy_minted_session_id_reaches_the_spend_row_but_not_the_span": [
+      "other.observability.otel.conversation_id_ignores_generated_session_id"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_generate_policy_keeps_the_langfuse_session_header_as_conversation_id": [
+      "other.observability.otel.conversation_id_langfuse_header_wins_over_generated"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_header_body_and_metadata_session_ids_resolve_to_the_same_id_as_the_spend_row": [
+      "other.observability.otel.conversation_id_header_precedence_matches_spend_row"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_three_identical_requests_produce_one_span_each_with_the_same_conversation_id": [
+      "other.observability.otel.conversation_id_repeated_requests_log_once_each"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_metadata_trace_id_alone_fills_the_spend_row_but_not_the_span": [
+      "other.observability.otel.conversation_id_ignores_trace_id_backfill"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_sink_outage_during_a_mixed_burst_lands_every_response_exactly_once_after_recovery": [
+      "other.observability.otel.conversation_id_sink_outage_recovers_exactly_once"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_slow_sink_during_a_burst_lands_every_response_exactly_once": [
+      "other.observability.otel.conversation_id_slow_sink_no_duplicates"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_killing_one_of_two_workers_mid_burst_keeps_serving_and_never_duplicates_a_span": [
+      "other.observability.otel.conversation_id_survives_worker_kill"
+    ],
+    "tests/integration/observability/test_otel_conversation_id.py::test_terminating_the_proxy_right_after_a_burst_flushes_every_span_before_exit": [
+      "other.observability.otel.conversation_id_flushes_on_shutdown"
+    ],
     "tests/integration/management/test_user_updates_wedged_coordination_redis.py::test_user_budget_updates_return_promptly_while_coordination_redis_is_wedged": [
       "mgmt.user.update.budget_change_returns_promptly_with_wedged_coordination_redis",
       "mgmt.user.bulk_update.budget_change_returns_promptly_with_wedged_coordination_redis",