:summary: שדות החובה והשדות המומלצים בכל רשומה, דוגמה מלאה, איך עובדת דגימת לוגי ה-info ומה אומר היעדר של שורה בלוג, טשטוש שדות רגישים, וטקסונומיית קודי השגיאה. סכמת לוגים ========== שדות חובה --------- - ``schema_version`` (למשל ``"1.0"``) - ``event`` (שם קנוני ב-``snake_case``) - ``severity`` (``info``/``warn``/``error``) - ``timestamp`` (``ISO8601``, מוסף אוטומטית על ידי structlog) - ``request_id`` (מזהה בקשה קצר, מ-ContextVar) - ``trace_id``/``span_id`` (מוזרקים אוטומטית כש-OpenTelemetry פעיל) שדות מומלצים ------------ - ``user_ref`` (מזהה לא-PII) - ``resource`` (``{type, id}``) - ``attributes`` (שדות ייעודיים לאירוע) - ``error_code`` (לשגיאות בלבד, קוד יציב לפי טקסונומיית השגיאות) - ``msg_he`` (טקסט קריא בעברית) שמות האירועים עצמם, ומה כל אחד מהם אומר, נמצאים ב-:doc:`observability/events_catalog`. דוגמה ----- .. code-block:: json { "schema_version": "1.0", "event": "file_saved", "severity": "info", "timestamp": "2025-10-15T10:23:45.123Z", "request_id": "a3f2c891", "trace_id": "0123abcd0123abcd0123abcd0123abcd", "span_id": "abcd0123abcd0123", "user_ref": "u_12345", "resource": {"type": "file", "id": "file_789"}, "attributes": {"language": "python", "size_bytes": 1520}, "msg_he": "קובץ נשמר בהצלחה" } דגימה (Sampling) ---------------- כדי להקטין את נפח הלוגים אפשר לדגום אירועי ``info``: ``LOG_INFO_SAMPLE_RATE`` קובע איזה חלק מהם מגיע לפלט, וברירת המחדל ``1.0`` שומרת את כולם. הדגימה נעשית ב-``_maybe_sample_info`` שב-``observability.py``. מה לא נדגם אף פעם: - אירועי ``warn`` ו-``error``. - שורות ``logging`` רגילות (``logger.info(...)``), שאינן עוברות בשרשרת של structlog. - האירועים שב-``INFO_SAMPLE_BUILTIN_ALLOWLIST``, וגם השמות שב-``LOG_INFO_SAMPLE_ALLOWLIST``. המשתנה **מוסיף** על הרשימה המובנית ואינו מחליף אותה. הרשימה המובנית והחלון, כפי שהם מוגדרים בקוד: .. literalinclude:: ../observability.py :language: python :start-after: # docs:info-sampling-constants:start :end-before: # docs:info-sampling-constants:end :caption: observability.py – הקבועים של הדגימה כשהשיעור גדול מ-0 וקטן מ-0.999 (מ-0.999 ומעלה הכול נשמר), כל שורת ``info`` שאינה ברשימות עוברת את השאלה הזו: האם נשמרה שורה של אותו שם אירוע ב-``INFO_SAMPLE_WINDOW_SECONDS`` האחרונות? אם לא, השורה נשמרת בלי הגרלה. אם כן, היא חזרה בתוך החלון, והיא עוברת הגרלה: עם ``request_id`` לפי hash שלו, כך שהחזרות של אותה בקשה נשמרות או נזרקות יחד, ובלעדיו באקראי. כל שורה שנשמרת, בזכות החלון או בהגרלה, פותחת חלון חדש לאותו שם. שורה שנזרקה לא מזיזה אותו. - ``0`` מכבה את ה-``info`` לגמרי: כל אירוע שאינו ברשימות נזרק, כולל ההופעה הראשונה שלו. - ערך שאינו מספר — טקסט, ערך ריק או ``nan`` — נחשב ``1.0``. ערך שלילי נחשב כמו ``0``. - הזיכרון של שמות האירועים מוגבל ב-``_INFO_SAMPLE_MAX_TRACKED_EVENTS``. כשהוא מתמלא הוא מתרוקן, נרשמת על זה אזהרה, וההופעה הבאה של כל שם נשמרת כאילו הייתה הראשונה. כלומר, השכחה יכולה רק להוסיף שורות, לא להעלים אותן. מה אומר היעדר של שורה ~~~~~~~~~~~~~~~~~~~~~~ כשהשיעור גדול מ-0: - אירוע שנשלח פעם אחת בחיי התהליך, כמו ``db_connected``, ‏``metrics_db_initialized`` או ``alert_tags_db_initialized``, מופיע בלוג של כל עלייה. - אם אירוע קרה ברגע מסוים, יש בלוג שורה שלו מאותו רגע או מ-``INFO_SAMPLE_WINDOW_SECONDS`` שלפניו. לכן, כשמחפשים אירוע בטווח זמן, מרחיבים את החיפוש בחלון אחד אחורה. אם גם שם אין שורה, האירוע לא קרה. - מספר השורות בלוג **אינו** מספר הפעמים שהאירוע קרה: מובטחת רק שורה אחת לכל חלון, והחזרות נדגמות. לספירה משתמשים במדדים, לא בלוג. עד 6.10.2026 כל הופעה הוגרלה בנפרד, ובלוגים מלפני התאריך הזה היעדר של שורת ``info`` אינו מוכיח דבר. כך נוצרה אז מסקנה שכותב המדדים של הוובאפ לא עולה, בזמן שהיעדר השורה ``metrics_db_initialized`` הוסבר כולו בדגימה. פרטיות ------ - ערך של שדה שהשם שלו מכיל אחת המילים שב-``_redact_sensitive`` (``observability.py``) מוחלף ב-``[REDACTED]``. הזיהוי הוא לפי שם המפתח בלבד, לא לפי התוכן: סוד שיושב בשדה עם שם תמים לא יטושטש. - אין לוג לתוכן קוד או לשאילתות גולמיות — רק מטא-נתונים. טקסונומיית שגיאות (Error codes) -------------------------------- .. code-block:: yaml errors: E_FILE_DUPLICATE: category: storage severity: error remediation: "בדקו unique index; הציעו למשתמש שם חדש." E_SEARCH_TIMEOUT: category: search severity: warn remediation: "הקטינו טווח חיפוש; בדקו אינדקס/Cache." E_AUTH_INVALID_SESSION: category: auth severity: warn remediation: "ביצוע התחברות מחדש; בדיקת עוגייה."