Passer au contenu principal
Vous avez attaché un guardrail et maintenant vous voulez voir ce qu’il a attrapé. Le flux Matches est le journal de correspondances de guardrail d’OrcaRouter — chaque fois qu’une règle se déclenche (block, mask, flag, annotate ou spotlight), la passerelle enregistre une correspondance que vous pouvez examiner dans la console ou tirer via l’API. C’est ainsi que vous répondez à « ce que la règle PII a redacté hier ? », « quelle clé déclenche le bloqueur de secrets ? », et « cette règle se déclenche-t-elle sur du trafic réel ou juste du bruit ? ». Cette page est le guide ciblé sur la lecture et le triage des correspondances. Pour la façon dont les règles sont rédigées et ce que fait chaque action, voir la référence Guardrails.

​
1. Ce que le journal de correspondances enregistre

Chaque règle déclenchée écrit une correspondance dans un flux à portée d’espace de travail (GET /api/guardrail/match, ouvert à tout Member). Le flux est séparé de votre journal de requête — il ne stocke que ce qu’un guardrail a fait, pas le corps complet de la requête. Chaque correspondance enregistre :
rule_type (keyword, regex, pii, max_chars, external, llm_judge, grounding), l’action effective (block / mask / flag / annotate / spotlight), et l’stage (input ou output) — afin que vous puissiez dire instantanément ce qui s’est déclenché et ce que ça a fait.
guardrail_name, le rule_label déclencheur, plus le contexte de la requête : model_name, le token sur lequel elle a circulé, l’ip de l’appelant, et le request_id qui rejoint votre journal de requête.
detail — la courte note lisible par un humain du moteur pour la violation (par exemple quelle entité ou quel motif s’est déclenché), toujours enregistrée.
matched n’est rempli que lorsque le toggle Log raw content du guardrail est activé. Il est désactivé par défaut, donc par défaut le flux vous dit qu’une règle s’est déclenchée et pourquoi, mais ne stocke jamais la chaîne sensible elle-même.
Le contenu brut est opt-in et non rétroactif. Avec Log raw content désactivé (le défaut), le champ matched reste vide — le flux enregistre le verdict et detail, jamais l’adresse email, le secret ou la PII qui a déclenché la règle. Activez-le par guardrail uniquement quand vous avez besoin de la sous-chaîne pour le triage ; il s’applique aux correspondances enregistrées après que vous l’avez activé. Voir Journalisation & confidentialité.

​
2. Lister et filtrer le journal de correspondances

La vue de liste par défaut est paginée par curseur, du plus récent au plus ancien, et à portée de votre espace de travail. Affinez-la avec des paramètres de requête — la console les expose comme des puces de filtre :
ParamètreFiltre par
guardrail_id, rule_type, action, stageLe verdict
token_id, model_name, request_idLe contexte de la requête
days / start_at + end_at, hide_fpFenêtre et état de faux positif
Une lecture typique « montre-moi tout ce que le guardrail de secrets a bloqué cette semaine », en utilisant votre token de session de console : 
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>"
Les routes de gestion comme /api/guardrail/* s’authentifient avec votre session / token d’accès de console, pas une clé de relais. Les clés sk-orca-... ne servent qu’aux appels de modèle /v1/*. Au quotidien, vous lirez le flux directement depuis l’onglet Matches sur la page Guardrails.

​
3. Grouper par requête

Une seule requête peut déclencher plusieurs règles à la fois — un mask de PII d’entrée et un plafond de longueur max, disons. La vue groupée (GET /api/guardrail/match/grouped, Member) collapse les correspondances par request_id afin que vous voyiez une ligne par requête fautive avec ses correspondances repliées inline, au lieu de faire défiler cinq lignes pour le même appel. Réglez combien de correspondances s’affichent inline par groupe avec inline_limit (défaut 5).

​
4. Stats et la bande de tendance

L’endpoint de stats (GET /api/guardrail/match/stats, Member) alimente la bande de compte et le graphique sur l’onglet Matches — totaux sur une fenêtre days, optionnellement ventilés avec group_by :
group_byVentilation
(omis)Totaux uniquement
rule_typeQuels types de règles se déclenchent le plus
guardrail_idQuel guardrail représente l’activité
Passez request_id pour obtenir un compte de correspondances en temps constant pour une requête (utilisé par le cross-link du journal de requête). C’est là que vivent l’usage par guardrail, le mix d’actions et le taux de faux positifs — tranchez-le plutôt que de paginer la liste brute.

​
5. Exporter pour une piste d’audit

Quand vous avez besoin des correspondances hors de la console — un pack de preuves, un tableur, un SIEM en aval — GET /api/guardrail/match/export (Member) stream votre ensemble de filtres actuel en CSV ou 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
L’export porte les mêmes colonnes que le flux enregistre — heure, guardrail, type et label de règle, étape, action, modèle, token, détail, la sous-chaîne correspondante (uniquement si la capture de contenu brut était activée au moment de l’enregistrement), id de requête, ip, et le timestamp de faux positif.
Le CSV est sûr contre l’injection de formules : toute cellule qui serait sinon lue comme une formule de tableur est neutralisée, donc ouvrir un export dans Excel ou Sheets ne peut pas exécuter un payload introduit en contrebande via une sous-chaîne correspondante.

​
6. Trier les faux positifs

Toute correspondance n’est pas un vrai hit. Quand une règle se déclenche sur du trafic bénin, un Admin de l’espace de travail peut marquer la correspondance comme faux positif (POST /api/guardrail/match/:id/mark-fp) ; l’inverse DELETE /api/guardrail/match/:id/mark-fp la dé-marque. Le marquage est réservé à l’Admin même si le reste du flux est lisible par les Member — le triage est une action privilégiée. Marquer un faux positif fait deux choses : il tague la correspondance (afin que hide_fp=true la filtre hors du flux) et mémorise le finding afin que la même règle sur le même contenu soit sautée sur les requêtes futures. Dé-marquez pour restaurer l’application. Pour le workflow plus large d’ajustement d’une règle bruyante, voir Ajuster les faux positifs.
Une correspondance est une donnée de diagnostic, pas une décision d’application. Le fait qu’une requête ait été bloquée, masquée ou simplement signalée est déjà réglé par l’action au moment de la requête — le flux est l’enregistrement après coup. Marquer un faux positif change le comportement futur, jamais l’appel qui s’est déjà produit.

​
7. D’où viennent les correspondances

Les correspondances sont produites par le moteur de guardrail sur le chemin de relais, donc le flux reflète exactement ce que vos politiques attachées ont fait :
  • Les correspondances à l’étape input enregistrent ce que la passerelle a filtré avant que le modèle ne le voie — voir Étape input.
  • Les correspondances à l’étape output enregistrent ce qu’elle a filtré sur la réponse — voir Étape output.
  • Une requête bloquée apparaît aussi comme une HTTP 400 guardrail_blocked pour l’appelant ; la correspondance en est l’enregistrement côté serveur.
Si aucun guardrail ne se résout sur une requête, rien n’est filtré et rien n’atterrit dans le flux — le comportement est identique à un espace de travail qui n’a jamais activé la fonctionnalité. Voir Attacher à une clé et Défaut de compte pour la façon dont une politique se place devant le trafic en premier lieu.

​
8. Liés

Référence Guardrails

Le moteur complet : types de règles, étapes, actions, presets, harnais d’évaluation.

Journalisation & confidentialité

Le toggle Log raw content et ce que le flux stocke — et ne stocke pas.

Ajuster les faux positifs

Utilisez le flux pour trouver et faire taire les règles bruyantes sans affaiblir la politique.

Versioning

Diffez et rétablissez un guardrail quand le flux montre qu’un changement a raté.
Pour la vue d’ensemble de la façon dont la passerelle inspecte le trafic, voir Comment OrcaRouter inspecte et Guardrails vs firewall.