diff --git a/litellm/integrations/otel/langfuse_logger.py b/litellm/integrations/otel/langfuse_logger.py index 177bba0c1e1..d029b153c52 100644 --- a/litellm/integrations/otel/langfuse_logger.py +++ b/litellm/integrations/otel/langfuse_logger.py @@ -8,8 +8,8 @@ from litellm.integrations.otel.mappers.langfuse import ( LANGFUSE_OBSERVATION_OUTPUT, LangfuseMapper, ) -from litellm.integrations.otel.model.metadata import caller_trace_controls from litellm.integrations.otel.model.request_io import request_input, response_output, stream_output +from litellm.integrations.otel.model.trace_controls import caller_trace_controls from litellm.integrations.otel.plumbing.context import request_root_span if TYPE_CHECKING: diff --git a/litellm/integrations/otel/mappers/langfuse.py b/litellm/integrations/otel/mappers/langfuse.py index 11a199966b9..8651cd15945 100644 --- a/litellm/integrations/otel/mappers/langfuse.py +++ b/litellm/integrations/otel/mappers/langfuse.py @@ -22,12 +22,12 @@ from litellm.integrations.otel.mappers.utils import ( output_messages, serialize_messages, ) -from litellm.integrations.otel.model.metadata import TraceControls from litellm.integrations.otel.model.payloads import ( LLMCallSpanData, LLMRequestParams, LLMUsage, ) +from litellm.integrations.otel.model.trace_controls import TraceControls LANGFUSE_OBSERVATION_INPUT: Final = "langfuse.observation.input" LANGFUSE_OBSERVATION_OUTPUT: Final = "langfuse.observation.output" diff --git a/litellm/integrations/otel/model/metadata.py b/litellm/integrations/otel/model/metadata.py index 8a5383e981a..2fdbc826803 100644 --- a/litellm/integrations/otel/model/metadata.py +++ b/litellm/integrations/otel/model/metadata.py @@ -36,33 +36,19 @@ model. They coincide on the SDK path, which is correct. from __future__ import annotations -from collections.abc import Iterator, Mapping, Sequence +from collections.abc import Iterator, Mapping from dataclasses import dataclass, field from types import MappingProxyType from typing import TYPE_CHECKING, Any, Final, cast from litellm.constants import LITELLM_LOGGING_NO_UPSTREAM_LLM_CALL from litellm.integrations.otel.model.semconv import resolve_operation -from litellm.integrations.otel.model.utils import as_str, to_seconds +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 if TYPE_CHECKING: from litellm.types.utils import StandardLoggingPayload -LANGFUSE_HEADER_PREFIX: Final = "langfuse_" - - -@dataclass(frozen=True, slots=True) -class TraceControls: - """The caller's trace-level Langfuse controls: ``metadata.trace_name`` / ``trace_user_id`` / ``session_id`` / - ``tags`` on the request (SDK or proxy body), with the proxy's ``langfuse_`` headers winning over the - body for the scalar ones. Mutation controls (``trace_id``, ``existing_trace_id``, ``update_trace_keys``) are - deliberately not carried.""" - - name: str | None = None - user_id: str | None = None - session_id: str | None = None - tags: tuple[str, ...] = () - @dataclass(frozen=True) class RequestIdentity: @@ -251,38 +237,6 @@ class LLMCallEvent: ) -def caller_trace_controls(kwargs: Mapping[str, object]) -> TraceControls: - request: Final = _as_str_mapping(kwargs.get("litellm_params")) - if request is None: - return TraceControls() - proxy_request: Final = _as_str_mapping(request.get("proxy_server_request")) - headers: Final = (_as_str_mapping(proxy_request.get("headers")) if proxy_request is not None else None) or {} - bodies: Final = tuple( - metadata - for key in ("metadata", "litellm_metadata") - if (metadata := _as_str_mapping(request.get(key))) is not None - ) - - def scalar(control: str) -> str | None: - from_header: Final = as_str(headers.get(f"{LANGFUSE_HEADER_PREFIX}{control}")) - if from_header: - return from_header - return next((value for body in bodies if (value := as_str(body.get(control)))), None) - - return TraceControls( - name=scalar("trace_name"), - user_id=scalar("trace_user_id"), - session_id=scalar("session_id"), - tags=next((tags for body in bodies if (tags := _str_items(body.get("tags")))), ()), - ) - - -def _str_items(value: object) -> tuple[str, ...]: - if not isinstance(value, (list, tuple)): - return () - return tuple(item for item in cast("Sequence[object]", value) if isinstance(item, str) and item) - - 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 @@ -317,15 +271,8 @@ def auth_metadata(payload: StandardLoggingPayload | None, kwargs: Mapping[str, o ) -def _as_str_mapping(value: object) -> Mapping[str, object] | None: - """A read-only view of ``value`` when it is a mapping, else ``None``.""" - if not isinstance(value, Mapping): - return None - return cast("Mapping[str, object]", value) # cast-ok: isinstance-guarded, JSON metadata has str keys - - def _string_entries(value: object) -> Mapping[str, str] | None: - entries: Final = _as_str_mapping(value) + entries: Final = as_str_mapping(value) if entries is None: return None typed: Final = MappingProxyType({key: item for key, item in entries.items() if isinstance(item, str)}) @@ -341,18 +288,18 @@ def _metadata_dicts( litellm copies it onto ``metadata``, but both are yielded so a route that populates only one is still covered. """ - payload_view: Final = _as_str_mapping(payload) + payload_view: Final = as_str_mapping(payload) if payload_view is not None: - payload_metadata: Final = _as_str_mapping(payload_view.get("metadata")) + payload_metadata: Final = as_str_mapping(payload_view.get("metadata")) if payload_metadata is not None: yield payload_metadata - params: Final = _as_str_mapping(kwargs.get("litellm_params")) + params: Final = as_str_mapping(kwargs.get("litellm_params")) if params is None: return yield from ( metadata for key in ("metadata", "litellm_metadata") - if (metadata := _as_str_mapping(params.get(key))) is not None + if (metadata := as_str_mapping(params.get(key))) is not None ) diff --git a/litellm/integrations/otel/model/payloads.py b/litellm/integrations/otel/model/payloads.py index 068c3a38e21..33da1549fd5 100644 --- a/litellm/integrations/otel/model/payloads.py +++ b/litellm/integrations/otel/model/payloads.py @@ -10,11 +10,7 @@ from types import MappingProxyType from typing import TYPE_CHECKING, ClassVar, Final, cast from urllib.parse import urlsplit -from litellm.integrations.otel.model.metadata import ( - RequestContext, - RequestIdentity, - TraceControls, -) +from litellm.integrations.otel.model.metadata import RequestContext, RequestIdentity from litellm.integrations.otel.model.semconv import ( GenAIOperation, GenAIOutputType, @@ -23,6 +19,7 @@ from litellm.integrations.otel.model.semconv import ( resolve_output_type, resolve_provider, ) +from litellm.integrations.otel.model.trace_controls import TraceControls from litellm.integrations.otel.model.utils import ( as_bool, as_float, diff --git a/litellm/integrations/otel/model/trace_controls.py b/litellm/integrations/otel/model/trace_controls.py new file mode 100644 index 00000000000..884c51a420b --- /dev/null +++ b/litellm/integrations/otel/model/trace_controls.py @@ -0,0 +1,61 @@ +"""The caller's Langfuse trace controls, parsed from the live callback kwargs.""" + +from __future__ import annotations + +from collections.abc import Mapping +from dataclasses import dataclass +from typing import Final + +from pydantic import TypeAdapter, ValidationError + +from litellm.integrations.otel.model.utils import as_str, as_str_mapping + +LANGFUSE_HEADER_PREFIX: Final = "langfuse_" +_ITEMS: Final = TypeAdapter(tuple[object, ...]) + + +@dataclass(frozen=True, slots=True) +class TraceControls: + """The caller's trace-level Langfuse controls: ``metadata.trace_name`` / ``trace_user_id`` / ``session_id`` / + ``tags`` on the request (SDK or proxy body), with the proxy's ``langfuse_`` headers winning over the + body for the scalar ones. Mutation controls (``trace_id``, ``existing_trace_id``, ``update_trace_keys``) are + deliberately not carried.""" + + name: str | None = None + user_id: str | None = None + session_id: str | None = None + tags: tuple[str, ...] = () + + +def caller_trace_controls(kwargs: Mapping[str, object]) -> TraceControls: + request: Final = as_str_mapping(kwargs.get("litellm_params")) + if request is None: + return TraceControls() + proxy_request: Final = as_str_mapping(request.get("proxy_server_request")) + headers: Final = (as_str_mapping(proxy_request.get("headers")) if proxy_request is not None else None) or {} + bodies: Final = tuple( + metadata + for key in ("metadata", "litellm_metadata") + if (metadata := as_str_mapping(request.get(key))) is not None + ) + + def scalar(control: str) -> str | None: + from_header: Final = as_str(headers.get(f"{LANGFUSE_HEADER_PREFIX}{control}")) + if from_header: + return from_header + return next((value for body in bodies if (value := as_str(body.get(control)))), None) + + return TraceControls( + name=scalar("trace_name"), + user_id=scalar("trace_user_id"), + session_id=scalar("session_id"), + tags=next((tags for body in bodies if (tags := _str_items(body.get("tags")))), ()), + ) + + +def _str_items(value: object) -> tuple[str, ...]: + try: + items: Final = _ITEMS.validate_python(value) + except ValidationError: + return () + return tuple(item for item in items if isinstance(item, str) and item) diff --git a/litellm/integrations/otel/model/utils.py b/litellm/integrations/otel/model/utils.py index fb35e9abf51..a3276f30078 100644 --- a/litellm/integrations/otel/model/utils.py +++ b/litellm/integrations/otel/model/utils.py @@ -8,7 +8,13 @@ parsing lives in :mod:`litellm.integrations.otel.plumbing.providers` instead, because it delegates to the OTel SDK's own W3C Baggage parser. """ +from collections.abc import Mapping from datetime import datetime +from typing import Final + +from pydantic import TypeAdapter, ValidationError + +_STR_MAPPING: Final = TypeAdapter(Mapping[str, object]) def as_str(value: object) -> str | None: @@ -55,6 +61,13 @@ def as_bool(value: object) -> bool | None: return bool(value) +def as_str_mapping(value: object) -> Mapping[str, object] | None: + try: + return _STR_MAPPING.validate_python(value) + except ValidationError: + return None + + def as_str_tuple(value: object) -> tuple[str, ...] | None: if value is None: return None diff --git a/tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py b/tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py index d42077d6e6a..c5c77a12a62 100644 --- a/tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py +++ b/tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py @@ -28,7 +28,8 @@ from litellm.integrations.otel import ( ) from litellm.integrations.otel.mappers.genai import GenAIMapper from litellm.integrations.otel.model import spans as spans_mod -from litellm.integrations.otel.model.metadata import LLMCallEvent, TraceControls, caller_trace_controls +from litellm.integrations.otel.model.metadata import LLMCallEvent +from litellm.integrations.otel.model.trace_controls import TraceControls, caller_trace_controls from litellm.integrations.otel.model.payloads import ( LLMCallSpanData, RequestIdentity, diff --git a/tests/test_litellm/integrations/otel/test_otel_v2_vendor_mappers.py b/tests/test_litellm/integrations/otel/test_otel_v2_vendor_mappers.py index 81c9c2cdc9a..bd83357305e 100644 --- a/tests/test_litellm/integrations/otel/test_otel_v2_vendor_mappers.py +++ b/tests/test_litellm/integrations/otel/test_otel_v2_vendor_mappers.py @@ -18,7 +18,7 @@ from litellm.integrations.otel.mappers import ( WeaveMapper, resolve_mappers, ) -from litellm.integrations.otel.model.metadata import TraceControls +from litellm.integrations.otel.model.trace_controls import TraceControls from litellm.integrations.otel.model.payloads import ( LLMCallSpanData, LLMRequestParams,