Alerts

​

title: “Cảnh báo” description: “Tài liệu về Cảnh báo AgentEye.”

​

Khái niệm

• Cảnh báo — quy tắc. Nó nói cái gì để kiểm tra (kích hoạt), tần suất (khoảng đánh giá), khi nào coi là bị hỏng (logic phức hợp), mức độ khẩn cấp (mức độ nghiêm trọng), và ai/nơi để thông báo (kênh).
• Sự cố — những gì xảy ra khi cảnh báo phát động. Một cảnh báo có tối đa một sự cố mở tại một thời điểm. Những lần vi phạm lặp lại cập nhật bằng chứng của cùng một sự cố. Sự cố được giải quyết bởi một điều hành viên; giải quyết tự động khi quy tắc dừng phát động được lên kế hoạch nhưng hiện không được bật.
• Kênh — nơi thông báo đi: email, Slack, webhook chung, hoặc trong bảng điều khiển. Mỗi cảnh báo có thể đính kèm bất kỳ sự kết hợp nào.

​

Các loại kích hoạt

​

1. metric_threshold

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

​

2. custom_sql

• chế độ hàng (không có op/value): cảnh báo phát động ngay khi truy vấn trả về ít nhất một hàng.
• chế độ giá trị: truy vấn phải có bí danh một cột là metric_value; dispatcher so sánh metric_value của hàng đầu tiên với value sử dụng 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", hoặc { "at_least": N }.
• conditions[]: mỗi { score_key, op, value }, sử dụng cùng các toán tử như các kích hoạt khác (>, >=, <, <=, ==).
• window_secs: lookback được chia sẻ áp dụng cho mọi điều kiện (mặc định 3600).
• min_count: số lượng đánh giá tối thiểu trên mỗi điều kiện trước khi điều kiện đó có thể vi phạm; một điều kiện có quá ít mẫu trong cửa sổ được tính là “không vi phạm” (mặc định 1).
• environment: tùy chọn; hạn chế mọi điều kiện chỉ trong một môi trường.

​

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

​

Logic phức hợp (M of N)

• eval_window: có bao nhiêu đánh giá gần đây để xem (mặc định 1)
• min_breaches: có bao nhiêu trong số đó phải vi phạm trước khi cảnh báo phát động (mặc định 1)

​

Khoảng đánh giá

​

Kênh

​

Email

1. Ghi đè recipients[] theo kênh (khi không trống).
2. Cài đặt alerts.email_default_recipients (một mảng các chuỗi email).

​

Slack

• URL mặc định: alerts.slack_default_webhook (được đặt trong /settings).
• Ghi đè cho mỗi cảnh báo: đặt webhook_setting_key của kênh thành bất kỳ khóa cài đặt kiểu URL nào khác, ví dụ: alerts.slack_oncall, alerts.slack_costs.

​

Webhook chung

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

​

Trong bảng điều khiển

​

Vòng đời sự cố

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

• firing — dispatcher vừa mở sự cố hoặc phát hiện một vi phạm khác. Thông báo phát động được quạt ra chính xác một lần (được gated bởi dấu thời gian notified_firing_at trên sự cố).
• acknowledged — một điều hành viên nhấn ack trên /incidents/:id. Sự cố vẫn được coi là mở; các vi phạm tiếp theo sẽ cập nhật bằng chứng của nó mà không thông báo lại.
• resolved — một điều hành viên nhấn resolve. Giải quyết tự động khi quy tắc dừng phạm được lên kế hoạch nhưng hiện không được bật, vì vậy một sự cố mở vẫn mở cho đến khi một điều hành viên giải quyết nó.

​

Quyền bắt buộc

• alerts:read: xem các quy tắc cảnh báo.
• alerts:write: tạo, chỉnh sửa, xóa các quy tắc cảnh báo, và kích hoạt thông báo kiểm tra.
• incidents:read: xem sự cố.
• incidents:write: mở các sự cố thủ công (ad-hoc) không gắn liền với cảnh báo.
• incidents:ack: ack, gán, bình luận, và giải quyết sự cố.

Legacy alerts:ack. Các khóa và điều hành viên được cấp mã thông báo alerts:ack cũ hơn tiếp tục hoạt động: nó được chấp nhận là incidents:ack (và ngụ ý incidents:read), vì vậy các on-caller hiện tại giữ quyền truy cập của họ mà không cấp lại thông tin xác thực. Phát hành các khoản cấp mới với gia đình incidents:*.

Bộ chọn người nhận email. Bộ chọn người nhận của trình chỉnh sửa cảnh báo liệt kê các thành viên của tổ chức của bạn để bạn có thể chọn họ theo tên. Nó tải cho bất kỳ điều hành viên nào giữ alerts:read hoặc alerts:write; xem danh mục của nhóm của bạn cho mục đích này không yêu cầu users:read, và bộ chọn chỉ trả về địa chỉ email thành viên, không bao giờ toàn bộ hồ sơ người dùng.

​

Cấu hình

• alerts.email_default_recipients (email_list): mảng JSON của các chuỗi email — người nhận mặc định cho kênh email.
• alerts.slack_default_webhook (url): URL webhook đến Slack mặc định.
• alerts.webhook_default_url (url): URL webhook chung mặc định.
• alerts.webhook_signing_secret (secret): khóa HMAC-SHA256. Luôn được trả về dưới dạng "" trong phản hồi GET; gõ giá trị mới để xoay.
• alerts.enabled_channels (channel_set): bộ toàn org của các loại kênh bên ngoài được gửi khi cảnh báo phát động; mặc định tất cả ba (email, slack, webhook). Loại bỏ một loại ở đây sẽ loại bỏ kênh đó toàn cầu cho mọi cảnh báo mà không chỉnh sửa từng quy tắc. Kênh trong bảng điều khiển luôn được gửi và không bị ảnh hưởng bởi cài đặt này.

​

Xác minh cảnh báo mới

1. Lưu nó dưới dạng bật với ít nhất một kênh thông báo.
2. Chọn test trên trang chi tiết cảnh báo và xác nhận mỗi điểm đến được cấu hình nhận thông báo tổng hợp.
3. Sau lần vi phạm thực tế đầu tiên, xác nhận sự cố xuất hiện dưới Sự cố và giá trị đo được của nó phù hợp với truy vấn bảng điều khiển tương ứng.

​

Khắc phục sự cố