Avvisi

​

Concetti

• Avviso — la regola. Dice cosa verificare (il trigger), con quale frequenza (l’intervallo di valutazione), quando considerarla rotta (logica composta), quanto è urgente (severità), e chi/dove notificare (canali).
• Incidente — quello che accade quando un avviso si attiva. Un avviso ha al massimo un incidente aperto per volta. Le violazioni ripetute aggiornano le evidenze dello stesso incidente. Gli incidenti vengono risolti da un operatore; la risoluzione automatica quando la regola smette di attivarsi è pianificata ma non attualmente abilitata.
• Canale — dove va una notifica: email, Slack, webhook generico, o in-dashboard. Ogni avviso può collegare qualsiasi combinazione.

​

Tipi di trigger

​

1. metric_threshold

{
  "metric": "p95_latency_ms",
  "filter": { "environment": "production" },
  "window_secs": 900,
  "op": ">",
  "value": 5000
}

​

2. custom_sql

• modalità righe (nessun op/value): l’avviso si attiva non appena la query restituisce almeno una riga.
• modalità valore: la query deve alias una colonna come metric_value; il dispatcher confronta il metric_value della prima riga rispetto a value usando op.

{
  "sql": "SELECT count() AS metric_value FROM agenteye.events WHERE event_type = 'error' AND ts >= now() - INTERVAL 1 HOUR",
  "op": ">",
  "value": 100
}

​

3. evaluation_score

{
  "score_key": "hallucination",
  "op": ">",
  "value": 0.6,
  "window_secs": 3600,
  "min_count": 5,
  "environment": "production"
}

​

4. eval_compound

{
  "combinator": { "at_least": 2 },
  "conditions": [
    { "score_key": "hallucination", "op": ">", "value": 0.8 },
    { "score_key": "helpfulness",   "op": "<", "value": 0.6 },
    { "score_key": "tone",          "op": "<", "value": 0.5 }
  ],
  "window_secs": 3600,
  "min_count": 5,
  "environment": "production"
}

• combinator: "any", "all", o { "at_least": N }.
• conditions[]: ogni { score_key, op, value }, usando gli stessi operatori degli altri trigger (>, >=, <, <=, ==).
• window_secs: il lookback condiviso applicato a ogni condizione (predefinito 3600).
• min_count: numero minimo per-condizione di valutazioni prima che quella condizione possa violare; una condizione con troppi pochi campioni nella finestra conta come “non violata” (predefinito 1).
• environment: opzionale; limita ogni condizione a un ambiente.

​

5. per_event

{
  "event_type": "error",
  "lookback_secs": 60,
  "environment": "production",
  "tool_name": "bash",
  "agent_id": "caa",
  "error_type": "TimeoutError",
  "message_contains": "vertex-ai timed out"
}

​

Logica composta (M of N)

• eval_window: quante valutazioni recenti guardare (predefinito 1)
• min_breaches: quante di queste devono violare prima che l’avviso si attivi (predefinito 1)

​

Intervallo di valutazione

​

Canali

​

Email

1. Override recipients[] per-canale (quando non vuoto).
2. L’impostazione alerts.email_default_recipients (un array di stringhe email).

​

Slack

• URL predefinito: alerts.slack_default_webhook (impostato in /settings).
• Override per-alert: imposta il webhook_setting_key del canale a qualsiasi altra chiave di impostazione di tipo URL, ad es. alerts.slack_oncall, alerts.slack_costs.

​

Webhook generico

{
  "schema_version": 1,
  "event": "alert.firing",
  "incident": { "id": "uuid", "url": "https://…/incidents/uuid", "opened_at": "2026-…" },
  "alert":    { "id": "uuid", "name": "errors > 50/hr", "severity": "critical" },
  "breach":   { "value": 73.0, "summary": "ErrorCount > 50 (observed 73.000)", "evidence": { … } }
}

​

In-dashboard

​

Ciclo di vita dell’incidente

firing  ──ack──▶  acknowledged
   │                    │
   └────────────────────┴───── operator resolve ───▶  resolved

• firing — il dispatcher ha appena aperto l’incidente o ha rilevato un’altra violazione. La notifica di firing è diffusa esattamente una volta (controllata dal timestamp notified_firing_at sull’incidente).
• acknowledged — un operatore ha premuto ack su /incidents/:id. L’incidente è ancora considerato aperto; le violazioni successive aggiorneranno le sue evidenze senza ri-notificare.
• resolved — un operatore ha premuto resolve. La risoluzione automatica quando la regola smette di violare è pianificata ma non attualmente abilitata, quindi un incidente aperto rimane aperto finché un operatore non lo risolve.

​

Permessi richiesti

• alerts:read: visualizza le regole di avviso.
• alerts:write: crea, modifica, elimina regole di avviso e attiva una notifica di test.
• incidents:read: visualizza gli incidenti.
• incidents:write: apri incidenti manuali (ad-hoc) non legati a un avviso.
• incidents:ack: acknowledges, assegna, commenta e risolvi incidenti.

Legacy alerts:ack. Le chiavi e gli operatori a cui è stato concesso il token alerts:ack più vecchio continuano a funzionare: viene onorato come incidents:ack (e implica incidents:read), quindi gli on-caller esistenti mantengono il loro accesso senza ri-emettere credenziali. Emetti nuove concessioni con la famiglia incidents:*.

Email-recipient picker. Il selettore di destinatari dell’editor di avviso elenca i membri della tua organizzazione in modo da poterli selezionare per nome. Si carica per qualsiasi operatore che detiene alerts:read o alerts:write; visualizzare la directory del tuo team a questo scopo non richiede users:read, e il selettore restituisce solo gli indirizzi email dei membri, mai record utente completi.

​

Configurazione

• alerts.email_default_recipients (email_list): array JSON di stringhe email — i destinatari predefiniti per i canali email.
• alerts.slack_default_webhook (url): URL webhook in arrivo Slack predefinito.
• alerts.webhook_default_url (url): URL webhook generico predefinito.
• alerts.webhook_signing_secret (secret): chiave HMAC-SHA256. Sempre restituita come "" nella risposta GET; digita un nuovo valore per ruotare.
• alerts.enabled_channels (channel_set): il set a livello di organizzazione dei tipi di canale esterni che vengono inviati quando un avviso si attiva; di default tutti e tre (email, slack, webhook). Rimuovendo un tipo qui globalmente sopprimi quel canale per ogni avviso senza modificare ogni regola. Il canale in-dashboard è sempre consegnato e non è interessato da questa impostazione.

​

Verifica un nuovo avviso

1. Salvalo come abilitato con almeno un canale di notifica.
2. Seleziona test sulla pagina di dettaglio dell’avviso e conferma che ogni destinazione configurato riceva la notifica sintetica.
3. Dopo la prima violazione reale, conferma che l’incidente appaia sotto Incidenti e che il suo valore misurato corrisponda alla corrispondente query della dashboard.

​

Risoluzione dei problemi