التنبيهات

​

المفاهيم

• التنبيه — القاعدة. تحدد ماذا يتحقق (المحفز)، كم مرة (فترة التقييم)، متى تُعتبر معطلة (منطق مركب)، مدى الاستعجالية (الخطورة)، ومن/أين يتم الإخطار (القنوات).
• الحادثة — ما يحدث عند تفعيل التنبيه. لكل تنبيه حادثة مفتوحة واحدة على الأكثر في المرة الواحدة. التخطيات المتكررة تحدّث أدلة الحادثة نفسها. يتم حل الحوادث بواسطة المشغّل؛ الحل التلقائي عند توقف القاعدة عن التفعيل مخطط له لكنه غير مفعل حالياً.
• القناة — حيث يذهب الإخطار: البريد الإلكتروني أو Slack أو webhook عام أو لوحة التحكم. كل تنبيه يمكن أن يرفق أي مجموعة.

​

أنواع المحفزات

​

1. metric_threshold

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

​

2. custom_sql

• وضع الصفوف (بدون op/value): ينشّط التنبيه بمجرد أن تعود الاستعلام صفاً واحداً على الأقل.
• وضع القيمة: يجب أن تسمي الاستعلام عموداً واحداً بـ metric_value؛ يقارن المُرسِل metric_value في الصف الأول مقابل value باستخدام 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", أو { "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 من N)

• eval_window: عدد التقييمات الأخيرة التي يتم النظر إليها (افتراضي 1)
• min_breaches: كم عدد هذه التي يجب أن تخفق قبل ينشّط التنبيه (افتراضي 1)

​

فترة التقييم

​

القنوات

​

البريد الإلكتروني

1. تجاوز recipients[] لكل قناة (عندما غير فارغة).
2. إعداد alerts.email_default_recipients (مصفوفة من سلاسل البريد الإلكتروني).

​

Slack

• رابط افتراضي: alerts.slack_default_webhook (يُعين في /settings).
• تجاوز لكل تنبيه: اضبط webhook_setting_key للقناة إلى أي مفتاح إعداد من نوع رابط آخر، مثل alerts.slack_oncall, alerts.slack_costs.

​

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

​

لوحة التحكم

​

دورة حياة الحادثة

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

• firing — فتح المُرسِل للتو الحادثة أو كشف إخفاق آخر. يُروّج إخطار الإطلاق بالضبط مرة واحدة (محكوم بطابع زمني notified_firing_at على الحادثة).
• acknowledged — ضغط المشغّل على ack في /incidents/:id. الحادثة لا تزال تُعتبر مفتوحة؛ الإخفاقات اللاحقة ستحدّث أدلتها بدون إخطار مجدد.
• resolved — ضغط المشغّل على resolve. الحل التلقائي عند توقف القاعدة عن الإخفاق مخطط له لكنه غير مفعل حالياً، لذا حادثة مفتوحة تبقى مفتوحة حتى يحلها المشغّل.

​

الأذونات المطلوبة

• alerts:read: اعرض قواعد التنبيهات.
• alerts:write: أنشئ أو حرّر أو احذف قواعد التنبيهات وشغّل إخطار اختبار.
• incidents:read: اعرض الحوادث.
• incidents:write: افتح حوادث يدوية (مجانية) غير مرتبطة بتنبيه.
• incidents:ack: اعترف بـ الحوادث وعيّنها وعلّق عليها وحلها.

alerts:ack القديم. المفاتيح والمشغّلون الذين مُنحوا رمز alerts:ack الأقدم يستمران في العمل: يُشرّفه كـ incidents:ack (ويضمن incidents:read)، لذا المشغّلون في الخدمة الحالية يحتفظون بوصولهم بدون إعادة إصدار أوراق اعتماد. أصدر منح جديد بعائلة incidents:*.

منتقي المستقبل للبريد الإلكتروني. يسرد منتقي المستقبل في محرر التنبيهات أعضاء مؤسستك حتى تختار بالاسم. يُحمّل لأي مشغّل يحمل alerts:read أو alerts:write؛ عرض دليل فريقك لهذا الغرض لا يتطلب users:read، والمنتقي يعيد فقط عناوين بريد الأعضاء ليس سجلات المستخدمين الكاملة.

​

التكوين

• alerts.email_default_recipients (email_list): مصفوفة JSON من سلاسل البريد الإلكتروني — المستقبلات الافتراضية لقنوات البريد.
• alerts.slack_default_webhook (url): رابط Slack webhook الوارد الافتراضي.
• alerts.webhook_default_url (url): رابط webhook عام افتراضي.
• alerts.webhook_signing_secret (secret): مفتاح HMAC-SHA256. يُعاد دائماً كـ "" في استجابة GET؛ اكتب قيمة جديدة للتدوير.
• alerts.enabled_channels (channel_set): مجموعة أنواع القنوات الخارجية على مستوى المنظمة التي يتم توصيلها عند تفعيل تنبيه؛ الافتراضي كل ثلاثة (email, slack, webhook). إزالة نوع هنا توقف عام هذه القناة لكل تنبيه بدون تحرير كل قاعدة. قناة لوحة التحكم تُسلّم دائماً وغير متأثرة بهذا الإعداد.

​

تحقق من تنبيه جديد

1. احفظه مفعلاً بقناة إخطار واحد على الأقل.
2. اختر test في صفحة تفاصيل التنبيه وأكد أن كل وجهة مُكوّنة تتلقى الإخطار الاصطناعي.
3. بعد أول إخفاق حقيقي، أكد أن الحادثة تظهر تحت الحوادث وقيمتها المقاسة تطابق استعلام لوحة التحكم المطابق.

​

استكشاف الأخطاء