Vai al contenuto principale
Hai collegato un guardrail e ora vuoi vedere cosa ha catturato. Il feed dei Matches è il log dei match dei guardrail di OrcaRouter — ogni volta che una regola scatta (block, mask, flag, annotate o spotlight), il gateway registra un match che puoi esaminare nella console o estrarre tramite l’API. È così che rispondi a “cosa ha redatto la regola PII ieri?”, “quale chiave fa scattare il secrets blocker?” e “questa regola scatta sul traffico reale o è solo rumore?”. Questa pagina è la guida focalizzata sul leggere e triare i match. Per come le regole sono scritte e cosa fa ogni azione, vedi il riferimento Guardrails.

​
1. Cosa registra il log dei match dei guardrail

Ogni regola scattata scrive un match in un feed con scope a livello di workspace (GET /api/guardrail/match, aperto a qualsiasi Member). Il feed è separato dal tuo request log — memorizza solo cosa ha fatto un guardrail, non il corpo completo della richiesta. Ogni match registra:
rule_type (keyword, regex, pii, max_chars, external, llm_judge, grounding), l’action effettiva (block / mask / flag / annotate / spotlight), e lo stage (input o output) — così puoi capire istantaneamente cosa è scattato e cosa ha fatto.
guardrail_name, il rule_label che ha scattato, più il contesto della richiesta: model_name, il token su cui è arrivato, l’ip del chiamante e il request_id che riconnette al tuo request log.
detail — la breve nota leggibile dall’uomo del motore per la violazione (es. quale entità o pattern ha fatto scattare), sempre registrata.
matched è popolato solo quando il toggle Log raw content del guardrail è attivo. È disattivato per default, quindi per default il feed ti dice che una regola è scattata e perché, ma non memorizza mai la stringa sensibile stessa.
Il contenuto grezzo è opt-in e non retroattivo. Con Log raw content disattivato (il default), il campo matched resta vuoto — il feed registra il verdetto e detail, mai l’indirizzo email, il segreto o la PII che ha fatto scattare la regola. Attivalo per ciascun guardrail solo quando ti serve la sottostringa per il triage; si applica ai match registrati dopo che lo abiliti. Vedi Logging e privacy.

​
2. Elenca e filtra il log dei match

La vista di elenco di default è paginata a cursore, dalla più recente, e con scope al tuo workspace. Restringila con query param — la console li espone come chip di filtro:
ParamFiltra per
guardrail_id, rule_type, action, stageIl verdetto
token_id, model_name, request_idIl contesto della richiesta
days / start_at + end_at, hide_fpFinestra e stato di falso positivo
Una tipica lettura “mostrami tutto ciò che il guardrail dei segreti ha bloccato questa settimana”, usando il token di sessione della tua 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>"
Le rotte di management come /api/guardrail/* si autenticano con il tuo session / access token della console, non con una chiave di relay. Le chiavi sk-orca-... servono solo per le chiamate al modello /v1/*. Nell’uso quotidiano leggerai il feed direttamente dalla tab Matches sulla pagina Guardrails.

​
3. Raggruppa per richiesta

Una singola richiesta può far scattare diverse regole contemporaneamente — un mask PII di input e un limite di max-length, diciamo. La vista raggruppata (GET /api/guardrail/match/grouped, Member) collassa i match per request_id così che tu veda una riga per richiesta incriminata con i suoi match ripiegati inline, invece di scorrere cinque righe per la stessa chiamata. Regola quanti match si mostrano inline per gruppo con inline_limit (default 5).

​
4. Stats e la striscia di trend

L’endpoint delle stats (GET /api/guardrail/match/stats, Member) alimenta la striscia di conteggio e il grafico sulla tab Matches — totali su una finestra days, opzionalmente suddivisi con group_by:
group_bySuddivisione
(omesso)Solo totali
rule_typeQuali tipi di regola scattano di più
guardrail_idQuale guardrail rende conto dell’attività
Passa request_id per ottenere un conteggio di match a tempo costante per una richiesta (usato dal cross-link del request-log). È qui che vivono l’utilizzo per guardrail, il mix di azioni e il tasso di falsi positivi — suddividilo anziché paginare l’elenco grezzo.

​
5. Esporta per una traccia di audit

Quando ti servono i match fuori dalla console — un pacchetto di evidenze, un foglio di calcolo, un SIEM a valle — GET /api/guardrail/match/export (Member) streama il tuo set di filtri corrente come CSV o 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 porta le stesse colonne che il feed registra — tempo, guardrail, tipo di regola e label, stage, action, model, token, detail, la sottostringa corrispondente (solo se la cattura del contenuto grezzo era attiva al momento della registrazione), request id, ip e il timestamp del falso positivo.
Il CSV è sicuro dall’injection di formule: qualsiasi cella che altrimenti verrebbe letta come una formula di foglio di calcolo è neutralizzata, così aprire un export in Excel o Sheets non può eseguire un payload inserito di nascosto tramite una sottostringa corrispondente.

​
6. Triage dei falsi positivi

Non ogni match è un hit reale. Quando una regola scatta sul traffico benigno, un Admin del workspace può segnare il match come falso positivo (POST /api/guardrail/match/:id/mark-fp); l’inverso DELETE /api/guardrail/match/:id/mark-fp lo desegna. La segnalazione è solo Admin anche se il resto del feed è leggibile dai Member — il triage è un’azione privilegiata. Segnare un falso positivo fa due cose: etichetta il match (così hide_fp=true lo filtra fuori dal feed) e ricorda il finding così che la stessa regola sullo stesso contenuto venga saltata nelle richieste future. Desegna per ripristinare l’applicazione. Per il workflow più ampio di mettere a punto una regola rumorosa, vedi Tuning dei falsi positivi.
Un match è dato diagnostico, non una decisione di applicazione. Se una richiesta è stata bloccata, mascherata o solo segnalata è già stabilito dall’azione al momento della richiesta — il feed è il record a posteriori. Segnare un falso positivo cambia il comportamento futuro, mai la chiamata già avvenuta.

​
7. Da dove vengono i match

I match sono prodotti dal motore di guardrail sul percorso di relay, quindi il feed riflette esattamente ciò che le tue policy collegate hanno fatto:
  • I match dello stage di input registrano cosa il gateway ha filtrato prima che il modello lo vedesse — vedi Stage di input.
  • I match dello stage di output registrano cosa ha filtrato sulla risposta — vedi Stage di output.
  • Una richiesta bloccata emerge anche come un HTTP 400 guardrail_blocked al chiamante; il match è il record lato server di esso.
Se nessun guardrail si risolve su una richiesta, nulla viene filtrato e nulla atterra nel feed — il comportamento è identico a un workspace che non ha mai abilitato la feature. Vedi Collega a una chiave e Default di account per come una policy si mette davanti al traffico in primo luogo.

​
8. Correlati

Riferimento Guardrails

Il motore completo: tipi di regola, stage, azioni, preset, harness di eval.

Logging e privacy

Il toggle Log raw content e cosa il feed memorizza — e non memorizza.

Tuning dei falsi positivi

Usa il feed per trovare e silenziare le regole rumorose senza indebolire la policy.

Versioning

Confronta e fai il revert di un guardrail quando il feed mostra che una modifica ha mancato il bersaglio.
Per il quadro più ampio di come il gateway ispeziona il traffico, vedi Come OrcaRouter ispeziona e Guardrails vs firewall.