fix(passthrough): emit otel guardrail span when a guardrail blocks

[yassin-berriai]

Relevant issues

With otel_v2 logging on a passthrough endpoint, the guardrail span (execute_guardrail <name>) shows up when a guardrail allows a request but is missing when a guardrail blocks it. On the unified (chat/completions) path the guardrail span is always present, on both allow and block. This makes the passthrough failure path match the unified path.

Linear ticket

Resolves LIT-3510

Root cause

The otel_v2 logger emits guardrail spans from its post-call hooks (async_post_call_success_hook / async_post_call_failure_hook -> _emit_guardrail_spans), which read standard_logging_guardrail_information off the top-level metadata key of the dict handed to the hook (guardrail_entries_from_request_data).

On passthrough, post-call guardrails run against a throwaway hook_data dict built in pass_through_request; its metadata is what _init_kwargs_for_pass_through_endpoint already stripped off _parsed_body. When a guardrail denies with a non ModifyResponseException (HTTPException 400, BlockedPiiEntityError, GuardrailRaisedException, ...), the guardrail records its standard_logging_guardrail_information onto that hook_data dict, then the exception lands in the generic except Exception handler, which forwards a request_payload built from _parsed_body to post_call_failure_hook. That dict no longer carries the guardrail info, so _emit_guardrail_spans finds nothing and returns early; no span. On allow, the otel logger's success hook runs with the same hook_data the guardrail wrote into, so the span is present. The unified path passes the same self.data (metadata intact) to the failure hook, so its span always shows.

The ModifyResponseException branch already forwards e.request_data (the hook_data), so passthrough-mode masks were unaffected; only the deny path was broken.

Changes

In pass_through_request, capture the post-call guardrail hook_data and, in the failure handler, carry its standard_logging_guardrail_information over to the request_data forwarded to post_call_failure_hook (_carry_guardrail_logging_info). The helper copies the entries list (so request_data never shares the source hook_data list) and uses setdefault so it never clobbers entries already present; it is a no-op when no post-call guardrail ran or recorded anything.

Screenshots / Proof of Fix

Live proxy with otel_v2 + console span exporter, a passthrough endpoint guarded by a post-call deny guardrail, pointed at a local mock upstream that echoes the request text into the response so the curl payload controls allow vs block. No external provider keys needed; a pre-call deny never reaches the upstream and a post-call deny needs a response to scan, so a local upstream is the realistic setup here.

config.yaml:

model_list: []
litellm_settings:
  callbacks: ["otel"]
guardrails:
  - guardrail_name: "block-demo"
    litellm_params:
      guardrail: block_guardrail.BlockOnTextGuardrail
      mode: "post_call"
general_settings:
  master_key: sk-1234
  pass_through_endpoints:
    - path: "/mock/echo"
      target: "http://127.0.0.1:9100/echo"
      guardrails: ["block-demo"]

block_guardrail.py (post-call deny on BLOCKME):

from fastapi import HTTPException
from litellm.integrations.custom_guardrail import CustomGuardrail, log_guardrail_information

class BlockOnTextGuardrail(CustomGuardrail):
    def __init__(self, **kwargs):
        self.optional_params = kwargs
        super().__init__(**kwargs)

    @log_guardrail_information
    async def async_post_call_success_hook(self, data, user_api_key_dict, response):
        import json
        if "BLOCKME" in json.dumps(response):
            raise HTTPException(status_code=400, detail={"error": "blocked by block-demo guardrail"})
        return response

Run the proxy and fire the same two requests (block + allow) before and after the fix:

LITELLM_OTEL_V2=1 OTEL_EXPORTER=console python litellm/proxy/proxy_cli.py --config config.yaml --port 4000 > proxy.log 2>&1 &

# block (response contains BLOCKME)
curl -s -o /dev/null -w "HTTP %{http_code}\n" -X POST http://127.0.0.1:4000/mock/echo \
  -H 'content-type: application/json' -H 'Authorization: Bearer sk-1234' -d '{"text":"BLOCKME please"}'
# allow
curl -s -o /dev/null -w "HTTP %{http_code}\n" -X POST http://127.0.0.1:4000/mock/echo \
  -H 'content-type: application/json' -H 'Authorization: Bearer sk-1234' -d '{"text":"hello world"}'

grep -oE '"name": "execute_guardrail[^"]*"' proxy.log | sort | uniq -c

Both requests return the same status before and after (HTTP 400 then HTTP 200); the difference is the emitted spans.

Before the fix (block span missing, only the allow request emits one):

1 "name": "execute_guardrail block-demo"

After the fix (both requests emit a guardrail span):

2 "name": "execute_guardrail block-demo"

The block span carries the intervention status:

{
  "name": "execute_guardrail block-demo",
  "status": { "status_code": "ERROR", "description": "guardrail_intervened" },
  "attributes": {
    "litellm.guardrail.name": "block-demo",
    "litellm.guardrail.mode": "post_call",
    "litellm.guardrail.status": "guardrail_intervened"
  }
}

Type

🐛 Bug Fix

Changes

• litellm/proxy/pass_through_endpoints/pass_through_endpoints.py: capture the post-call guardrail hook_data and carry its standard_logging_guardrail_information onto the failure-path request_data via _carry_guardrail_logging_info (copies the list, does not clobber existing entries).
• tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_guardrail_block_otel_span.py: regression test that drives the real pass_through_request with a real otel_v2 logger (in-memory exporter) and a real blocking guardrail, asserting the execute_guardrail span is emitted on both block and allow. Fails on the block case without the fix.
• tests/test_litellm/proxy/pass_through_endpoints/test_carry_guardrail_logging_info.py: focused unit tests pinning the helper's contract (carries entries, copies the list, populates existing metadata without clobbering, no-ops when nothing to carry); no otel dependency.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

Fixes a missing OTel guardrail span on the passthrough endpoint block path by capturing the hook_data dict post-call guardrails write into, then copying its standard_logging_guardrail_information over to the request_payload forwarded to post_call_failure_hook via the new _carry_guardrail_logging_info helper.

• _carry_guardrail_logging_info uses setdefault with list(entries) so it never clobbers pre-existing entries and never aliases the source list into the destination dict.
• Three test files cover the helper's contract (unit), the full OTel span emission on both allow and block (integration with in-memory exporter), and the failure-path propagation (mock-based regression).

Confidence Score: 5/5

The change is a targeted, additive fix confined to the passthrough failure path; on every other code path it is a no-op, and the new helper is exercised end-to-end by both unit and integration tests.

The fix adds one small helper function and two lines to the exception handler. The helper is a no-op when post_call_guardrail_data is None (non-guardrail exceptions, pre-call blocks) and uses setdefault + a shallow list copy to safely merge metadata. All changed logic is covered by three test files that use mocked upstream transport, so no real network calls are made. No regressions to existing behaviour were identified.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/pass_through_endpoints/pass_through_endpoints.py	Adds _carry_guardrail_logging_info helper and post_call_guardrail_data capture variable to propagate guardrail logging info from the throwaway hook_data dict to the failure path; fix is minimal, correctly scoped, and is a no-op for non-guardrail exceptions.
tests/test_litellm/proxy/pass_through_endpoints/test_carry_guardrail_logging_info.py	New unit tests pin all contracts of _carry_guardrail_logging_info (carries entries, copy not share, no-op on None/empty, does not clobber existing keys); no network calls, no OTel dependency.
tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_guardrail_block_otel_span.py	Regression integration tests drive the real pass_through_request with an in-memory OTel exporter and a real blocking guardrail; upstream is fully mocked with no network calls.
tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_post_call_guardrails.py	Adds test_deny_forwards_guardrail_logging_info_to_failure_hook to verify the failure handler propagates standard_logging_guardrail_information to post_call_failure_hook; adds from fastapi import HTTPException import needed for the new test.

_{Reviews (2): Last reviewed commit: "test(passthrough): cover deny-path guard..." | Re-trigger Greptile}

[yassin-berriai]

@greptileai