Skip to content
23 changes: 23 additions & 0 deletions litellm/integrations/opentelemetry.py
Original file line number Diff line number Diff line change
Expand Up @@ -2962,6 +2962,11 @@ async def async_management_endpoint_success_hook(
management_endpoint_span.set_status(Status(StatusCode.OK))
management_endpoint_span.end(end_time=_end_time_ns)

# The management wrapper has no other hook that closes the SERVER span.
self.set_response_status_code_attribute(parent_otel_span, 200)
parent_otel_span.set_status(Status(StatusCode.OK))
parent_otel_span.end(end_time=_end_time_ns)

async def async_management_endpoint_failure_hook(
self,
logging_payload: ManagementEndpointLoggingPayload,
Expand Down Expand Up @@ -3012,6 +3017,24 @@ async def async_management_endpoint_failure_hook(
management_endpoint_span.set_status(Status(StatusCode.ERROR))
management_endpoint_span.end(end_time=_end_time_ns)

# The management wrapper has no other hook that closes the SERVER span.
from litellm.litellm_core_utils.litellm_logging import (
StandardLoggingPayloadSetup,
)

error_information = StandardLoggingPayloadSetup.get_error_information(
original_exception=_exception,
)
parent_otel_span.set_status(Status(StatusCode.ERROR))
self._record_exception_on_span(
span=parent_otel_span,
kwargs={
"exception": _exception,
"standard_logging_object": {"error_information": error_information},
},
)
parent_otel_span.end(end_time=_end_time_ns)
Comment thread
ryan-crabbe-berri marked this conversation as resolved.
Resolved

def create_litellm_proxy_request_started_span(
self,
start_time: datetime,
Expand Down
8 changes: 6 additions & 2 deletions litellm/litellm_core_utils/litellm_logging.py
Original file line number Diff line number Diff line change
Expand Up @@ -5143,13 +5143,17 @@ def get_error_information(
) -> StandardLoggingPayloadErrorInformation:
from litellm.constants import MAXIMUM_TRACEBACK_LINES_TO_LOG

# Check for 'code' first (used by ProxyException), then fall back to 'status_code' (used by LiteLLM exceptions)
# Ensure error_code is always a string for Prisma Python JSON field compatibility
# ProxyException uses .code, LiteLLM exceptions use .status_code,
# httpx.HTTPStatusError exposes status only as .response.status_code.
# Stringified for Prisma JSON compatibility.
error_code_attr = getattr(original_exception, "code", None)
if error_code_attr is not None and str(error_code_attr) not in ("", "None"):
error_status: str = str(error_code_attr)
else:
status_code_attr = getattr(original_exception, "status_code", None)
if status_code_attr is None:
response_attr = getattr(original_exception, "response", None)
status_code_attr = getattr(response_attr, "status_code", None)
error_status = str(status_code_attr) if status_code_attr is not None else ""
error_class: str = (
str(original_exception.__class__.__name__) if original_exception else ""
Expand Down
1 change: 1 addition & 0 deletions litellm/proxy/auth/user_api_key_auth.py
Original file line number Diff line number Diff line change
Expand Up @@ -736,6 +736,7 @@ async def _user_api_key_auth_builder( # noqa: PLR0915
url_path=route,
http_route=get_request_route_template(request),
)
request.state.parent_otel_span = parent_otel_span

### USER-DEFINED AUTH FUNCTION ###
if enterprise_custom_auth is not None:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3222,6 +3222,7 @@ async def info_key_fn_v2(
@router.get(
"/key/info", tags=["key management"], dependencies=[Depends(user_api_key_auth)]
)
@management_endpoint_wrapper
async def info_key_fn(
key: Optional[str] = fastapi.Query(
default=None, description="Key in the request parameters"
Expand Down
30 changes: 17 additions & 13 deletions litellm/proxy/management_helpers/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -518,19 +518,23 @@ async def wrapper(*args, **kwargs):
_request_body: dict = await _read_request_body(
request=_http_request
)
logging_payload = ManagementEndpointLoggingPayload(
route=_route,
request_data=_request_body,
response=None,
start_time=start_time,
end_time=end_time,
exception=e,
)

await open_telemetry_logger.async_management_endpoint_failure_hook( # type: ignore
logging_payload=logging_payload,
parent_otel_span=parent_otel_span,
)
else:
_route = func.__name__
_request_body = {}

logging_payload = ManagementEndpointLoggingPayload(
route=_route,
request_data=_request_body,
response=None,
start_time=start_time,
end_time=end_time,
exception=e,
)

await open_telemetry_logger.async_management_endpoint_failure_hook( # type: ignore
logging_payload=logging_payload,
parent_otel_span=parent_otel_span,
)

raise e

Expand Down
47 changes: 47 additions & 0 deletions litellm/proxy/proxy_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -550,6 +550,7 @@ def generate_feedback_box():
status,
)
from fastapi.encoders import jsonable_encoder
from fastapi.exceptions import RequestValidationError
from fastapi.middleware.cors import CORSMiddleware
from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.openapi.utils import get_openapi
Expand Down Expand Up @@ -1218,6 +1219,52 @@ async def openai_exception_handler(request: Request, exc: ProxyException):
)


def _close_dangling_otel_server_span(request: Request, status_code: int) -> None:
parent_otel_span = getattr(request.state, "parent_otel_span", None)
if parent_otel_span is None:
return
if open_telemetry_logger is None:
return
try:
from opentelemetry.trace import Status, StatusCode

open_telemetry_logger.set_response_status_code_attribute(
parent_otel_span, status_code
)
parent_otel_span.set_status(
Status(StatusCode.ERROR if status_code >= 400 else StatusCode.OK)
)
parent_otel_span.end()
except Exception as e:
verbose_proxy_logger.debug(
"Error closing dangling OTEL SERVER span: %s", str(e)
)
finally:
request.state.parent_otel_span = None


@app.exception_handler(RequestValidationError)
async def otel_request_validation_exception_handler(
request: Request, exc: RequestValidationError
):
_close_dangling_otel_server_span(request, 422)
return JSONResponse(
status_code=422,
content={"detail": jsonable_encoder(exc.errors())},
)


@app.exception_handler(Exception)
async def otel_unhandled_exception_handler(request: Request, exc: Exception):
if isinstance(exc, (ProxyException, HTTPException, RequestValidationError)):
raise exc
_close_dangling_otel_server_span(request, 500)
return JSONResponse(
status_code=500,
content={"error": {"message": str(exc), "type": type(exc).__name__}},
Comment thread
veria-ai[bot] marked this conversation as resolved.
Resolved
)


router = APIRouter()


Expand Down
Empty file.
109 changes: 109 additions & 0 deletions tests/test_litellm/integrations/open_telemetry/_helpers.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
"""
Helpers for the LIT-3193 OTEL HTTP-attribute matrix.

Module split from ``conftest.py`` because pytest auto-discovers fixtures but
forbids ``from .conftest import …`` (no parent package). Fixtures stay in
``conftest.py``; pure helpers (assertions, exception factories, attribute
constants) live here so test modules can ``from ._helpers import …``.
"""

from typing import Any, Optional

from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
InMemorySpanExporter,
)
from opentelemetry.trace import StatusCode

from litellm.integrations.opentelemetry import (
HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE,
HTTP_ROUTE_ATTRIBUTE,
LITELLM_PROXY_REQUEST_SPAN_NAME,
URL_PATH_ATTRIBUTE,
)


def get_server_span(exporter: InMemorySpanExporter):
"""Return the (single) finished SERVER span, or None if it never ended."""
for s in exporter.get_finished_spans():
if s.name == LITELLM_PROXY_REQUEST_SPAN_NAME:
return s
return None


def assert_server_span_attrs(
exporter: InMemorySpanExporter,
*,
expected_status: int,
expected_url_path: str,
expected_http_route: Optional[str] = None,
where: str = "",
) -> None:
"""The four required attributes on the SERVER span must all be set."""
span = get_server_span(exporter)
assert span is not None, (
f"{where}: SERVER span never finished — exporter saw "
f"{[s.name for s in exporter.get_finished_spans()]}"
)

actual_status = span.attributes.get(HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE)
assert actual_status == expected_status, (
f"{where}: {HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE} = "
f"{actual_status!r}, expected {expected_status}"
)
assert isinstance(
actual_status, int
), f"{where}: status code must be int (semconv), got {type(actual_status)}"

actual_url = span.attributes.get(URL_PATH_ATTRIBUTE)
assert actual_url == expected_url_path, (
f"{where}: {URL_PATH_ATTRIBUTE} = {actual_url!r}, "
f"expected {expected_url_path!r}"
)

expected_route = expected_http_route or expected_url_path
actual_route = span.attributes.get(HTTP_ROUTE_ATTRIBUTE)
assert actual_route == expected_route, (
f"{where}: {HTTP_ROUTE_ATTRIBUTE} = {actual_route!r}, "
f"expected {expected_route!r}"
)

duration_ns = (span.end_time or 0) - (span.start_time or 0)
assert duration_ns > 0, f"{where}: duration must be > 0, got {duration_ns}ns"

expected_span_status = StatusCode.ERROR if expected_status >= 400 else StatusCode.OK
actual_span_status = span.status.status_code
assert actual_span_status == expected_span_status, (
f"{where}: span.status = {actual_span_status!r}, "
f"expected {expected_span_status!r}"
)


# ---------------------------------------------------------------------------
# Synthetic exceptions covering the matrix triggers
# ---------------------------------------------------------------------------
class HttpStatusException(Exception):
"""Generic exception with .status_code; mirrors what proxy code reads."""

def __init__(self, status_code: int, message: str = "boom"):
super().__init__(message)
self.status_code = status_code
self.code = status_code


def make_httpx_status_error(status_code: int, body: str = "upstream error"):
"""Real httpx.HTTPStatusError — what providers emit on 4xx/5xx upstream."""
import httpx

request = httpx.Request("POST", "https://upstream.example/v1/x")
response = httpx.Response(
status_code=status_code, content=body.encode("utf-8"), request=request
)
return httpx.HTTPStatusError(
f"HTTP {status_code}", request=request, response=response
)


def make_fastapi_http_exception(status_code: int, detail: Any = "boom"):
from fastapi import HTTPException

return HTTPException(status_code=status_code, detail=detail)
93 changes: 93 additions & 0 deletions tests/test_litellm/integrations/open_telemetry/conftest.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
"""
Shared fixtures for the LIT-3193 OTEL HTTP-attribute matrix.

The matrix needs every error response — across unified inference, passthrough,
and admin endpoints — to carry ``http.response.status_code``, ``url.path``,
``http.route``, and a non-zero duration on the SERVER (root) span. These
fixtures hook a real ``OpenTelemetry`` callback into ``litellm.callbacks`` so
the tests drive the actual handler / wrapper code under test, not the OTEL
emitter in isolation.

See ``LIT-3193_test_matrix.md`` (same directory) for the cell list.
"""

import os
import sys
from datetime import datetime
from typing import Optional, Tuple
from unittest.mock import MagicMock

import pytest
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
InMemorySpanExporter,
)

sys.path.insert(0, os.path.abspath("../../.."))

import litellm
from litellm.integrations.opentelemetry import OpenTelemetry


# ---------------------------------------------------------------------------
# OTEL + exporter
# ---------------------------------------------------------------------------
@pytest.fixture
def otel_with_exporter() -> Tuple[OpenTelemetry, InMemorySpanExporter]:
"""Real OpenTelemetry callback with every span captured in-memory."""
exporter = InMemorySpanExporter()
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(exporter))

otel = OpenTelemetry()
otel.tracer = provider.get_tracer("lit-3193-tests")
otel.message_logging = True
return otel, exporter


@pytest.fixture
def server_span_factory(otel_with_exporter):
"""Factory mirroring user_api_key_auth: SERVER span + url.path + http.route."""
otel, _exporter = otel_with_exporter

def _make(url_path: str, http_route: Optional[str] = None):
span = otel.create_litellm_proxy_request_started_span(
start_time=datetime.now(), headers={}
)
otel.set_proxy_request_route_attributes(
span, url_path=url_path, http_route=http_route or url_path
)
return span

return _make


@pytest.fixture
def user_api_key_dict_factory():
"""UserAPIKeyAuth-shaped mock; the only attr the failure hooks read is
parent_otel_span (plus team_id/team_alias for stamping)."""

def _make(parent_span):
d = MagicMock()
d.parent_otel_span = parent_span
d.team_id = "team-lit-3193"
d.team_alias = "lit-3193-team"
d.request_route = None
return d

return _make


@pytest.fixture
def register_otel_callback(otel_with_exporter, monkeypatch):
"""Make ProxyLogging.post_call_failure_hook iterate our OTEL instance."""
otel, _ = otel_with_exporter
saved = list(litellm.callbacks)
monkeypatch.setattr(litellm, "callbacks", [otel])
yield otel
litellm.callbacks = saved


# Helpers (assertions, exception factories) live in ``_helpers.py`` — pytest
# auto-discovers fixtures here but forbids ``from .conftest import …``.
Loading
Loading