Observability
Shield guardrail evaluations are fully observable through Observatory. Every enforcement decision — allow, block, redact, or monitor — is captured as a structured event with the evidence and policy context needed to understand why it was made.
How Shield decisions appear in Observatory
In the Threats view
Blocked and monitored events from Shield appear in Observatory → Threats alongside events from the Agent Gateway, Browser Security, and Code Agents. Each Shield event includes:
The determining policies — the specific Cedar policy IDs that drove the block or alert, with their
@id,@severity, and@tagsannotationsThe projected context — the detector outputs (injection score, PII flags, secret types, tool risk score, etc.) that Cedar evaluated
The enforcement mode — whether the rule was in Block, Monitor, or Alert at the time
The policy reason — a human-readable explanation from the Cedar policy's
@reject_messageannotation
In the Traces view
Shield evaluations appear as spans within the distributed trace for each agent request. Each guardrail evaluation span records:
Which evaluation point fired (user prompt, tool call, tool response, assistant response)
The evaluation latency broken down by detection tier (fast / standard / slow)
The guardrail outcome and the determining policies
The number of threats detected and their highest severity
This makes it possible to see a guardrail block in context — the span immediately before it shows what the agent was doing, and spans after show what happened next (or confirm the session was terminated).
In the Sessions view
Shield's session-level signals (session_cumulative_risk_score, session_threat_turns, loop_detected, budget_exceeded) are surfaced in Observatory → Sessions as agentic lifecycle metrics. Use these to identify sessions where risk accumulated gradually across turns rather than triggering a single high-confidence block.
OpenTelemetry
Shield emits spans using the OpenTelemetry standard with the hf.* attribute convention. If you export traces to an external backend (Datadog, Honeycomb, Jaeger), Shield spans appear alongside your application spans. See Traces for OTLP exporter configuration.
Further reading
For full documentation on investigation workflows, retention, faceted search, and alerting:
Last updated