Investigate a guardrail decision

When a user reports “the assistant refused my request” or “my prompt came back altered”, /guardrail-logs holds the answer. Every guardrail evaluation is recorded with what matched and what the pipeline did about it.

Steps

1. Open /guardrail-logs.

2. Locate the request. Filter by time, by the key that made it, or by the guardrail that fired.

3. Read the outcome.

modified is the one people miss. The request succeeded and the model answered — but it answered a rewritten prompt. If output quality is the complaint rather than an outright refusal, this is where to look.

What is stored, and what deliberately is not

In mask mode original_content is empty by design. The whole point of reversible redaction is that raw PII never lands in a log, so the record shows the masked form ([EMAIL_1], [SSN_1]) and the placeholders it substituted.

That is a deliberate trade: you can see that an email was detected and where, but not what it was. If you need the original value you need the source system, not the audit trail.

Common diagnoses

A guardrail never appears in the logs. It is not running. Check it is enabled in /guardrails, and that its type is spelled exactly as the platform expects — an unrecognised type is stored happily and never matches anything.

Too many false positives. Lower the detector’s sensitivity in its Config (JSON), e.g. raise {"threshold": 0.8} toward 0.95. Change one guardrail at a time; with several running it is otherwise guesswork which one moved.

Blocked when masking would do. Switch aocore_params from {"mode":"block"} to {"mode":"mask"}. The model then works on masked text and the caller still sees real values — see Configure a guardrail.

Placeholders leaking into the user’s output. Restoration puts the real value back when the model echoes a placeholder. If placeholders are reaching users, the model paraphrased rather than echoed — it wrote the customer's email instead of [EMAIL_1]. Nothing can restore a value the model did not reproduce; this is a prompt-design issue, not a redaction failure.

Correlating with the rest of the platform

A useful sequence when behaviour changed and nobody knows why: find the first affected request in /guardrail-logs, note its timestamp, then look in /audit-logs immediately before it for a guardrail mutation. The before/after snapshot on that entry tells you exactly what changed.