# Observability

Shield guardrail evaluations are fully observable through [Observatory](https://docs.highflame.ai/observatory/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](https://docs.highflame.ai/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 `@tags` annotations
* The **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_message` annotation

### 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](https://docs.highflame.ai/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](https://docs.highflame.ai/observatory/traces) for OTLP exporter configuration.

***

## Further reading

For full documentation on investigation workflows, retention, faceted search, and alerting:

* [Observatory Overview](https://docs.highflame.ai/observatory/observatory)
* [Threats](https://docs.highflame.ai/observatory/threats) — filtering and investigating Shield events
* [Sessions](https://docs.highflame.ai/observatory/sessions) — session-level agentic metrics
* [Traces](https://docs.highflame.ai/observatory/traces) — distributed trace visualization and OTLP export