קטלוג אירועים קנוניים
עיקרון
שמרו על שמות אירועים ב-snake_case; הימנעו מ-PII. השתמשו ב-resource ו-attributes.
GitHub
github_rate_limit_check— בדיקת Rate Limit.github_upload_start— התחלת תהליך העלאה.github_upload_saved_error— שגיאה בשמירת קובץ שהועלה.github_upload_direct_error— שגיאה בהעלאה ישירה.github_import_repo_error— שגיאה בייבוא ריפו.github_sync— סנכרון קבצים מוצלח.
{"event":"github_upload_saved_error","severity":"error","request_id":"a3f2c891","repo":"owner/repo","error":"Rate limit exceeded"}
DB
db_get_latest_version_error— שגיאה בשליפת גרסה אחרונה.db_save_code_snippet_error— שגיאה בשמירת קטע קוד.db_delete_file_error— שגיאה במחיקה.db_mcp_uploads_index_missing— אינדקס של התנהגות עלmcp_uploads— ה-TTL עלexpires_atאו הייחודי עלupload_id, לפיindex_name— אינו במצב המבוקש. בלי ה-TTL העלאות שלא נצרכו אינן נמחקות לעולם, ולכן שער המוכנות של שירות ה-MCP עונה503 upload_storage_unavailableעל כל העלאה עד שהוא מאומת. נשלח מ-DatabaseManager._create_mcp_uploads_indexesבכל עלייה ובכל ניסיון בנייה של השער; הסיבה הטכנית נרשמת לפניו באירוע שלsafe_create_index. ראו העלאת תוכן בלי לעבור דרך המודל.db_advisor_index_missing— אינדקס TTL של מצב היועץ אינו במצב המבוקש באוסף שב-collection(advisor_historyאוadvisor_daily_usage), לפיindex_name. בלי ה-TTL שלadvisor_historyזיכרון השיחה לא נמחק, בניגוד למה שהפתיחה של היועץ מבטיחה לגולש. נשלח מ-DatabaseManager._create_advisor_indexesבכל עלייה; הסיבה הטכנית נרשמת לפניו באירוע שלsafe_create_index. ראו מצב היועץ (/advisor).db_styled_shares_index_missing— אינדקס של התנהגות עלstyled_shares— ה-TTL עלexpires_atאו הייחודי עלtoken, לפיindex_name— אינו במצב המבוקש. בלי ה-TTL קישורי שיתוף מעוצבים שפקעו נשארים במסד לצמיתות, אף שהם כבר עונים 404; בלי הייחודיtokenאינו מובטח למסמך אחד. נשלח מ-DatabaseManager._create_styled_shares_indexesבכל עלייה; הסיבה הטכנית נרשמת לפניו באירוע שלsafe_create_index. המפרט ב-styled_shares.py.db_recycle_bin_ttl_index_missing— אינדקס ה-TTL שמרוקן את סל המיחזור אינו במצב המבוקש בקולקציה שב-collection. בלעדיו פריטים בסל אינם נמחקים לעולם, והעמוד/trashממשיך להציג ”נמחק סופית ב-“ על תאריכים שעברו. נשלח מ-DatabaseManager._create_recycle_bin_ttl_indexesבכל עלייה ובפקודה/recycle_backfill; הסיבה הטכנית נרשמת לפניו באירוע שלsafe_create_index. המצב הנוכחי נראה בעמוד/admin/verify-indexes, בסעיףrecycle_bin_ttl.db_sync_jobs_index_missing— אינדקס של התנהגות עלsync_jobsאינו במקום, לפיindex_name: ה-TTL שמוחק ג’ובים ישנים (SYNC_JOBS_TTL_INDEX), או הייחודי שמאפשר ג’ובrunningאחד לכל ריפו (SYNC_JOBS_ONE_RUNNING_INDEX).reasonהואrunning_duplicatesכשהייחודי לא נוצר כי יש ריפו עם יותר מג’וב רץ אחד (הריפואים ב-repos), ו-create_failedכשהיצירה עצמה נכשלה; אז הסיבה הטכנית נרשמת לפניו באירוע שלsafe_create_index. בלי ה-TTL ג’ובים ישנים לא נמחקים, ובלי הייחודי שני workers יכולים לסנכרן את אותו ריפו יחד. נשלח מ-ensure_sync_jobs_indexes(services/repo_sync_service.py) כשה-worker של הסנכרון עולה, ומ-scripts/create_repo_indexes.py. ראו מה קורה לג’וב סנכרון.
{"event":"db_get_latest_version_error","severity":"error","request_id":"a3f2c891","error":"not found"}
Metrics (DB)
כתיבת מדדי הבקשות ל-service_metrics (_flush_once ב-monitoring/metrics_storage.py). כל באצ« מסתיים באחד מהאירועים האלה, או בלי אירוע כשהכתיבה הצליחה:
metrics_db_batch_resolved— השרת ענה על כל מסמך בבאצ« (BulkWriteError), ושום דבר לא חוזר לתור.insertedנכתבו עכשיו;already_storedהיו שמורים כבר מניסיון קודם שהתשובה שלו אבדה (כפילות על_id);droppedנזרקו, ו-dropped_codesסופר אותם לפי קוד השגיאה של השרת —unknownהוא מסמך שהתשובה לא הסבירה;write_concern_codesהם שגיאות write concern. ברמתinfoכששום דבר לא נזרק, ו-warnאחרת.metrics_db_batch_insert_error— הכתיבה נכשלה בתקלה שאחריה אי אפשר לדעת אם נכתבה: ניתוק, אין primary, מגבלת זמן של השרת (_OUTCOME_UNKNOWN_ERRORS). הבאצ« חוזר לתור עם ה-_idשלו, כך שהניסיון הבא לא יכתוב פעמיים, והניסיון הבא מגיע אחריMETRICS_FLUSH_INTERVAL_SEC.error_typeהוא שם החריגה.metrics_db_batch_dropped— חריגה מחוץ לתקלות האלה: באג, הרשאה חסרה, מסמך שאי אפשר לקודד. הבאצ« נזרק ולא מנוסה שוב, ברמתerror;error_typeבשדה, וה-traceback בשורת לוג נפרדת.
אף אחד מהם אינו מכיל את המסמכים עצמם, רק מספרים וקודים: נתיב הבקשה שבמסמך יכול לשאת טוקן של קישור שיתוף.
{"event":"metrics_db_batch_resolved","severity":"info","count":8,"inserted":3,"already_stored":5,"dropped":0,"dropped_codes":{},"write_concern_codes":[]}
Alerts
alert_received— התקבלה התראה מה-Alertmanager.alerts_parse_error— כשל בפענוח ההתראה.
Web Push
מנוי ותפעול:
push_subscribed/push_unsubscribed— דפדפן נרשם למנוי או הוסר ממנו.push_subscriptions_cleanup/push_subscriptions_delete_all— ניקוי מנויים מעמוד ההגדרות.push_deleted_dead_endpoints— מנויים שהוסרו אחרי404/410משירות הפוש.sw_push_report— דיווח מה-Service Worker על שלב בטיפול בהתראה.
שליחה של תזכורות פתקים:
push_send_attempt— ניסיון שליחה של תזכורת שהגיע זמנה.push_send_error— כשל בשליחה למנוי. נרשם עםendpoint_hashולא עם ה-endpoint עצמו, שהוא מזהה מכשיר.push_send_no_subscriptions— למשתמש אין מנוי פעיל.push_send_missing_vapid_private— המסלול המקומי נבחר בלי מפתח VAPID פרטי.
שליחה של אירועי כתיבה מה-MCP:
push_event_send_attempt— ניסיון שליחה של אירוע שנרשם על ידי שירות ה-MCP.push_event_unknown_kind— האירוע נושאkindשגרסת ה-WebApp הזו אינה יודעת לבנות ממנו התראה. הוא מכובה ואינו נשלח, כדי שלא ייבחר בכל סבב מכאן והלאה.push_event_delivery_exhausted— המסירה נכשלה עד תקרת הניסיונות, והאירוע עבר למצב סופי בלי שנשלח. עולה על כשל שאינו404/410— כלומר כזה שאינו מוחק את המנוי ולכן חוזר על עצמו בכל סבב.
בדיקה ידנית:
push_test_result/push_test_local_error/push_test_worker_error— תוצאותPOST /api/push/test.
Jobs
job_started— הרצת Job התחילה.job_completed— הרצה הסתיימה בהצלחה.job_failed— הרצה נכשלה.job_skipped— הרצה דולגה (מושבת, או כבר רץ).job_stuck— הרצה עברה את סף הזמן ועדייןrunning.job_runs_reconciled— הרצות שנשארו ממחזיק מנעול קודם נסגרו בעלייה. אירוע מסכם אחד לכל פיוס:countהוא המניין המלא, ``job_ids_sample`` הוא מדגם ולא הרשימה כולה. ראו Background Jobs Monitor. כשלא נמצא מה לסגור נרשמת שורת לוג באותו שם עםcountאפס — ולא נשלח אירוע — כדי ש“רץ ולא מצא כלום“ ייראה שונה מ“לא רץ“.jobs_orphan_reconcile_skipped— הפיוס לא רץ כלל. ``reason`` אומר למה:no_lock(התהליך אינו מחזיק זמן רכישת מנעול, למשל תחתLOCK_FAIL_OPEN) אוno_db(אוסףjob_runsלא זמין).jobs_orphan_reconcile_timed_out— הפיוס נחתך אחריRECONCILE_TIMEOUT_SECS(``services/job_orphan_reconciler.py``). מה שלא נסגר ממתין לעלייה הבאה.jobs_orphan_reconcile_failed— הפיוס נפל על חריגה; ה-traceback בלוג.job_run_reconcile_skipped— הרצה אחת לא נסגרה כי הסטטוס שלה השתנה בין השליפה לעדכון (סיימה בעצמה). נספרת ב-skippedשל האירוע המסכם. השמות ברמת הג’וב פותחים במזהה הג’וב,jobs_orphan_reconcile; השם ברמת ההרצה הבודדת פותח ב-job_run— כדי שחיפוש על אחד לא יתפוס את השני בטעות.
דוגמה לאירוע המסכם job_runs_reconciled:
{"event":"job_runs_reconciled","severity":"warn","count":3,"skipped":0,"truncated":false,"job_ids_sample":["cache_warming","drive_sync"]}
מילוי ה-mirrors בעליית הוובאפ
התראה לבוט, repo_mirror_fill_failing (ALERT_MIRROR_FILL_FAILING ב-services/repo_sync_service.py): נשלחת דרך emit_internal_alert ברמת error, פעם אחת לכל תהליך, כשהניסיון ה-MIRROR_FILL_ALERT_ATTEMPT של המילוי נכשל והמילוי ממשיך לנסות (דיסק בלי mirrors: המילוי בעלייה). השדות שלה: reason — db_unavailable (המסד לא זמין), read_failed (המסד לא ענה בקריאה של repo_metadata), lock_busy (תהליך אחר עדיין ממלא) או repos_failed; ``repos`` — הריפואים שהכשל שלהם ינוסה שוב, כש-reason הוא repos_failed; ``attempt`` ו-max_attempts; ``next_attempt_in_seconds``; ו-pid. alert_type הוא אותו שם, וה-runbook באותו שם ב-config/observability_runbooks.yml מסביר מה לבדוק לכל reason.
Google Drive
לבוט ולוובאפ יש חיבור Drive נפרד (ראו חיבור נפרד לכל שירות (owner)).
חיבור, ניתוק ותזמון בוובאפ (webapp/drive_auth.py, ``webapp/drive_backup_api.py``):
webapp_drive_connected— החיבור של הוובאפ נשמר, אחרי חזרה תקינה מגוגל.webapp_drive_disconnected— החיבור של הוובאפ נמחק. החיבור של הבוט לא משתנה.webapp_drive_schedule_set— נקבע תזמון גיבוי לוובאפ (schedule).webapp_drive_auth_failed— חיבור לא התחיל, כי ה-state לא נשמר במסד (reason:state_store_failed). המשתמש מקבל שגיאה ולא נשלח לגוגל.webapp_drive_callback_rejected— חזרה מגוגל שנדחתה.reasonאומר למה, ו-user_idמצורף כשיש משתמש ב-session. state, code, טוקנים וגוף התשובה של גוגל לא נרשמים —tests/test_webapp_drive_oauth_state.pyבודק את זה אחרי כל טסט בקובץ.
הסיבות ב-webapp_drive_callback_rejected (הרשימה מושווית לקוד ב-tests/test_webapp_drive_oauth_state.py):
session_missing— אין משתמש מחובר ב-session.state_missing— החזרה הגיעה בלי state.state_check_failed— שגיאת מסד בבדיקת ה-state.state_not_found_or_expired— ה-state לא שייך למשתמש הזה, כבר נוצל, או שפג תוקפו.google_error— גוגל החזיר שגיאה. הקוד שלה ב-google_error, אוunrecognizedכשהוא לא בצורה של קוד OAuth.code_missing— החזרה הגיעה בלי code.token_exchange_failed— החלפת ה-code בטוקנים נכשלה:error_typeכשלא הגענו לגוגל, אוhttp_statusו-google_errorכשגוגל ענה בשגיאה.token_response_invalid— תשובת הטוקנים אינה אובייקט JSON: לא JSON בכלל, או JSON שאינו אובייקט (http_status).no_access_token— בתשובת הטוקנים איןaccess_token.save_failed— שמירת הטוקנים במסד נכשלה.
{"event":"webapp_drive_callback_rejected","severity":"warn","reason":"token_exchange_failed","user_id":123456789,"http_status":400,"google_error":"invalid_grant"}
גיבוי בוובאפ (webapp/backup_scheduler.py):
webapp_drive_backup_failed— גיבוי Drive של הוובאפ, מתוזמן או ”גבה עכשיו“, לא הועלה.reasonהוא אחד מ-FAILURE_*ב-webapp/backup_scheduler.py:auth_required— גוגל דחה את החיבור (invalid_grant, או חיבור בלי refresh token), עםoauth_error. זה מצב סופי: מסך ההגדרות מבקש להתחבר מחדש, והתזמון מושהה עד שמתחברים (בדיקת חיבור לפני גיבוי (check_connection)).connection_failed— בדיקת החיבור לא עברה מסיבה אחרת:connection_statusהואtransient(תקלת רשת או תשובה שגוגל סימן לניסיון חוזר) אוunknown(למשלinvalid_client, תקלת הגדרות), ו-oauth_errorכשיש.upload_failed— ההעלאה לא החזירה מזהה קובץ. הסיבה בשורת הלוגdrive_call_failedשלservices/google_drive_service.py.exception— חריגה לא צפויה, עםerror_type.
ברמת
warn: בגיבוי מתוזמן, כשל שאינוauth_requiredמנוסה שוב אחרי המתנה שגדלה (_record_failed_attempt), עדRETRY_MAX_ATTEMPTSניסיונות. ב“גבה עכשיו“ אין ניסיון חוזר: התוצאה מוצגת למשתמש (manual_backup_errorב-/api/drive/backup-status).webapp_backup_retries_exhausted— גיבוי מתוזמן של הוובאפ נכשלattemptsפעמים ברצף (RETRY_MAX_ATTEMPTS), ועבר למועד הרגיל הבא של התזמון במקום לנסות שוב.targetהואdriveאוdisk. נשלח פעם אחת לכל רצף כשלים, כשהמונה (consecutive_failures) מתאפס.
התפריט והגיבוי המתוזמן בבוט (handlers/drive/menu.py, ``main.py``). ה-jobs של הגיבוי המתוזמן נוצרים בזיכרון בלבד, ו-drive_reschedule ב-main.py בונה מחדש מהתזמון השמור במסד כל job שחסר — בכל עלייה, כשכולם חסרים, ושוב בכל סבב שלו:
drive_handler_ready— ה-handler של תפריט ה-Drive (GoogleDriveMenuHandler) נוצר ונשמר ב-bot_dataבעליית הבוט.drive_schedule_job_set— נוצר job של גיבוי מתוזמן למשתמש (_ensure_schedule_job):keyהתזמון,interval_sהמרווח,first_sהשניות עד ההרצה הראשונה ו-planned_nextמועד ההרצה.drive_schedule_job_setup_failed— יצירת ה-job נכשלה (key,error).drive_schedule_job_cancelled— המשתמש כיבה את התזמון בתפריט.drive_schedule_job_missing— למשתמש יש תזמון פעיל בהעדפות ואין לו job בזיכרון, וה-job נוצר מחדש (ensure_schedule_job_if_missing).drive_reschedule_jobs_run— סיכום הרצה שלdrive_rescheduleב-main.py, שמשחזר את ה-jobs של התזמונים הפעילים:scanned, ``total`` (עם תזמון תקף), ``recreated``, ``skipped``.drive_reschedule_handler_restored— ה-handler חסר ב-bot_dataושוחזר מהעותק שעל ה-application (source).drive_scheduled_backup_start— גיבוי מתוזמן התחיל.drive_scheduled_backup_result— תוצאת הגיבוי המתוזמן (ok), ברמתwarnכשהוא נכשל.drive_scheduled_backup_auth_required— הגיבוי המתוזמן נכשל, ואי אפשר לבנות שירות Drive מהטוקנים השמורים; המשתמש קיבל בקשה להתחבר מחדש.drive_scheduled_backup_update_prefs— נשלח אחרי כל גיבוי מתוזמן, עם הזמנים שנשלחו לשמירה בהעדפות של הבוט (next_at,last_at,last_full_at). התוצאה של השמירה עצמה לא נבדקת שם, ולכן האירוע אינו ראיה שהזמנים נשמרו.drive_scheduled_backup_update_prefs_failed— חריגה בבלוק שמעדכן את הזמנים (error).drive_scheduled_backup_error— חריגה לא צפויה בהרצת הגיבוי המתוזמן (error); ה-traceback בלוג.
שגיאות מסד בחיבור ובהעדפות, של שני השירותים (database/repository.py):
db_save_drive_tokens_error/db_get_drive_tokens_error/db_delete_drive_tokens_error/db_save_drive_prefs_error/db_get_drive_prefs_error—ownerאומר של איזה שירות החיבור (botאוwebapp).db_get_users_with_active_drive_schedule_error— שגיאת מסד בשליפת המשתמשים שיש להם תזמון פעיל. השליפה היא של התזמון של הבוט בלבד.
אינדקס התיעוד
מעבר האינדוקס של אתר התיעוד (services/docs_index_service.py, ראו אינדקס התיעוד) ועמוד האדמין שלו. השדות של מעבר הם של המעבר הזה בלבד, ולא מצטברים: run_id; ``trigger`` — מי ביקש אותו (TRIGGERS במודול); ``status`` ו-code (STATUS_*, ומהקובץ EXPORT_* של services/docs_export_client.py, או CODE_* של המעבר); ``source_commit`` של הקובץ שנקרא; ``embedded`` — כמה נתחים הוטמעו; ``deleted_chunks``, ``deleted_sections`` ו-deleted_pages — כמה נמחקו, לפי קריאה חוזרת; ``deletions_spared`` — מחיקות שנחסכו כי הקובץ לא הכיר אף רשומה במסד; ``chunk_count`` — כמה נתחים במסד אחרי המעבר; ו-user_id כשאדמין ביקש את המעבר.
docs_index_pass— כל מעבר שהסתיים, בכל סטטוס.docs_index_awaiting_approval— מעבר אוטומטי עצר לאישור: מילוי ראשון או החלפת מודל, יותר מ-APPROVAL_THRESHOLD_CHUNKSנתחים להטמעה, או תוכנית שהשתנתה מאז שאושרה.codeאומר איזה מהם.docs_index_quota_paused— Gemini החזיר 429, והמעבר עצר.detailהוא הסטטוס וההודעה של Google, בתקרת אורך. ברמתwarning.docs_index_failed— מעבר נכשל, ברמתerror.codeהוא הסיבה ו-detailהפירוט. שני מקרים נשלחים עם שדות אחרים:lease_lost— ה-lease עבר למריץ אחר, והמעבר עצר בלי לכתוב עוד; ברמתwarning, ועםrun_idבלבד.unexpected_error— חריגה שהמעבר לא צפה;detailהוא שם המחלקה בלבד, וההודעה וה-traceback בלוג.docs_index_admin_action— פעולה בעמוד האדמין:actionהוא הכפתור,resultמה שחזר, ו-user_idמי לחץ.
התראה לבוט, docs_index_approval_needed (ALERT_APPROVAL_NEEDED): נשלחת דרך emit_internal_alert כשהאינדקס נכנס להמתנה לאישור — במסמך המצב לא הייתה approval לפני הכתיבה של המעבר — ולא בכל מעבר שעוצר, כמו docs_index_awaiting_approval. השדות שלה: reason (ה-code של המעבר), chunks_to_embed, approval_threshold, source_commit של הקובץ שנבדק, ו-indexed_commit — הקומיט שהאינדקס נכון אליו, כשיש כזה. alert_type הוא אותו שם, וה-runbook באותו שם ב-config/observability_runbooks.yml נותן לה שורת Quick Fix לעמוד האדמין.
{"event":"docs_index_pass","severity":"info","run_id":"5f0c1d2e","trigger":"deploy","status":"complete","code":null,"source_commit":"990a666a91fd2c821c6718f8f655e245eb80fc90","embedded":12,"deleted_chunks":1,"deleted_sections":1,"deleted_pages":0,"deletions_spared":0,"chunk_count":2310}
פתקים דביקים
האירועים של webapp/sticky_notes_api.py. כולם נושאים user_id; תוכן הפתק ושמו אינם נכנסים לאף אירוע.
sticky_note_created— פתק נוצר. לצדuser_id— המזהה של היעד:file_id,board_idאוrepo_name, לפי סוג הפתק.sticky_note_updated— פתק עודכן (note_id).sticky_note_deleted— פתק נמחק (note_id),threads_deleted: כמה שרשורי תגובות נמחקו איתו, ו-reminders_deleted: כמה מסמכי תזכורת נמחקו איתו. כל אחד מהםnullכשהמחיקה שלו נכשלה והפתק עצמו כבר נמחק (מצב התזכורת: שדה אחד מתאר, שניים סוטים).sticky_note_archived— פתק הועבר לארכיון (note_id), ו-threads_resolved: כמה שרשורים פתוחים נסגרו, אוnullכשהסגירה נכשלה וההעברה עצמה נשארה (ארכיון: היעד הרביעי).sticky_note_files_page_pinned— פתק לוח ננעץ לראש עמוד הקבצים (note_id). נשלח רק כשהנעיצה הזו נכתבה, ולא על ”כבר נעוץ“ (נעיצה לעמוד הקבצים: שדה לצד היעד, ולא יעד).sticky_note_files_page_unpinned— הנעיצה הוסרה (note_id). נשלח רק כשההסרה הזו נכתבה, ולא על ”כבר לא נעוץ“.note_reminder_set— נקבעה תזכורת לפתק (note_id).sticky_note_task_not_applied(error) — סימון צ’קבוקס שהמסד לא החיל (note_id).sticky_notes_<פעולה>_error(anomaly) — כשל בראוט, עםerror. הפעולה היא שם המסלול, למשלlist,createאוsearch.
Repo Analyzer
repo_analysis_start/repo_analysis_parsed/repo_analysis_donerepo_analysis_error— כשל בניתוח ריפו.
Business
business_metric— אירוע ביזנס כללי (למשלfile_saved/search/github_sync).
הערה
עדיף לציין מזהי משאבים עקביים (resource:{type,id}) ולשמור על msg_he קצר וברור.