סכמת לוגים ואירועים (Observability)

מסמך זה מתאר את הסכמה המומלצת והאירועים הקנוניים שנעשה בהם שימוש במערכת.

שדות חובה בכל אירוע

  • schema_version: ”1.0“

  • event: שם אירוע בפורמט snake_case (לדוגמה: file_saved)

  • severity: info | warn | error

  • timestamp: ISO8601 (מוסף אוטומטית ע“י structlog)

  • request_id: מזהה בקשה קצר (ContextVar)

  • trace_id / span_id: מוזרק אוטומטית כאשר OpenTelemetry פעיל

שדות מומלצים

  • user_ref / user_id

  • resource {type, id}

  • attributes — שדות לפי אירוע

  • error_code — לשגיאות בלבד, קוד יציב

  • msg_he — טקסט תיאורי בעברית

אירועים מרכזיים

  • file_saved, file_read_success, file_read_unreadable

  • github_upload_* (saved/direct_success/error)

  • github_zipball_fetch_error, github_zip_create_error, github_zip_persist_error

  • github_inline_download_error, github_multi_zip_error

  • github_safe_delete_error, github_delete_file_error

  • github_share_selected_links_error, github_share_single_link_error

  • repo_analysis_start/repo_analysis_done/repo_analysis_error

  • metrics_view_error, alerts_parse_error, alert_received

  • db_* errors (לפי מקור)

  • business_metric (metric=…)

  • performance (operation=…, duration_ms=…)

דגימה (Sampling)

  • LOG_INFO_SAMPLE_RATE שולט בדגימת לוגי info

  • Allowlist: business_metric, performance, github_sync

פרטיות

  • טשטוש שדות רגישים: token/password/secret/authorization/cookie

  • אין לוג לתוכן קוד/שאילתות גולמיות — רק מטא-נתונים