fix(otel): emit guardrail span on violation, surface status + categories

[yassin-berriai]

Summary

Resolves LIT-3234

When a pre-call guardrail blocked a request, the production failure path was missing the guardrail child span entirely, and the guardrail span on the _handle_failure path didn't surface guardrail_status or the violated categories as queryable attributes — that data was buried inside the serialised guardrail_response blob.

This PR:

1. Emits guardrail spans from async_post_call_failure_hook by reading request_data["metadata"]["standard_logging_guardrail_information"] and routing through _create_guardrail_span. Dedupe via _emit_once keeps this safe even when _handle_failure already emitted the span on the same kwargs.

2. Enriches every guardrail span with guardrail_status (success / guardrail_intervened / guardrail_failed_to_respond / not_run), guardrail_action (the provider's top-level action — Bedrock's GUARDRAIL_INTERVENED / NONE), and — when the guardrail intervened — guardrail_violation_categories extracted from Bedrock assessments[*] policy items whose action is BLOCKED / ANONYMIZED.

Repro

A pre-call guardrail block from a Bedrock guardrail looks like this:

1. Configure litellm proxy with a Bedrock guardrail attached as pre_call.
2. Configure OTEL to export to a backend (or use OTEL_EXPORTER=console).
3. Send a /chat/completions request that triggers a topic-policy / content-policy block.
4. Inspect the trace.

The same path is exercised in a standalone script that does not require AWS:

import asyncio
from dataclasses import dataclass

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter

from litellm.integrations.opentelemetry import OpenTelemetry


@dataclass
class FakeUserAPIKey:
    api_key: str = "sk-test"
    parent_otel_span: object = None
    request_route: str = "/chat/completions"
    team_id: str = "team-1"
    team_alias: str = "demo-team"


exporter = InMemorySpanExporter()
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(exporter))
otel = OpenTelemetry(tracer_provider=provider)
otel.tracer = provider.get_tracer(__name__)

parent_span = otel.tracer.start_span("Received Proxy Server Request")
request_data = {
    "model": "gpt-4",
    "metadata": {
        "standard_logging_guardrail_information": [
            {
                "guardrail_name": "bedrock-policy",
                "guardrail_provider": "bedrock",
                "guardrail_mode": "pre_call",
                "guardrail_status": "guardrail_intervened",
                "guardrail_response": {
                    "action": "GUARDRAIL_INTERVENED",
                    "assessments": [
                        {
                            "topicPolicy": {"topics": [{"name": "Fiduciary Advice", "action": "BLOCKED"}]},
                            "contentPolicy": {"filters": [{"type": "VIOLENCE", "action": "BLOCKED"}]},
                        }
                    ],
                },
                "start_time": 1.0,
                "end_time": 1.05,
            }
        ]
    },
}

asyncio.new_event_loop().run_until_complete(
    otel.async_post_call_failure_hook(
        request_data=request_data,
        original_exception=Exception("Bedrock guardrail blocked"),
        user_api_key_dict=FakeUserAPIKey(parent_otel_span=parent_span),
    )
)

for s in exporter.get_finished_spans():
    print(s.name, dict(s.attributes or {}))

Before / after — async_post_call_failure_hook (prod failure path)

Before: no guardrail span emitted at all.

[
  {"name": "Failed Proxy Server Request", "status": "ERROR", "parent": "Received Proxy Server Request"},
  {"name": "Received Proxy Server Request", "status": "ERROR", "parent": "<root>"}
]

After: guardrail span emitted as a child of the proxy span, carrying status + violated categories.

[
  {"name": "Failed Proxy Server Request", "status": "ERROR", "parent": "Received Proxy Server Request"},
  {
    "name": "guardrail",
    "parent": "Received Proxy Server Request",
    "attributes": {
      "guardrail_name": "bedrock-policy",
      "guardrail_mode": "pre_call",
      "guardrail_status": "guardrail_intervened",
      "guardrail_action": "GUARDRAIL_INTERVENED",
      "guardrail_violation_categories": "[\"Fiduciary Advice\", \"VIOLENCE\"]"
    }
  },
  {"name": "Received Proxy Server Request", "status": "ERROR", "parent": "<root>"}
]

Before / after — _handle_failure (logging-handler path)

Before: guardrail span existed but lacked status / action / categories.

{
  "name": "guardrail",
  "attributes": {
    "guardrail_name": "bedrock-policy",
    "guardrail_mode": "pre_call",
    "guardrail_response": "{...full Bedrock JSON, only inspectable by parsing...}"
  }
}

After: queryable status + action + categories attributes on the same span.

{
  "name": "guardrail",
  "attributes": {
    "guardrail_name": "bedrock-policy",
    "guardrail_mode": "pre_call",
    "guardrail_response": "{...}",
    "guardrail_status": "guardrail_intervened",
    "guardrail_action": "GUARDRAIL_INTERVENED",
    "guardrail_violation_categories": "[\"Fiduciary Advice\", \"VIOLENCE\"]"
  }
}

Test plan

• uv run pytest tests/test_litellm/integrations/test_otel_guardrail_violation_spans.py (new file, 10 tests covering: failure-path span creation, post-call-failure-hook span emission, attribute presence for every GuardrailStatus, category extraction from Bedrock topic/content/word/PII/grounding policies, multi-guardrail flow where only the last one blocks, end-to-end with a real CustomGuardrail subclass)
• uv run pytest tests/test_litellm/integrations/test_opentelemetry.py (full existing suite still passes — 219 tests)

🤖 Generated with Claude Code

[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.}

[yassin-berriai]

@greptileai

[greptile-apps]

Greptile Summary

This PR fixes two gaps in guardrail OTEL tracing: the async_post_call_failure_hook now emits a child guardrail span when a pre-call guardrail blocks a request (previously the span was never created on the proxy failure path), and every guardrail span is enriched with queryable guardrail_status, guardrail_action, and guardrail_violation_categories attributes instead of burying that data inside the serialised guardrail_response blob.

• Provider-specific extraction (_extract_violation_category_names) lives in bedrock_guardrails.py and runs before redaction, populating violation_categories and guardrail_action on GuardrailTracingDetail/StandardLoggingGuardrailInformation so the OTEL integration stays provider-agnostic.
• Deduplication relies on _emit_once sharing a dict identity between kwargs[\"litellm_params\"][\"metadata\"] and request_data[\"metadata\"]; the synthetic kwargs in _emit_guardrail_spans_from_request_data passes the same dict reference to honour this contract.
• Ten new tests cover the failure-path span, dedup, every GuardrailStatus variant, the guardrail_action attribute, and a full end-to-end flow through a real CustomGuardrail subclass.

Confidence Score: 5/5

Safe to merge — all changed paths are additive observability instrumentation with no effect on request routing or auth.

All previously identified blocking findings have been addressed: Bedrock-specific parsing now lives in bedrock_guardrails.py, guardrail_action is fully wired end-to-end, the fastapi import is absent from the test file, and the event-loop leak is fixed via the _run() helper. No new functional defects found in this revision.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/integrations/opentelemetry.py	Adds _emit_guardrail_spans_from_request_data to emit guardrail child spans from the failure hook using the same metadata dict for dedup; enriches every guardrail span with guardrail_status, guardrail_action, and guardrail_violation_categories read from normalised fields on StandardLoggingGuardrailInformation.
litellm/proxy/guardrails/guardrail_hooks/bedrock_guardrails.py	Adds _extract_violation_category_names to build a safe, non-sensitive label list before redaction; propagates both violation_categories and guardrail_action via GuardrailTracingDetail into StandardLoggingGuardrailInformation.
litellm/types/utils.py	Adds violation_categories and guardrail_action fields to both StandardLoggingGuardrailInformation and GuardrailTracingDetail TypedDicts.
tests/test_litellm/integrations/test_otel_guardrail_violation_spans.py	New test file covering failure-path span emission, dedup via shared metadata dict identity, attribute presence for all GuardrailStatus values, guardrail_action population, and an end-to-end flow through a real CustomGuardrail subclass. Correctly uses a _run() helper that closes the event loop.
tests/test_litellm/proxy/guardrails/guardrail_hooks/test_bedrock_guardrails.py	Adds unit tests for _extract_violation_category_names (mixed policies, security/no-leak, named-regex, ANONYMIZED skip, empty assessments) and two async tests verifying guardrail_action forwarding through tracing_detail.

_{Reviews (8): Last reviewed commit: "fix(otel): emit guardrail_action span at..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[yassin-berriai]

@greptileai re-review please — addressed feedback: pushed Bedrock parsing into BedrockGuardrail (added _extract_violation_category_names), added violation_categories to StandardLoggingGuardrailInformation / GuardrailTracingDetail so OTEL stays provider-agnostic, dropped guardrail_action, removed fastapi import from tests, fixed event-loop cleanup, added an explicit dedupe test.

[yassin-berriai]

Note for human reviewers: the 3 inline Greptile comments still attached to commit cfc55825 are stale carry-overs from the original review on 8353bcae. All have been addressed:

• Event loops not closed → added _run helper in the test file that always closes the loop in a finally.
• fastapi import outside proxy/ → swapped HTTPException for a plain local Exception subclass.
• Dedupe relies on shared dict identity → added explicit test test_handle_failure_and_post_call_failure_hook_dedupe that exercises both code paths back-to-back and asserts exactly one guardrail span.

Bedrock-specific parsing has been moved out of opentelemetry.py into BedrockGuardrail._extract_violation_category_names, with a new generic violation_categories field on StandardLoggingGuardrailInformation / GuardrailTracingDetail. Retriggered Greptile.

[veria-ai]

PR overview

Guardrail telemetry spans expanded

This PR adds failure-path guardrail span emission and surfaces Bedrock guardrail status/action/category attributes in OTel. I checked the new span data flow from Bedrock responses through standard guardrail logging, including redaction boundaries and the request metadata fallback path, and did not find a concrete security issue.

Security review

• No new security issues were flagged in the latest review.
• No review issues remain open on this pull request.

Risk: 2/10

[yassin-berriai]

@greptileai please re-review on commit c5ddb60bb5 — addresses all P1/P2 concerns from the initial review plus the veria-ai security finding.

[yassin-berriai]

@greptileai

[yassin-berriai]

@greptileai review

[yassin-berriai]

@greptileai

[yassin-berriai]

@greptileai please re-review on commit 1859bd76 — addresses the P1 guardrail_action finding from the last review. Bedrock hook now writes the raw top-level action onto StandardLoggingGuardrailInformation via GuardrailTracingDetail, OTEL reads the normalised field (no provider-specific parsing). Tests cover both populated and absent paths.