> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # התראות > תיעוד התראות AgentEye. התראות מערכות כלל על לוח זמנים ומודיעות לך כאשר משהו חוצה סף. הן הופכות את AgentEye מלוח מחוונים פסיבי למשטח דירוג לדברים החשובים: עליות בשיעור שגיאות, רגרסיות בזמן תגובה, ירידות בציוני מעריך, או כל אירוע מותאם שאתה יכול להביע כשאילתה ClickHouse. מדריך זה מכסה מה זו התראה, חמישת סוגי ההדלקה, ארבע ערוצי ההודעות, מחזור החיים של התקרית, וחוגי הפעולה. דף התראות: רשת של כרטיסי כללי התראות, כל אחד מציג את סוג ההדלקה שלו, חלון הערכה, ערוצים, ותג חומרת חומרה/אזהרה/קריטית *** ## מושגים * **התראה** — הכלל. הוא אומר *מה* לבדוק (ההדלקה), *כמה לעתים קרובות* (מרווח ההערכה), *מתי להתייחס אליו כשבור* (לוגיקה מרוכבת), *כמה דחוף* (חומרה), ו*מי/איפה להודיע* (ערוצים). * **תקרית** — מה קורה כאשר התראה משתלחת. התראה אחת יכולה להיות בעלת תקרית פתוחה אחת בלבד בכל פעם. הפרות חוזרות מעדכנות את ראיות אותה תקרית. תקריות נפתרות על ידי מפעיל; רזולוציה אוטומטית כאשר הכלל מפסיק לשלוח אותות מתוכננת אך לא מופעלת כרגע. * **ערוץ** — היכן הודעה מגיעה: דוא"ל, Slack, webhook כללי, או בתוך הלוח. כל התראה יכולה לצרף כל שילוב. התראות ותקריות שייכות לארגון ומשותפות בין מפעילי הארגון הזה (בפריסה חד-שוכנית זה פשוט הארגון המובנה `default`). ניתן להקצות תקריות למפעיל בודד לבדיקה. *** ## סוגי הדלקה חמישה סוגים, כל אחד עם תו JSON משלו. בחר את זה שמתאים לדרך שבה אתה רוצה לתאר "שבור". טופס **התראה חדשה** של הלוח משנה את אותו תו עבורך, ומעביר את עורך התנאי כדי להתאים לסוג ההדלקה שבחרת: טופס התראה חדשה, עם היסודות (שם, תיאור, מופעל) ובורר ההדלקה המציג סף מטרי, SQL מותאם, ניקוד הערכה, כשלים בהערכה, ואפשרויות לכל אירוע ### 1. `metric_threshold` הפשוט ביותר. בחר מטרי מרשימה סגורה, מפעיל, סף, וחלון זמן. | מטרי | מה זה סופר | | ---------------- | ----------------------------------------------------------------- | | `event_count` | סך הכל אירועים בחלון | | `error_count` | `event_type = 'error'` או כל אירוע עם `error_type IS NOT NULL` | | `error_rate` | `error_count / event_count` (0..1) | | `p95_latency_ms` | `quantile(0.95)(duration_ms)` על פני כל האירועים עם `duration_ms` | | `p99_latency_ms` | `quantile(0.99)(duration_ms)` | | `token_sum` | `SUM(input_tokens + output_tokens)` | מפעילים: `>`, `>=`, `<`, `<=`, `==` (גם מקובל כ-`gt`, `gte`, `lt`, `lte`, `eq`). מסננים אופציונליים: `environment`, `event_type`. דוגמה למפרט: ```json theme={null} { "metric": "p95_latency_ms", "filter": { "environment": "production" }, "window_secs": 900, "op": ">", "value": 5000 } ``` ### 2. `custom_sql` לכל דבר שהמטריקות הקבועות מראש לא מכסות. ה-SQL שמסר המפעיל עובר דרך אותו שומר `/queries/run` (SELECT/WITH בלבד, הצהרה יחידה, תקרת שורות 10,000) לפני שהמשלח מריץ אותה. שני מצבים: * **מצב שורות** (ללא `op`/`value`): ההתראה משתלחת ברגע שהשאילתה מחזירה לפחות שורה אחת. * **מצב ערך**: השאילתה חייבת לכנות עמודה אחת כ-`metric_value`; המשלח משווה את ה-`metric_value` של השורה הראשונה מול `value` באמצעות `op`. ```json theme={null} { "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` קורא מ-`agenteye.evaluations` ומשווה את הממוצע של ציון בשם על פני חלון. ```json theme={null} { "score_key": "hallucination", "op": ">", "value": 0.6, "window_secs": 3600, "min_count": 5, "environment": "production" } ``` `min_count` מגן מפני חריגי מדגם יחיד; המשלח לא ישלח עד שלפחות N הערכות קיימות בחלון. ### 4. `eval_compound` תופסת רגרסיה בחומר שמופיעה רק על פני *מספר* ציוני מעריך בו-זמנית. כאשר `evaluation_score` עוקבת אחר ציון בשם יחיד, `eval_compound` מרכיבה מספר תנאי ציוני הערכה לתראה אחת ומשלבת את התוצאות שלהן עם לוגיקה שנבחרה; אז כלל אחד יכול להביע "שלח אם עזרתיות ירידה **או** הזיות עולות", "שלח רק אם עזרתיות **ו** יעילות כלים שתיהן ירידות", או "שלח אם **לפחות 2 מ** שלוש הבדיקות הללו הפרו". כל תנאי קורא את הממוצע של ציון בשם אחד מ-`agenteye.evaluations` על פני החלון המשותף ובוחן אותו עם מפעיל וסף משלו. התוצאות הבוליאניות משולבות לאחר מכן על ידי `combinator`: | משלב | לוגיקה | משלח כאשר | | ------------------- | ------ | ------------------- | | `"any"` | OR | לפחות תנאי אחד הופר | | `"all"` | AND | כל תנאי הופר | | `{ "at_least": N }` | M-of-N | לפחות N תנאים הופרו | ```json theme={null} { "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` לכל התראות "כל אירוע התואם X נחת". ללא צבירה; המשלח משלח ברגע שהוא רואה התאמה בחלון ההחזר אחורה. ```json theme={null} { "event_type": "error", "lookback_secs": 60, "environment": "production", "tool_name": "bash", "agent_id": "caa", "error_type": "TimeoutError", "message_contains": "vertex-ai timed out" } ``` כל המסננים משולבים עם AND; כל שדה שתשאיר אינו מוגבל. | שדה | מטרה | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent_id` | הגבל לשגיאות מסוכן ספציפי (האחד המוצג בשורת `/errors`). | | `error_type` | הגבל למחלקת שגיאה ספציפית (למשל `TimeoutError`) ולא לכל שגיאה. | | `message_contains` | התאמת מחרוזת משנה לא תלויה בגודל אותיות מול `payload.message`. שימושי לתפיסת אופן כשל ספציפי אחד (למשל `prompt is too long`) ללא התראה על כל שגיאה מהסוכן זה. מוגבל ל-200 תווים; התאם כמחרוזת מילולית, לא כדפוס. | טיפ: קבע את `lookback_secs` ערך בערך להתאמת `eval_interval_secs` של ההתראה כך שלא תקבל הודעה כפולה על אותו אירוע. **קיצור מ-`/errors`:** לכל קבוצת שגיאה שורה כונית בתצוגת השגיאות (וחלונת פרטי אירוע הסעת לאירוע שגיאה) יש כפתור **+ התראה** שפותח את `/alerts/new` מלא מראש עם ההדלקה `per_event` מחובר לאותו שורה של `event_type` + סביבה, כולל שם שזוריע מ-`error_type` של הטעון כאשר קיים. אתה עדיין בוחר ערוצים ומאשר את ההחזר אחורה, אבל התאמה היא מלאה עבורך. מפעילים צריכים `alerts:write` כדי שהכפתור יופיע. *** ## לוגיקה מרוכבת (M of N) לכל התראה יש שני כפתורים שלמים בנוסף להדלקה: * `eval_window`: כמה הערכות אחרונות להסתכל על (ברירת מחדל 1) * `min_breaches`: כמה מהן חייבות להיות הפרה לפני שההתראה משתלחת (ברירת מחדל 1) `1 of 1` (ברירת המחדל) הוא "שלח בהפרה הראשונה". `3 of 5` אומר "שלח כאשר הכלל הופר 3 מ-5 ההערכות האחרונות", שימושי לאותות רועדים כאשר מדידה רעה אחת היא רעש. המשלח מתחזק חיץ טבעת לכל התראה; אתה לא צריך לנהל מדינה. *** ## מרווח הערכה `eval_interval_secs` שולט כמה לעתים קרובות המשלח מריץ את הכלל שלך. מוגבל ל-`[30, 86400]`. קבועות בלוח: 1m / 5m / 15m / 1h. בחר מרווח תואם לאופן תנועת האות הבסיסי: התראת שיעור שגיאה של 5 דקות המוערכת כל 15 שניות בזבוזי CPU; התראה לכל אירוע צריכה החזר אחורה קצר או היא תשמיט בשקט אירועים בין קללות. *** ## ערוצים כל התראה יכולה לצרף כל שילוב מאלה הארבע. פרטי עדכון לערוץ (Slack webhook URL, generic webhook URL + חתימת סודי, נמענים דוא"ל ברירת מחדל) מוגדרים פעם אחת בַ\*\*`/settings`\*\* והנקובים לפי מפתח מכל התראה. בדרך זו ערוץ Slack אחד יכול לשרת התראות רבות ללא כל אחד לאחסן את העתק משלו של ה-webhook URL. שלושת סוגי הערוץ החיצוני (דוא"ל, Slack, webhook) גם מהודקים על ידי כיבוי ארגוני רחב-חלל, `alerts.enabled_channels`. כאשר התראה משתלחת מצרפת סוג ערוץ שאינו בקבוצה זו, המשלח מדלג עליה ורושם שורת `alert_notifications` עם סטטוס `skipped_disabled` ויעד `` (שיכול לעזור לך לעצור בכללי, נגיד, את כל משלוח Slack ללא עריכת כל כלל). ערוץ בתוך הלוח תמיד מותר. ראה [תצורה](#configuration). ### דוא"ל משתמש בשפל SMTP זהה שחומק אימיילי התחברות OTP. נמענים פותרים בסדר: 1. החזקה ערוץ-ספציפית `recipients[]` (כאשר לא ריק). 2. הגדרת `alerts.email_default_recipients` (מערך של מחרוזות דוא"ל). אם SMTP אינו מוגדר הערוץ הוא no-op; המשלח עדיין רושם שורת `alert_notifications` עם יעד `` כך ששביל הביקורת הופך את ההשגחה גלויה. ### Slack שולח הודעת Block Kit ל-[Incoming webhook URL](https://api.slack.com/messaging/webhooks). * URL ברירת מחדל: `alerts.slack_default_webhook` (קבע בַ`/settings`). * עקיפה לכל התראה: קבע את `webhook_setting_key` של הערוץ לכל מפתח הגדרה מסוג URL אחר, למשל `alerts.slack_oncall`, `alerts.slack_costs`. ראש כלול אימוג'י חומרה (`:rotating_light:` / `:warning:` / `:bell:`), והודעה נושאת כפתור שחובר עמוק לדף התקרית. ### Webhook כללי אינטגרציה JSON-POST לכן PagerDuty, Opsgenie, או נקודת קבלה משלך. צורת הגוף: ```json theme={null} { "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": { … } } } ``` כאשר `alerts.webhook_signing_secret` מוקבע, הבקשה כוללת כותרת `X-AgentEye-Signature: sha256=`, ה-HMAC-SHA256 של הגוף באמצעות הסוד. אמת אותה בצד המקבל לפני הסמכת הטעון. ראש `X-AgentEye-Event` נושא `alert.firing` / `alert.test`. (`alert.resolved` שמור לתכונת ההסדר האוטומטי המתוכננת ואינו נפלט כרגע.) ### בתוך הלוח ללא משלוח חיצוני: ההתראה פשוט כותבת שורת `alert_notifications` שדף התקריות של הלוח משטח. שימושי בזמן כיוונון כלל ולא רוצה לספאם מערכת חיצונית, או לתראות נמוכות-דחיפות שמפעילים בודקים במהלך בדיקה רגילה. *** ## מחזור חיים של תקרית ``` firing ──ack──▶ acknowledged │ │ └────────────────────┴───── operator resolve ───▶ resolved ``` * **משדר** — המשלח פשוט פתח את התקרית או גילה הפרה נוספת. הודעת הדלקה היא מחוברת בדיוק פעם אחת (מהודקת על ידי חותמת הזמן `notified_firing_at` על התקרית). * **מודה** — מפעיל לחץ על *ack* בַ`/incidents/:id`. התקרית עדיין נחשבת פתוחה; הפרות עתידיות יעדכנו את ראיות שלה ללא הודעה חוזרת. * **פתור** — מפעיל לחץ על *resolve*. רזולוציה אוטומטית כאשר הכלל מפסיק לשלוח אותות מתוכננת אך לא מופעלת כרגע, כך שתקרית פתוחה נשארת פתוחה עד שמפעיל פותר אותה. תקרית חדשה יכולה להפתח מחדש על אותה התראה בכל נקודה לאחר רזולוציה של קודמתה. **ציר זמן פעילות.** כל פעולה על תקרית — נפתחה, הודתה, פתורה — מתועדה בעיתון פעילות המצטבר בלבד ומופיעה בציר הזמן *פעילות* של התקרית, כל כניסה המיוחסת למפעיל שביצע אותה (לפי דוא"ל) או **automated** לפעולות המשלח לקח בעצמו (auto-open בהפרה). הודעה משותפת: מספר מפעילים יכולים ack אותה תקרית וכל אחד מופיע כערך מובחן ומיוחס. תא **התקריות** מקבץ תקריות פתוחות לפי מצב ומאפשר לך לסנן לפי חומרה ומועסק: תא התקריות המציג כרטיסי תקריות מקושרות התראה וכרטיסי תקריות אד-הוק עם תגי חומרה ומועסקות פתיחת תקרית מציגה את ראיות ההפרה, מועסקות והמנויים, ציר הזמן של הפעילות המיוחסת, ועצומת הערות: תצוגת פרטי תקרית: התראה האב, סיכום הפרה, מועסקות, מנויים, עיתון פעילות מיוחס, ושיחה *** ## הרשאות נדרשות תוכן כללי *התראות* ובדיקת *תקריות* הם חששות נפרדים עם מענקים נפרדים, כך שתוכל להעניק לסיבוב ברירת מחדל גישה תקרית ללא סיפור לתוכה גם היכולת לכתוב מחדש את הכללים. * `alerts:read`: הצג כללי התראות. * `alerts:write`: צור, ערוך, מחק כללי התראות, והפעל הודעת בדיקה. * `incidents:read`: הצג תקריות. * `incidents:write`: פתח תקריות ידניות (ad-hoc) שאינן קשורות להתראה. * `incidents:ack`: הודא, הקצה, הערות, ופתור תקריות. > **הורשת `alerts:ack` מורשת.** מפתחות ומפעילים שהוענקו לטוקן `alerts:ack` הישן שלהם ממשיכים לעבוד: זה מכובד כ-`incidents:ack` (והרמז `incidents:read`), כך שיום-קרוביות קיימות שומרות על גישתם ללא הדלקה מחדש של פרטים. בעיה מענקים חדשים עם המשפחה `incidents:*`. מענק על מפתחות API (`POST /keys`) ומפעילים (`PUT /users/:id`). `PermGate` של הלוח נועל את הכפתורים הרלוונטיים כאשר הרשאה חסרה; תראה `// 403` ליד הפעולה. > **בורר נמען דוא"ל.** בורר הנמענים של עורך ההתראות רושם את חברי הארגון שלך כך שתוכל לבחור אותם לפי שם. הוא טוען לכל מפעיל המחזיק `alerts:read` או `alerts:write`; צפיית ספרית הצוות שלך למטרה זו **לא** דורשת `users:read`, והבורר מחזיר רק כתובות דוא"ל של חברים, לעולם לא רשומות משתמש מלאות. *** ## תצורה משתנים סביבה שנצרכו על ידי המשלח: | Var | ברירת מחדל | מטרה | | -------------------------- | ---------------------------- | ------------------------------------------------------------------------ | | `ALERT_WORKERS` | `1` | משימות עובדים לכל מופע שרת. רוב הפריסות צריכות רק אחד. | | `ALERT_CLAIM_BATCH` | `16` | התראות מרביות עובד יחיד מעבד. | | `ALERT_POLL_IDLE_SECS` | `5` | שינה עובדת כאשר התור ריק. | | `ALERT_REQUEST_TIMEOUT_MS` | `15000` | פרקודה הערכה הדלקה. | | `DASHBOARD_URL` | `https://app.befailproof.ai` | מקור המשמש לבניית קישור הקסם של תקרית בהודעות. קבע לבעלות לוח הבקרה שלך. | לאחר כשל הערכה חולף (ClickHouse בלתי נגיש, פרק זמן שאילתה), המשלח מנסה מחדש את הכלל עם מעוך אקספוננציאלי. ברגע שלכלל יש זכירה **5** כשלים חוליים רצופים הוא משוכסל בקדנציה רגילה שלו בכל מקום חוקי על רקע להמשיך, לכן כלל שמשכך בעקביות עדיין ממשיך להיות מוערך מחדש. תקרה זו קבועה ואינה מתויבלת על ידי מפעיל. הגדרות ערוץ (מנוהל מ-`/settings`, לא env): * `alerts.email_default_recipients` (`email_list`): מערך JSON של מחרוזות דוא"ל — הנמענים ברירת המחדל לערוצי דוא"ל. * `alerts.slack_default_webhook` (`url`): URL webhook נכנס ברירת המחדל של Slack. * `alerts.webhook_default_url` (`url`): generic-webhook URL ברירת המחדל. * `alerts.webhook_signing_secret` (`secret`): מפתח HMAC-SHA256. תמיד החזר כ-`""` בתגובת GET; הקלד ערך חדש לסיבוב. * `alerts.enabled_channels` (`channel_set`): קבוצת ערוצים חיצוני רחב-ארגוני שמשודרות כאשר התראה משתלחת; ברירות לכל שלוש (`email`, `slack`, `webhook`). הסרת סוג כאן משעות את הערוץ בכללי לכל התראה ללא עריכת כל כלל. ערוץ בתוך הלוח תמיד מועבר ואינו מושפע מהגדרה זו. *** ## אמת התראה חדשה לפני הסמכה על התראה חדשה: 1. שמור אותו כמופעל עם לפחות ערוץ הודעות אחד. 2. בחר **בדיקה** בעמוד פרטי ההתראה וקבל את הודעת הבדיקה הסינתטית בכל יעד מוגדר. 3. לאחר ההפרה הראשונה בעולם האמת, קבל את הופעת התקרית תחת **Incidents** וערכו הנמדד תואם את שאילתת הלוח המקביל. תקריות לא נפתרות באופן אוטומטי כאשר תנאי מתנקה. מפעיל חייב לפתור אותם מעמוד פרטי התקרית. *** ## פתרון בעיות | סימפטום | סיבה סבירה | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | התראה לא משתלחת לעולם | `enabled = false`, או אין ערוצים מצורפים, או שאילתת CH בסיסית מחזירה 0 שורות. השתמש בתקן *לבדיקה* כדי לקבל ערוצים; השתמש ב-`/queries/run` כדי לקבל המטרי. | | הודעת Slack חסרה | `alerts.slack_default_webhook` (או מפתח העקיפה לכל התראה) אינו קבוע: בדוק `alert_notifications.target` לשורות ``; או `slack` סוג מופעל בגלל ב`alerts.enabled_channels`: בדוק שורות `alert_notifications` עם סטטוס `skipped_disabled` ויעד ``. | | Webhook כללי 401 | התמקד דורש חתימה אך `alerts.webhook_signing_secret` אינו קבוע. אמת בנמקד שה-HMAC תואם `hmac_sha256(secret, body)`. | | דוא"ל "מכל השידורים נכשלו" | פרטי SMTP שגויים או כתובת `from` נדחתה על ידי השידור שלך. אותו משטח שחומק אימיילי OTP: אם אלה עובדים, תחבורת SMTP בסדר. | | תקרית משחזרת שוב ושוב | כפתורי המרוכב תוקפים מדי: נסה להרים את `min_breaches` או `eval_window` אז טריגרים חולפים לא פתוחים מחדש תקריות פתרת. |