Alertas

​

Conceptos

• Alerta — la regla. Define qué verificar (el disparador), con qué frecuencia (el intervalo de evaluación), cuándo considerarla rota (lógica compuesta), qué tan urgente es (severidad) y a quién/dónde notificar (canales).
• Incidente — lo que ocurre cuando una alerta se activa. Una alerta tiene como máximo un incidente abierto a la vez. Los incidentes repetidos actualizan la evidencia del mismo incidente. Los incidentes son resueltos por un operador; la resolución automática cuando la regla deja de activarse está planificada pero aún no está habilitada.
• Canal — hacia dónde va una notificación: correo electrónico, Slack, webhook genérico o en el panel. Cada alerta puede combinar cualquier combinación de estos.

​

Tipos de disparadores

​

1. metric_threshold

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

​

2. custom_sql

• modo rows (sin op/value): la alerta se activa en cuanto la consulta devuelve al menos una fila.
• modo value: la consulta debe tener un alias de columna llamado metric_value; el despachador compara el metric_value de la primera fila con 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[]: cada una como { score_key, op, value }, usando los mismos operadores que los demás disparadores (>, >=, <, <=, ==).
• window_secs: el período de retrospección compartido que se aplica a cada condición (por defecto 3600).
• min_count: número mínimo de evaluaciones por condición antes de que esa condición pueda superar el umbral; una condición con muy pocas muestras en la ventana se cuenta como “no superada” (por defecto 1).
• environment: opcional; restringe cada condición a un entorno.

​

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 compuesta (M de N)

• eval_window: cuántas evaluaciones recientes considerar (por defecto 1)
• min_breaches: cuántas de esas deben superar el umbral antes de que la alerta se active (por defecto 1)

​

Intervalo de evaluación

​

Canales

​

Correo electrónico

1. Anulación recipients[] por canal (cuando no está vacío).
2. La configuración alerts.email_default_recipients (un array de cadenas de correo).

​

Slack

• URL predeterminada: alerts.slack_default_webhook (configurada en /settings).
• Anulación por alerta: establece el webhook_setting_key del canal a cualquier otra clave de configuración de tipo URL, p. ej. 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": { … } }
}

​

En el panel

​

Ciclo de vida del incidente

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

• firing — el despachador acaba de abrir el incidente o detectó otro incumplimiento. La notificación de activación se envía exactamente una vez (controlada por la marca de tiempo notified_firing_at del incidente).
• acknowledged — un operador presionó ack en /incidents/:id. El incidente sigue considerándose abierto; los incumplimientos posteriores actualizarán su evidencia sin volver a notificar.
• resolved — un operador presionó resolve. La resolución automática cuando la regla deja de incumplir está planificada pero aún no está habilitada, por lo que un incidente abierto permanece abierto hasta que un operador lo resuelva.

​

Permisos requeridos

• alerts:read: ver reglas de alerta.
• alerts:write: crear, editar, eliminar reglas de alerta y disparar una notificación de prueba.
• incidents:read: ver incidentes.
• incidents:write: abrir incidentes manuales (ad-hoc) que no están vinculados a una alerta.
• incidents:ack: reconocer, asignar, comentar y resolver incidentes.

alerts:ack heredado. Las claves y operadores a los que se otorgó el token anterior alerts:ack siguen funcionando: se trata como incidents:ack (e implica incidents:read), por lo que los operadores de guardia existentes mantienen su acceso sin necesidad de reemitir credenciales. Emite nuevos permisos con la familia incidents:*.

Selector de destinatarios de correo. El selector de destinatarios del editor de alertas lista los miembros de tu organización para que puedas seleccionarlos por nombre. Se carga para cualquier operador que tenga alerts:read o alerts:write; ver el directorio de tu equipo para este fin no requiere users:read, y el selector devuelve únicamente las direcciones de correo de los miembros, nunca registros de usuario completos.

​

Configuración

• alerts.email_default_recipients (email_list): array JSON de cadenas de correo — los destinatarios predeterminados para los canales de correo.
• alerts.slack_default_webhook (url): URL de webhook entrante de Slack por defecto.
• alerts.webhook_default_url (url): URL de webhook genérico por defecto.
• alerts.webhook_signing_secret (secret): clave HMAC-SHA256. Siempre se devuelve como "" en la respuesta GET; escribe un nuevo valor para rotarla.
• alerts.enabled_channels (channel_set): el conjunto global de tipos de canales externos que se despachan cuando se activa una alerta; por defecto incluye los tres (email, slack, webhook). Eliminar un tipo aquí suprime globalmente ese canal para cada alerta sin editar cada regla. El canal en el panel siempre se entrega y no se ve afectado por esta configuración.

​

Verificar una nueva alerta

1. Guárdala como habilitada con al menos un canal de notificación.
2. Selecciona test en la página de detalle de la alerta y confirma que cada destino configurado recibe la notificación sintética.
3. Tras el primer incumplimiento real, confirma que el incidente aparece en Incidents y que el valor medido coincide con la consulta correspondiente en el panel.

​

Solución de problemas