diff --git a/litellm/litellm_core_utils/get_litellm_params.py b/litellm/litellm_core_utils/get_litellm_params.py index 49fc9abc525..be18197de9c 100644 --- a/litellm/litellm_core_utils/get_litellm_params.py +++ b/litellm/litellm_core_utils/get_litellm_params.py @@ -134,7 +134,7 @@ def get_litellm_params( # Derive litellm_session_id / litellm_trace_id from metadata when not provided (call chaining) _meta: Final = resolved_metadata or {} if litellm_session_id is None: - litellm_session_id = _meta.get("session_id") or _meta.get("trace_id") + litellm_session_id = _meta.get("session_id") if litellm_trace_id is None: litellm_trace_id = _meta.get("trace_id") or _meta.get("session_id") diff --git a/litellm/proxy/spend_tracking/spend_tracking_utils.py b/litellm/proxy/spend_tracking/spend_tracking_utils.py index 5a3a3f6c2f4..9f1eddcd129 100644 --- a/litellm/proxy/spend_tracking/spend_tracking_utils.py +++ b/litellm/proxy/spend_tracking/spend_tracking_utils.py @@ -743,9 +743,10 @@ def _get_session_id_for_spend_log( omit_when_missing: bool, batch_trace_session_id: str | None = None, ) -> str | None: - """Under `omit` only `metadata.session_id`, the key Langfuse reads, counts as a session; `litellm_session_id` may - be a copied trace id. Batch call types carry a deterministic session derived from the batch id, which outranks - the per-request trace ids because those differ between the create call and the cost poller's row.""" + """Under `omit` only `metadata.session_id`, the key Langfuse reads, counts as a session. Batch call types carry + a deterministic session derived from the batch id, which outranks the per-request trace ids because those differ + between the create call and the cost poller's row. Without an explicit session the legacy fallback groups by + `litellm_trace_id`, but a client-supplied `metadata.trace_id` is a trace correlation id, never a session.""" if omit_when_missing: session_id: Final = metadata.get("session_id") if metadata else None return str(session_id) if session_id else None @@ -754,10 +755,20 @@ def _get_session_id_for_spend_log( if batch_trace_session_id is not None: return batch_trace_session_id - if standard_logging_payload is not None and standard_logging_payload.get("trace_id") is not None: - return str(standard_logging_payload.get("trace_id")) - if kwargs.get("litellm_trace_id") is not None: - return str(kwargs.get("litellm_trace_id")) + litellm_params: Final = kwargs.get("litellm_params") + explicit_session_id: Final = ( + kwargs.get("litellm_session_id") + or (litellm_params.get("litellm_session_id") if isinstance(litellm_params, Mapping) else None) + or (metadata.get("session_id") if metadata else None) + ) + if explicit_session_id: + return str(explicit_session_id) + metadata_trace_id: Final = metadata.get("trace_id") if metadata else None + trace_id: Final = ( + standard_logging_payload.get("trace_id") if standard_logging_payload is not None else None + ) or kwargs.get("litellm_trace_id") + if trace_id is not None and (metadata_trace_id is None or str(trace_id) != str(metadata_trace_id)): + return str(trace_id) return str(uuid.uuid4()) diff --git a/tests/test_litellm/litellm_core_utils/test_get_litellm_params.py b/tests/test_litellm/litellm_core_utils/test_get_litellm_params.py index f026ff57719..ee030675f5b 100644 --- a/tests/test_litellm/litellm_core_utils/test_get_litellm_params.py +++ b/tests/test_litellm/litellm_core_utils/test_get_litellm_params.py @@ -197,6 +197,11 @@ class TestMetadataFallsBackToLitellmMetadata: assert result["litellm_session_id"] == "session-1" assert result["litellm_trace_id"] == "trace-1" + def test_metadata_trace_id_alone_does_not_become_the_session_id(self): + result = get_litellm_params(metadata={"trace_id": "trace-1"}) + assert result["litellm_trace_id"] == "trace-1" + assert result["litellm_session_id"] is None + def test_explicit_session_and_trace_id_are_not_overridden(self): result = get_litellm_params( litellm_session_id="explicit-session", diff --git a/tests/test_litellm/proxy/spend_tracking/test_spend_tracking_utils.py b/tests/test_litellm/proxy/spend_tracking/test_spend_tracking_utils.py index f2273924b30..b57e51639b1 100644 --- a/tests/test_litellm/proxy/spend_tracking/test_spend_tracking_utils.py +++ b/tests/test_litellm/proxy/spend_tracking/test_spend_tracking_utils.py @@ -164,9 +164,9 @@ _TRACE_ONLY_STANDARD_LOGGING: Final = cast( def _trace_only_session_id(omit_when_missing: bool) -> str | None: - """get_litellm_params copies metadata.trace_id into litellm_session_id, so every field echoes the trace id.""" + """get_litellm_params copies metadata.trace_id into litellm_trace_id, so the payload trace id echoes it.""" return _get_session_id_for_spend_log( - kwargs={"litellm_trace_id": "trace-abc", "litellm_session_id": "trace-abc"}, + kwargs={"litellm_trace_id": "trace-abc", "litellm_params": {"litellm_trace_id": "trace-abc"}}, metadata={"trace_id": "trace-abc"}, standard_logging_payload=_TRACE_ONLY_STANDARD_LOGGING, omit_when_missing=omit_when_missing, @@ -195,11 +195,35 @@ def test_omit_records_metadata_session_id(): def test_legacy_policy_keeps_trace_id_fallback(): - assert _trace_only_session_id(omit_when_missing=False) == "trace-abc" generated: Final = _get_session_id_for_spend_log( kwargs={}, metadata=None, standard_logging_payload=None, omit_when_missing=False ) assert len(str(generated)) == 36 + playground_session: Final = _get_session_id_for_spend_log( + kwargs={"litellm_trace_id": "trace-abc"}, + metadata={}, + standard_logging_payload=_TRACE_ONLY_STANDARD_LOGGING, + omit_when_missing=False, + ) + assert playground_session == "trace-abc" + + +def test_legacy_policy_never_records_client_metadata_trace_id_as_the_session(): + """A client sending only `metadata.trace_id` is correlating a trace, not opening a session; the logs UI must + not show that value under Session ID.""" + session_id: Final = _trace_only_session_id(omit_when_missing=False) + assert session_id != "trace-abc" + assert len(str(session_id)) == 36 + + +def test_legacy_policy_prefers_explicit_session_over_metadata_trace_id(): + session_id: Final = _get_session_id_for_spend_log( + kwargs={"litellm_trace_id": "trace-abc", "litellm_params": {"litellm_session_id": "sess-1"}}, + metadata={"trace_id": "trace-abc"}, + standard_logging_payload=_TRACE_ONLY_STANDARD_LOGGING, + omit_when_missing=False, + ) + assert session_id == "sess-1" def test_batch_lifecycle_rows_derive_the_same_session_from_the_batch_id():