Zum Hauptinhalt springen
Sie haben ein Guardrail angehängt und wollen nun sehen, was es gefangen hat. Der Matches-Feed ist das Guardrail-Match-Log von OrcaRouter — jedes Mal, wenn eine Regel feuert (block, mask, flag, annotate oder spotlight), zeichnet das Gateway einen Match auf, den Sie in der Konsole überprüfen oder über die API abrufen können. So beantworten Sie „Was hat die PII-Regel gestern redigiert?”, „Welcher Key löst den Secrets-Blocker aus?” und „Feuert diese Regel auf echtem Traffic oder ist sie nur Rauschen?”. Diese Seite ist der fokussierte Leitfaden zum Lesen und Triagieren von Matches. Wie Regeln verfasst werden und was jede Action tut, finden Sie in der Guardrails-Referenz.

​
1. Was das Guardrail-Match-Log aufzeichnet

Jede gefeuerte Regel schreibt einen Match in einen workspace-bezogenen Feed (GET /api/guardrail/match, offen für jedes Member). Der Feed ist getrennt von Ihrem Request-Log — er speichert nur, was ein Guardrail tat, nicht den vollständigen Request-Body. Jeder Match zeichnet auf:
rule_type (keyword, regex, pii, max_chars, external, llm_judge, grounding), die effektive action (block / mask / flag / annotate / spotlight) und die stage (input oder output) — sodass Sie sofort erkennen, was gefeuert hat und was es tat.
guardrail_name, das feuernde rule_label plus den Request-Kontext: model_name, das token, mit dem er hereinkam, die Aufrufer-ip und die request_id, die zu Ihrem Request-Log zurückführt.
detail — die kurze, menschenlesbare Notiz der Engine zum Verstoß (z. B. welche Entity oder welches Muster ausgelöst hat), stets aufgezeichnet.
matched wird nur befüllt, wenn der Schalter Log raw content des Guardrails aktiviert ist. Er ist standardmäßig deaktiviert, sodass der Feed standardmäßig sagt, dass eine Regel gefeuert hat und warum, aber nie den sensiblen String selbst speichert.
Rohinhalt ist Opt-in und nicht-rückwirkend. Mit deaktiviertem Log raw content (dem Standard) bleibt das matched-Feld leer — der Feed zeichnet das Verdikt und detail auf, nie die E-Mail-Adresse, das Secret oder die PII, die die Regel auslöste. Aktivieren Sie es pro Guardrail nur, wenn Sie den Substring für die Triage benötigen; es gilt für Matches, die nach der Aktivierung aufgezeichnet werden. Siehe Logging & Datenschutz.

​
2. Das Match-Log auflisten und filtern

Die Standard-Listenansicht ist cursor-paginiert, neueste zuerst, und auf Ihren Workspace beschränkt. Grenzen Sie sie mit Query-Parametern ein — die Konsole legt diese als Filter-Chips offen:
ParamFiltert nach
guardrail_id, rule_type, action, stageDem Verdikt
token_id, model_name, request_idDem Request-Kontext
days / start_at + end_at, hide_fpFenster und False-Positive-Zustand
Ein typischer „Zeig mir alles, was das Secrets-Guardrail diese Woche blockiert hat”-Lesezugriff, mit Ihrem Konsolen-Session-Token: 
curl "https://api.orcarouter.ai/api/guardrail/match?guardrail_id=42&action=block&days=7" \
  -H "Authorization: Bearer <your-session-token>" \
  -H "X-Workspace-Id: <workspace-id>"
Management-Routen wie /api/guardrail/* authentifizieren sich mit Ihrem Konsolen-Session-/Access-Token, nicht mit einem Relay-Key. Die sk-orca-...-Keys sind nur für /v1/*-Modellaufrufe. Im Tagesgeschäft lesen Sie den Feed direkt aus dem Tab Matches auf der Guardrails-Seite.

​
3. Nach Request gruppieren

Ein einzelner Request kann mehrere Regeln auf einmal auslösen — etwa eine Input-PII-Maskierung und ein Max-Length-Limit. Die gruppierte Ansicht (GET /api/guardrail/match/grouped, Member) kollabiert Matches nach request_id, sodass Sie eine Zeile pro anstößigem Request mit seinen inline eingeklappten Matches sehen, statt an fünf Zeilen für denselben Aufruf vorbeizuscrollen. Justieren Sie mit inline_limit (Standard 5), wie viele Matches inline pro Gruppe angezeigt werden.

​
4. Statistiken und der Trend-Streifen

Der Stats-Endpunkt (GET /api/guardrail/match/stats, Member) treibt den Zählstreifen und das Diagramm im Matches-Tab an — Summen über ein days-Fenster, optional aufgeschlüsselt mit group_by:
group_byAufschlüsselung
(weggelassen)Nur Summen
rule_typeWelche Regeltypen am häufigsten feuern
guardrail_idWelches Guardrail die Aktivität ausmacht
Übergeben Sie request_id, um eine konstantzeitige Match-Anzahl für einen Request zu erhalten (genutzt vom Request-Log-Querverweis). Hier leben Pro-Guardrail-Nutzung, Action-Mix und False-Positive-Rate — zerlegen Sie es, statt die Rohliste durchzublättern.

​
5. Für einen Audit-Trail exportieren

Wenn Sie Matches außerhalb der Konsole brauchen — ein Beweispaket, eine Tabelle, ein nachgelagertes SIEM — streamt GET /api/guardrail/match/export (Member) Ihr aktuelles Filterset als CSV oder JSON: 
curl "https://api.orcarouter.ai/api/guardrail/match/export?format=csv&guardrail_id=42&days=30" \
  -H "Authorization: Bearer <your-session-token>" \
  -H "X-Workspace-Id: <workspace-id>" \
  -o guardrail-matches.csv
Der Export trägt dieselben Spalten, die der Feed aufzeichnet — Zeit, Guardrail, Regeltyp und Label, Stage, Action, Modell, Token, Detail, den getroffenen Substring (nur wenn die Rohinhalt-Erfassung zum Aufzeichnungszeitpunkt aktiviert war), Request-ID, IP und den False-Positive-Zeitstempel.
Die CSV ist formel-injektionssicher: Jede Zelle, die sonst als Tabellenformel gelesen würde, wird neutralisiert, sodass das Öffnen eines Exports in Excel oder Sheets keine über einen getroffenen Substring geschmuggelte Payload ausführen kann.

​
6. False Positives triagieren

Nicht jeder Match ist ein echter Treffer. Wenn eine Regel auf gutartigem Traffic feuert, kann ein Workspace-Admin den Match als False Positive markieren (POST /api/guardrail/match/:id/mark-fp); das inverse DELETE /api/guardrail/match/:id/mark-fp entmarkiert ihn. Das Markieren ist nur Admin, obwohl der Rest des Feeds Member-lesbar ist — Triage ist eine privilegierte Aktion. Das Markieren eines False Positive tut zwei Dinge: Es taggt den Match (sodass hide_fp=true ihn aus dem Feed filtert) und merkt sich das Finding, sodass dieselbe Regel auf demselben Inhalt bei zukünftigen Requests übersprungen wird. Entmarkieren, um die Durchsetzung wiederherzustellen. Für den breiteren Ablauf des Justierens einer lauten Regel siehe False Positives justieren.
Ein Match sind Diagnosedaten, keine Durchsetzungsentscheidung. Ob ein Request blockiert, maskiert oder lediglich markiert wurde, ist bereits zur Request-Zeit durch die Action entschieden — der Feed ist der Datensatz im Nachhinein. Das Markieren eines False Positive ändert zukünftiges Verhalten, nie den bereits geschehenen Aufruf.

​
7. Woher Matches kommen

Matches werden von der Guardrail-Engine auf dem Relay-Pfad produziert, sodass der Feed genau widerspiegelt, was Ihre angehängten Policies taten:
  • Input-Stage-Matches zeichnen auf, was das Gateway prüfte, bevor das Modell es sah — siehe Input-Stage.
  • Output-Stage-Matches zeichnen auf, was es auf der Response prüfte — siehe Output-Stage.
  • Ein blockierter Request erscheint zudem als HTTP 400 guardrail_blocked beim Aufrufer; der Match ist der serverseitige Datensatz davon.
Wenn auf einem Request kein Guardrail aufgelöst wird, wird nichts geprüft und nichts landet im Feed — das Verhalten ist identisch zu einem Workspace, der das Feature nie aktiviert hat. Siehe An einen Key anhängen und Account-Default dazu, wie eine Policy überhaupt vor den Traffic gelangt.

​
8. Verwandtes

Guardrails-Referenz

Die vollständige Engine: Regeltypen, Stages, Actions, Presets, Eval-Harness.

Logging & Datenschutz

Der Log-raw-content-Schalter und was der Feed speichert — und nicht speichert.

False Positives justieren

Nutzen Sie den Feed, um laute Regeln zu finden und zu beruhigen, ohne die Policy zu schwächen.

Versionierung

Diffen und setzen Sie ein Guardrail zurück, wenn der Feed zeigt, dass eine Änderung danebenging.
Für das größere Bild, wie das Gateway Traffic inspiziert, siehe Wie OrcaRouter inspiziert und Guardrails vs. Firewall.