Alertas

​

Conceitos

• Alerta — a regra. Ela define o que verificar (o gatilho), com que frequência (o intervalo de avaliação), quando considerar algo quebrado (lógica composta), o nível de urgência (severidade) e quem/onde notificar (canais).
• Incidente — o que acontece quando um alerta é disparado. Um alerta tem no máximo um incidente aberto por vez. Violações repetidas atualizam as evidências do mesmo incidente. Incidentes são resolvidos por um operador; a resolução automática quando a regra para de disparar está planejada, mas ainda não está ativa.
• Canal — para onde uma notificação vai: e-mail, Slack, webhook genérico ou painel. Cada alerta pode usar qualquer combinação.

​

Tipos de gatilho

​

1. metric_threshold

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

​

2. custom_sql

• Modo rows (sem op/value): o alerta dispara assim que a query retorna pelo menos uma linha.
• Modo value: a query deve ter um alias de coluna chamado metric_value; o dispatcher compara o metric_value da primeira linha com 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" ou { "at_least": N }.
• conditions[]: cada { score_key, op, value }, usando os mesmos operadores dos outros gatilhos (>, >=, <, <=, ==).
• window_secs: o lookback compartilhado aplicado a cada condição (padrão 3600).
• min_count: número mínimo de avaliações por condição antes que ela possa ser violada; uma condição com amostras insuficientes na janela é contada como “não violada” (padrão 1).
• environment: opcional; restringe todas as condições a um único 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"
}

​

Lógica composta (M de N)

• eval_window: quantas avaliações recentes considerar (padrão 1)
• min_breaches: quantas delas precisam violar antes que o alerta dispare (padrão 1)

​

Intervalo de avaliação

​

Canais

​

E-mail

1. Substituição recipients[] por canal (quando não vazio).
2. A configuração alerts.email_default_recipients (um array de strings de e-mail).

​

Slack

• URL padrão: alerts.slack_default_webhook (definida em /settings).
• Substituição por alerta: defina o webhook_setting_key do canal para qualquer outra chave de configuração do tipo URL, ex: alerts.slack_oncall, alerts.slack_costs.

​

Webhook genérico

{
  "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": { … } }
}

​

No painel

​

Ciclo de vida do incidente

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

• firing — o dispatcher acabou de abrir o incidente ou detectou outra violação. A notificação de disparo é enviada exatamente uma vez (controlada pelo timestamp notified_firing_at no incidente).
• acknowledged — um operador pressionou ack em /incidents/:id. O incidente ainda é considerado aberto; violações subsequentes atualizarão suas evidências sem re-notificar.
• resolved — um operador pressionou resolve. A resolução automática quando a regra para de violar está planejada, mas ainda não está ativa, portanto um incidente aberto permanece aberto até que um operador o resolva.

​

Permissões necessárias

• alerts:read: visualizar regras de alerta.
• alerts:write: criar, editar, excluir regras de alerta e acionar uma notificação de teste.
• incidents:read: visualizar incidentes.
• incidents:write: abrir incidentes manuais (ad-hoc) que não estão vinculados a um alerta.
• incidents:ack: reconhecer, atribuir, comentar e resolver incidentes.

alerts:ack legado. Chaves e operadores que receberam o token alerts:ack antigo continuam funcionando: ele é aceito como incidents:ack (e implica incidents:read), para que os plantões existentes mantenham o acesso sem precisar reemitir credenciais. Emita novas concessões com a família incidents:*.

Seletor de destinatários de e-mail. O seletor de destinatários do editor de alertas lista os membros da sua organização para que você possa selecioná-los pelo nome. Ele carrega para qualquer operador que possua alerts:read ou alerts:write; visualizar o diretório da sua equipe para esse fim não requer users:read, e o seletor retorna apenas endereços de e-mail dos membros, nunca registros completos de usuário.

​

Configuração

• alerts.email_default_recipients (email_list): array JSON de strings de e-mail — os destinatários padrão para canais de e-mail.
• alerts.slack_default_webhook (url): URL padrão do webhook de entrada do Slack.
• alerts.webhook_default_url (url): URL padrão do webhook genérico.
• alerts.webhook_signing_secret (secret): chave HMAC-SHA256. Sempre retornada como "" na resposta GET; digite um novo valor para rotacionar.
• alerts.enabled_channels (channel_set): o conjunto global de tipos de canais externos que são despachados quando um alerta dispara; o padrão inclui todos os três (email, slack, webhook). Remover um tipo aqui suprime globalmente esse canal para todos os alertas sem editar cada regra. O canal no painel sempre é entregue e não é afetado por essa configuração.

​

Verificar um novo alerta

1. Salve-o como habilitado com pelo menos um canal de notificação.
2. Selecione test na página de detalhes do alerta e confirme que cada destino configurado recebe a notificação sintética.
3. Após a primeira violação real, confirme que o incidente aparece em Incidents e que o valor medido corresponde à query do painel correspondente.

​

Solução de problemas