feat(otel): OTel-standard attributes on the proxy SERVER span (status code, route/path, preprocessing latency)

[ryan-crabbe-berri]

Summary

Adds the three OTel-standard attributes the FIL telemetry ask needs, all on the proxy SERVER span (Received Proxy Server Request) — the logging handlers write a child span, so each is set where the SERVER span is in hand (auth path / post-call hooks). Squash-and-merge.

• http.response.status_code (int) — on failures; legacy error.code kept
• http.route (route template) + url.path (literal path)
• litellm.preprocessing.duration_ms — proxy-receive → first provider handoff (excludes retries)

Screenshots

error curl

success curl

error trace

success trace

Test plan

• Automated: test_opentelemetry.py, test_auth_utils.py, test_litellm_logging.py — 447 passed, no regression. Lint (Black/Ruff/MyPy) clean.
• Manual: console-exporter run; all three attributes land on one SERVER span for both success and failure.

Resolves LIT-3086

[codecov]

Codecov Report

❌ Patch coverage is 89.70588% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/integrations/opentelemetry.py	90.90%	4 Missing ⚠️
litellm/proxy/auth/user_api_key_auth.py	40.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

Adds three OTel-standard attributes to the proxy SERVER span (Received Proxy Server Request): http.response.status_code (int) on failures, http.route + url.path stamped in the auth path, and litellm.preprocessing.duration_ms (proxy-receive → first provider handoff, retries excluded) on both success and failure paths.

• Error attributes (http.response.status_code, error.type, legacy error.code) are now set directly on the SERVER span via async_post_call_failure_hook, which was previously only marking span status without structured attributes. The http.response.status_code coerces the string error_code to int and silently omits it for non-numeric codes.
• Route attributes are set immediately after the SERVER span is created in the auth builder — the only point where both the span and the full Request object are available together.
• Preprocessing duration is anchored by a set-once first_api_call_start_time (written on the first pre_call only, not on retries) and a litellm_received_at datetime propagated through request state → internal metadata → failure-path top-level key, with careful guard rails to avoid injecting datetimes into user-facing metadata.

Confidence Score: 5/5

Additive-only changes to the OTel layer; all new code is guarded with None checks and broad exception handlers so a missing span, missing timestamp, or non-numeric error code degrades gracefully to a no-op rather than surfacing an error.

The three new attributes are set on spans that already exist, the timing anchors are propagated through channels that already carry similar internal metadata (headers, parent_otel_span), and all edge cases (pre-auth failure, missing logging obj, clock skew, non-numeric error code, None span) have explicit tests. No auth logic, routing logic, or DB access is modified.

No files require special attention. The most non-trivial logic is in set_preprocessing_duration_attribute and the lift-before-pop in proxy/utils.py, both of which are directly covered by the new tests.

Important Files Changed

Filename	Overview
litellm/integrations/opentelemetry.py	Adds four module-level attribute-name constants, exposes http.response.status_code (as int) in _record_exception_on_span, stamps error attrs + preprocessing duration on the SERVER span in async_post_call_failure_hook, adds the same duration in async_post_call_success_hook, and introduces two new well-guarded helpers (set_proxy_request_route_attributes, set_preprocessing_duration_attribute).
litellm/litellm_core_utils/litellm_logging.py	Adds set-once first_api_call_start_time to model_call_details in pre_call(); deliberately does not touch litellm_params["metadata"] to avoid echoing a datetime into provider request bodies or batch objects.
litellm/proxy/auth/user_api_key_auth.py	Captures the true proxy-receive instant into request.state immediately at the top of _user_api_key_auth_builder, then calls set_proxy_request_route_attributes on the freshly-created SERVER span inside the existing open_telemetry_logger guard.
litellm/proxy/litellm_pre_call_utils.py	Propagates litellm_received_at (datetime or None) from request.state into the internal metadata dict via the same channel as endpoint/headers, making it accessible to the OTel layer for preprocessing latency.
litellm/proxy/utils.py	Lifts first_api_call_start_time off the logging object into the top level of request_data before the non-serialisable logging object is popped, so failure-path OTel callbacks can still compute preprocessing latency.

_{Reviews (3): Last reviewed commit: "Merge remote-tracking branch 'origin/lit..." | Re-trigger Greptile}

[ryan-crabbe-berri]

@greptileai re review

[cursor]

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

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

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

[cursor]

Preprocessing duration lost on thread/assistant failure path

Low Severity

For thread/assistant endpoints, first_api_call_start_time is written to a copy of litellm_params["metadata"] instead of the original request_data["litellm_metadata"]. This prevents set_preprocessing_duration_attribute from finding the start time on the failure path, causing the preprocessing duration to be omitted.

Additional Locations (1)

• litellm/integrations/opentelemetry.py#L2995-L3005

 

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

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[ryan-crabbe-berri]

@greptile re review