מנוע ניתוח לוגים (Log Event Aggregator)

monitoring/log_analyzer.py מרכז את כל האינטליגנציה שמטרתה להמיר זרם לוגים רועש להתראות פעולה. העמוד מפרט את רכיבי המערכת, הארכיטקטורה והקונפיגורציה שבין monitoring/log_analyzer.py, monitoring/error_signatures.py ו-scripts/run_log_aggregator.py.

ארכיטקטורה

  1. סינון רעשים – השורה עוברת דרך noise_allowlist שמוגדר ב-config/error_signatures.yml. התאמה תעצור את העיבוד.

  2. התאמת חתימה – ErrorSignatures.match() מחזיר קטגוריה, תקציר, מדיניות וסיווג על בסיס regex.

  3. Canonicalization + Fingerprint – מנרמל מזהים דינמיים (UUID, timestamps, נתיבים) ומחשב fingerprint קצר (sha1/12).

  4. חלונות גלילה – לכל fingerprint נשמר _Group עם מספר מופעים, דוגמאות אחרונות וטווח הזמנים.

  5. הפעלת מדיניות – immediate_categories גורמות לאזעקה מיידית; אחרת נדרש min_count בתוך window_minutes.

  6. Cooldown – לאחר התראה, אותו fingerprint לא ישלח שוב עד שיחלוף cooldown_minutes.

  7. שליחה – כברירת מחדל נשלח ל-internal_alerts.emit_internal_alert; במצב shadow (למשל בטסטים) נוצרת רק שורת לוג.

קונפיגורציה וקבצים

  • config/error_signatures.yml – מנהל קטגוריות (config/retryable/third_party/…) ורשימת חתימות בעלות pattern. עדכון הקובץ משפיע ישירות על הדירוג והתיאור שנשלח למפעיל. מומלץ לקרוא את קבצי קונפיגורציה ייעודיים ב-Rate Limiting.

  • config/alerts.yml – קובע את חלונות הזמן, ספי הספירה וקטגוריות שחייבות לעבור גם בזמן cooldown. מודגם בפרק ”alerts.yml“ בעמוד הקונפיגורציה.

  • config/observability_runbooks.yml (ולצורך תאימות: config/alert_quick_fixes.json) + config/alert_graph_sources.json – משמשים את ה-Observability Dashboard להצגת Quick Fixes וגרפים בהקשר של ההתראה שהופקה מהלוגים.

הרצת CLI מקומית

scripts/run_log_aggregator.py מאפשר לצרף את המנוע ל-pipeline קיים (למשל tail של Docker). הוא טוען את אותם קבצים כמו הסרוויס הראשי ויכול לרענן חתימות אוטומטית.

export ERROR_SIGNATURES_PATH="config/error_signatures.yml"
export ALERTS_GROUPING_CONFIG="config/alerts.yml"
LOG_AGG_ECHO=1 tail -F logs/app.log | python scripts/run_log_aggregator.py

דגלים חשובים:

  • LOG_AGG_RELOAD_SECONDS – טעינה מחדש של חתימות/קונפיג בכל N שניות (ברירת מחדל 60).

  • LOG_AGG_ECHO=1 – מדפיס ל-stderr כל שורה שסווגה כדי לחקור false positives.

  • ERROR_SIGNATURES_PATH / ALERTS_GROUPING_CONFIG – מצביעים על קובץ חלופי (למשל קובץ ניסוי ב-tmp).

שילוב במערכת

  • Alert Storage – התראות שמקורן בלוגים נשמרות יחד עם שאר ההתראות, ולכן מופיעות ב-Observability Dashboard, באינטגרציות Slack ובפקודות ChatOps כגון /triage.

  • Quick Fixes – כל התראה מקבלת רשימת פעולות המבוססת על ה-Runbooks ב-observability_runbooks.yml (ולצורך תאימות קיימת גם alert_quick_fixes.json). לדוגמה: /triage errors, מעבר ל-Playbook או פתיחת Incident Replay.

  • Visual Context – אם קיימת התאמה ל-alert_graph_sources.json (לפי metric/category) יוצמד לגרף חיצוני מאושר.

עבודה בטוחה

  • שכפול לסביבות ניסוי – לפני שינוי regex מהר, הריצו את כלי ה-CLI על snapshot לוגים היסטורי כדי לראות האם נוצרות התראות מיותרות.

  • בדיקות – LogEventAggregator.snapshot() מאפשר לבדוק במבחנים האם fingerprint מסוים נאגר והאם הספירה התאפסה לאחר cooldown.

  • Shadow Mode – בעת חיבור הסקריפט לסביבת production מומלץ להתחיל עם shadow=True (קוד מותאם אישית) כדי לוודא שאין הצפה בהתראות.

ניפוי תקלות נפוץ

  • אין קבצי קונפיג? ודאו שהנתיבים יחסיים לשורש הפרויקט או שתעבירו נתיב מוחלט.

  • התראות לא יוצאות? בדקו שהקטגוריה אינה ברשימת noise_allowlist וש-min_count_default אינו גבוה מדי עבור השדה שנמדד.

  • קלסיפיקציה שגויה? השתמשו ב-LOG_AGG_ECHO כדי לגזור את ה-fingerprint ולהוסיף חתימה חדשה או להרחיב את ה-regex הקיים.