# Observability

Shield guardrail evaluations are fully observable through [Observatory](/observatory/observatory.md). 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](/observatory/threats.md) 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](/observatory/sessions.md) 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](/observatory/traces.md) for OTLP exporter configuration.

***

## Further reading

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/agent-authorization-and-control-shield/observability.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.