🧠 Quick Fix חכם (Queue Delay + עומס/DB) – הנחיות למפתחים ולסוכני AI

המטרה של Quick Fix היא לתת המלצה קצרה, בטוחה ושימושית על “מה לעשות עכשיו”, לפי אותות שאנחנו כבר מודדים.

הדגש פה הוא על הבחנה בין:

• Queueing (תשתיתי): הבקשה ממתינה לפני שהאפליקציה התחילה לטפל בה (queue_delay).

• Processing איטי (אפליקטיבי): האפליקציה כבר מטפלת, אבל לוקח לה זמן (duration_ms).

איפה זה מופיע

• WebApp: עמודת Quick Fix בהיסטוריית התראות בלוח Observability (/admin/observability).

• Incident Replay: בפאנל Runbook (רק כפתורי פעולה שמוגדרים ב־Runbook).

• Telegram (התראות קריטיות): שורת “Quick Fix” בתוך הודעת ההתראה (best‑effort).

מקור אמת: איפה החוקים חיים

החוקים הדינמיים מוגדרים ב־config/observability_runbooks.yml תחת:

• quick_fix_rules.latency_v1

הפורמט מאפשר:

• ספים (thresholds)

• מיפוי פעולות (actions) לכל תרחיש

בנוסף, יש שני מקורות נוספים לפעולות:

• Runbooks באותו YAML (פעולות שמוגדרות בתוך צעדים)

• תאימות לאחור: config/alert_quick_fixes.json

האלגוריתם בפועל:

1. אם יש מספיק אותות → מפיק Quick Fix דינמי.

2. מוסיף פעולות Runbook (אם קיימות).

3. אם אין Runbook / אין פעולות → נופל ל־alert_quick_fixes.json.

טבלת החלטה (Latency / Slow Response)

ספי ברירת מחדל (ניתנים לשינוי ב־YAML):

• queue_delay_ms: 500ms

• duration_ms: 3000ms

כלל־על: קודם מזהים Queueing ורק אם הוא תקין עוברים ל־Processing.

Detection	Quick Fix	למה
Queueing גבוה + DB utilization גבוה	🔌 הגדל Connection Pool / Kill Slow Queries	אין מספיק חיבורים פנויים / שאילתות חוסמות
Queueing גבוה + CPU/RAM גבוה	📈 Scale Up / Add Workers	השרת בתקרת משאבים
Queueing גבוה + שימוש נמוך + DB utilization נמוך	🔄 Restart Service (Stuck Workers)	חשד ל־deadlock/worker תקוע
Queueing נמוך + Duration גבוה	🔍 Optimize Query / Cache	בעיית קוד/שאילתה, לא תשתית

אילו שדות אנחנו משתמשים בהם (סכמת נתונים)

אותות עיקריים

• Queue Delay

  • metadata.queue_delay (ms) – מגיע מלוגי access_logs (Headers X-Queue-Start/X-Request-Start).

  • במקרים מסוימים קיימים גם ערכים נגזרים: queue_delay_ms_p95 / queue_delay_ms_avg (best‑effort).

• Duration

  • metadata.duration_ms (ms) – זמן טיפול/בקשה.

עומס ומשאבים

• metadata.cpu_percent (אחוזים, best‑effort)

• metadata.memory_percent (אחוזים, best‑effort)

• metadata.active_requests (in‑flight requests, אינדיקציה מקומית לתהליך)

הערה: חלק מהמדדים הם “best‑effort” ויכולים להשתנות בין תהליכים/פודים. לכן הם משמשים בעיקר כדי לבחור המלצה כללית, לא כדי להסיק מסקנות חדות.

“DB Pool utilization”

בפועל אנו משתמשים היום ב־metadata.db_pool_utilization_pct שמחושב מה־Mongo serverStatus.connections (current/available).

• זה לא בדיוק utilization של client pool של PyMongo.

• אבל זה עדיין אינדיקציה טובה ללחץ על DB כשיש Queueing.

עקרונות Safety (חשוב)

• לא להציע פעולות מסוכנות כברירת מחדל (מחיקות/kill/rollback) בלי “caution” ובלי נתיב ברור.

• העדפה לפעולות בטוחות:

  • copy של פקודות ChatOps (/triage …, /errors, /status_worker)

  • קישורים למסכים פנימיים (Replay / Dashboard)

• אם אין מספיק נתונים → Fallback ברור (למשל “Scale Up” או “הרץ /triage latency”).

איך להוסיף/לשנות חוק (צ’קליסט למפתחים ול‑AI)

1. עדכון קונפיג

   • הוסיפו/שנו quick_fix_rules.latency_v1.thresholds ו/או actions.

2. בדיקת שדות קיימים

   • ודאו שהשדות שאתם רוצים קיימים ב־alert metadata.

   • אם לא: הוסיפו אותם בשכבת האינסטרומנטציה (לרוב metrics.py/alert_manager.py).

3. מימוש לוגיקה (אם נדרש)

   • הלוגיקה הדינמית נמצאת ב־services/observability_dashboard.py (פונקציה _dynamic_quick_fix_actions).

   • אם הוספתם אות חדש – הרחיבו את ה־extract/normalize שם בצורה fail‑open.

4. טסטים

   • כלל אצבע: שורה בטבלת החלטה = טסט.

   • לכסות:

     • queueing+pool גבוה

     • queueing+cpu/ram גבוה

     • queueing+usage נמוך

     • duration גבוה (processing)

     • חסר נתונים (fallback)

5. UI/Bot

   • UI מצייר את alert.quick_fixes כמו שהוא.

   • לבוט: ההמלצה נבנית best‑effort מתוך אותו מקור.

הערות לסוכני AI (איך לעבוד נכון)

• כשצריך מידע בזמן אמת (למשל האם באמת יש לחץ DB) לא מנחשים.

• מבקשים להריץ פקודות ChatOps רלוונטיות:

  • /triage latency

  • /triage db

  • /triage system

  • /errors

והפלט של הבוט הוא מקור האמת.