Alerts

​

Konzepte

• Alert — die Regel. Sie legt fest, was geprüft wird (der Trigger), wie oft (das Auswertungsintervall), wann ein Verstoß vorliegt (Verbundlogik), wie dringend (Schweregrad) und wer/wohin benachrichtigt wird (Kanäle).
• Incident — das Ereignis, das ausgelöst wird, wenn ein Alert feuert. Ein Alert hat maximal einen offenen Incident gleichzeitig. Wiederholte Verstöße aktualisieren die Belege desselben Incidents. Incidents werden von einem Operator aufgelöst; eine automatische Auflösung, wenn die Regel nicht mehr feuert, ist geplant, aber derzeit nicht aktiviert.
• Channel — wohin eine Benachrichtigung gesendet wird: E-Mail, Slack, generischer Webhook oder im Dashboard. Jeder Alert kann eine beliebige Kombination davon verwenden.

​

Trigger-Typen

​

1. metric_threshold

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

​

2. custom_sql

• Zeilenmodus (kein op/value): Der Alert feuert, sobald die Abfrage mindestens eine Zeile zurückgibt.
• Wertmodus: Die Abfrage muss eine Spalte als metric_value aliasieren; der Dispatcher vergleicht den metric_value der ersten Zeile mit value unter Verwendung von 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" oder { "at_least": N }.
• conditions[]: jeweils { score_key, op, value }, mit denselben Operatoren wie die anderen Trigger (>, >=, <, <=, ==).
• window_secs: der gemeinsame Rückblickzeitraum, der auf jede Bedingung angewandt wird (Standard: 3600).
• min_count: Mindestanzahl von Evaluierungen pro Bedingung, bevor diese Bedingung als verletzt gelten kann; eine Bedingung mit zu wenigen Stichproben im Fenster gilt als „nicht verletzt” (Standard: 1).
• environment: optional; schränkt jede Bedingung auf eine Umgebung ein.

​

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"
}

​

Verbundlogik (M von N)

• eval_window: wie viele der letzten Auswertungen betrachtet werden (Standard: 1)
• min_breaches: wie viele davon verletzt sein müssen, bevor der Alert feuert (Standard: 1)

​

Auswertungsintervall

​

Kanäle

​

E-Mail

1. Per-Kanal-Überschreibung recipients[] (wenn nicht leer).
2. Die Einstellung alerts.email_default_recipients (ein Array von E-Mail-Strings).

​

Slack

• Standard-URL: alerts.slack_default_webhook (in /settings gesetzt).
• Per-Alert-Überschreibung: Setzen Sie webhook_setting_key des Kanals auf einen anderen URL-typisierten Einstellungsschlüssel, z. B. alerts.slack_oncall, alerts.slack_costs.

​

Generischer Webhook

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

​

Im Dashboard

​

Incident-Lebenszyklus

firing  ──ack──▶  acknowledged
   │                    │
   └────────────────────┴───── Operator auflösen ───▶  resolved

• firing — der Dispatcher hat gerade den Incident eröffnet oder einen weiteren Verstoß erkannt. Die Firing-Benachrichtigung wird genau einmal ausgesendet (gesteuert durch den notified_firing_at-Zeitstempel am Incident).
• acknowledged — ein Operator hat Ack auf /incidents/:id gedrückt. Der Incident gilt noch als offen; nachfolgende Verstöße aktualisieren seine Belege, ohne erneut zu benachrichtigen.
• resolved — ein Operator hat Auflösen gedrückt. Die automatische Auflösung, wenn die Regel nicht mehr verletzt wird, ist geplant, aber derzeit nicht aktiviert; ein offener Incident bleibt offen, bis ein Operator ihn auflöst.

​

Erforderliche Berechtigungen

• alerts:read: Alert-Regeln anzeigen.
• alerts:write: Alert-Regeln erstellen, bearbeiten, löschen und eine Test-Benachrichtigung auslösen.
• incidents:read: Incidents anzeigen.
• incidents:write: Manuelle (Ad-hoc-)Incidents öffnen, die nicht an einen Alert gebunden sind.
• incidents:ack: Incidents bestätigen, zuweisen, kommentieren und auflösen.

Legacy alerts:ack. Schlüssel und Operatoren, denen das ältere alerts:ack-Token gewährt wurde, funktionieren weiterhin: Es wird als incidents:ack anerkannt (und impliziert incidents:read), sodass bestehende Bereitschaftsdienst-Mitglieder ihren Zugriff behalten, ohne Zugangsdaten neu auszustellen. Neue Berechtigungen sollten mit der incidents:*-Familie erteilt werden.

E-Mail-Empfänger-Auswahl. Die Empfängerauswahl im Alert-Editor listet die Mitglieder Ihrer Organisation auf, sodass Sie sie nach Namen auswählen können. Sie lädt für jeden Operator mit alerts:read oder alerts:write; die Anzeige des Team-Verzeichnisses zu diesem Zweck erfordert nicht users:read, und die Auswahl gibt nur E-Mail-Adressen der Mitglieder zurück, niemals vollständige Benutzerdatensätze.

​

Konfiguration

• alerts.email_default_recipients (email_list): JSON-Array von E-Mail-Strings — die Standard-Empfänger für E-Mail-Kanäle.
• alerts.slack_default_webhook (url): Standard-Slack-Incoming-Webhook-URL.
• alerts.webhook_default_url (url): Standard-URL für generische Webhooks.
• alerts.webhook_signing_secret (secret): HMAC-SHA256-Schlüssel. Wird in der GET-Antwort immer als "" zurückgegeben; geben Sie einen neuen Wert ein, um ihn zu rotieren.
• alerts.enabled_channels (channel_set): Die organisationsweite Menge externer Kanalarten, die beim Feuern eines Alerts ausgelöst werden; standardmäßig alle drei (email, slack, webhook). Wird eine Art hier entfernt, wird dieser Kanal für jeden Alert global unterdrückt, ohne dass jede Regel bearbeitet werden muss. Der In-Dashboard-Kanal wird immer zugestellt und ist von dieser Einstellung nicht betroffen.

​

Neuen Alert verifizieren

1. Speichern Sie ihn als aktiviert mit mindestens einem Benachrichtigungskanal.
2. Wählen Sie Test auf der Alert-Detailseite und bestätigen Sie, dass jedes konfigurierte Ziel die synthetische Benachrichtigung erhält.
3. Bestätigen Sie nach dem ersten echten Verstoß, dass der Incident unter Incidents erscheint und der gemessene Wert mit der entsprechenden Dashboard-Abfrage übereinstimmt.

​

Fehlerbehebung