Alerts

​

개념

• Alert — 규칙입니다. 무엇을 확인할지(트리거), 얼마나 자주(평가 주기), 언제 문제로 볼지(복합 로직), 얼마나 긴급한지(심각도), 누구에게/어디로 알릴지(채널)를 정의합니다.
• Incident — Alert가 발동될 때 생성됩니다. 하나의 Alert에는 동시에 열린 인시던트가 최대 하나만 존재합니다. 반복적인 위반은 동일 인시던트의 근거 데이터를 업데이트합니다. 인시던트는 운영자가 직접 해결해야 하며, 규칙이 발동을 멈출 때 자동 해결하는 기능은 계획 중이나 현재는 미지원입니다.
• Channel — 알림이 전달되는 대상: 이메일, Slack, 일반 웹훅, 또는 대시보드 내. 각 Alert에 원하는 조합을 붙일 수 있습니다.

​

트리거 유형

​

1. metric_threshold

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

​

2. custom_sql

• rows 모드 (op/value 없음): 쿼리가 하나 이상의 행을 반환하는 즉시 Alert가 발동됩니다.
• value 모드: 쿼리에서 컬럼 하나를 metric_value로 별칭 지정해야 하며, 디스패처는 첫 번째 행의 metric_value를 op를 사용해 value와 비교합니다.

{
  "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", 또는 { "at_least": N }.
• conditions[]: 각각 { score_key, op, value } 형태이며, 다른 트리거와 동일한 연산자(>, >=, <, <=, ==)를 사용합니다.
• window_secs: 모든 조건에 공통으로 적용되는 기간(기본값 3600).
• min_count: 조건이 위반으로 판정되기 전 필요한 최소 평가 횟수. 윈도우 내 샘플이 부족한 조건은 “위반 없음”으로 처리됩니다(기본값 1).
• environment: 선택 사항. 모든 조건을 특정 환경으로 제한합니다.

​

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

​

복합 로직 (M of N)

• eval_window: 살펴볼 최근 평가 횟수 (기본값 1)
• min_breaches: 그 중 Alert가 발동되기 위해 위반되어야 하는 횟수 (기본값 1)

​

평가 주기

​

채널

​

이메일

1. 채널별 recipients[] 재정의(비어 있지 않은 경우).
2. alerts.email_default_recipients 설정(이메일 문자열 배열).

​

Slack

• 기본 URL: alerts.slack_default_webhook (/settings에서 설정).
• Alert별 재정의: 채널의 webhook_setting_key를 다른 URL 유형 설정 키(예: alerts.slack_oncall, alerts.slack_costs)로 지정합니다.

​

일반 웹훅

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

​

대시보드 내

​

인시던트 생명주기

firing  ──ack──▶  acknowledged
   │                    │
   └────────────────────┴───── 운영자 해결 ───▶  resolved

• firing — 디스패처가 방금 인시던트를 열었거나 또 다른 위반을 감지했습니다. 발동 알림은 정확히 한 번만 전송됩니다(인시던트의 notified_firing_at 타임스탬프로 게이팅).
• acknowledged — 운영자가 /incidents/:id에서 ack를 눌렀습니다. 인시던트는 여전히 열린 상태로 간주되며, 이후 위반은 재알림 없이 근거 데이터를 업데이트합니다.
• resolved — 운영자가 resolve를 눌렀습니다. 규칙 위반이 멈출 때 자동 해결하는 기능은 계획 중이나 현재는 미지원이므로, 열린 인시던트는 운영자가 해결할 때까지 유지됩니다.

​

필요 권한

• alerts:read: Alert 규칙 보기.
• alerts:write: Alert 규칙 생성, 편집, 삭제 및 테스트 알림 트리거.
• incidents:read: 인시던트 보기.
• incidents:write: Alert와 연결되지 않은 수동(임시) 인시던트 열기.
• incidents:ack: 인시던트 확인, 배정, 댓글 작성, 해결.

레거시 alerts:ack. 이전 alerts:ack 토큰을 부여받은 키와 운영자는 계속 사용 가능합니다. incidents:ack로 인정되며(incidents:read 포함), 기존 온콜 담당자는 자격 증명을 재발급하지 않아도 접근 권한을 유지합니다. 새 권한은 incidents:* 계열로 발급하세요.

이메일 수신자 선택기. Alert 편집기의 수신자 선택기는 이름으로 선택할 수 있도록 조직 구성원 목록을 표시합니다. alerts:read 또는 alerts:write 권한을 가진 운영자라면 로드되며, 이 목적으로 팀 디렉터리를 보는 데는 users:read가 필요하지 않습니다. 선택기는 구성원 이메일 주소만 반환하며, 전체 사용자 레코드는 반환하지 않습니다.

​

구성

• alerts.email_default_recipients (email_list): 이메일 채널의 기본 수신자를 담은 이메일 문자열 JSON 배열.
• alerts.slack_default_webhook (url): 기본 Slack 수신 웹훅 URL.
• alerts.webhook_default_url (url): 기본 일반 웹훅 URL.
• alerts.webhook_signing_secret (secret): HMAC-SHA256 키. GET 응답에서는 항상 ""로 반환되며, 새 값을 입력하면 교체됩니다.
• alerts.enabled_channels (channel_set): Alert 발동 시 디스패치되는 외부 채널 종류의 조직 전체 설정. 기본값은 세 가지 모두(email, slack, webhook). 여기서 채널 종류를 제거하면 각 규칙을 편집하지 않아도 모든 Alert에서 해당 채널이 전역으로 억제됩니다. 대시보드 내 채널은 항상 전달되며 이 설정의 영향을 받지 않습니다.

​

새 Alert 검증

1. 최소 하나의 알림 채널을 붙여 활성화된 상태로 저장합니다.
2. Alert 상세 페이지에서 test를 선택하고 설정된 각 대상이 테스트 알림을 수신하는지 확인합니다.
3. 실제 첫 번째 위반 후, Incidents 아래에 인시던트가 나타나고 측정값이 해당 대시보드 쿼리와 일치하는지 확인합니다.

​

문제 해결