סכמת לוגים
שדות חובה
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(טקסט קריא בעברית)
שמות האירועים עצמם, ומה כל אחד מהם אומר, נמצאים ב-קטלוג אירועים קנוניים.
דוגמה
{
"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. המשתנה מוסיף על הרשימה המובנית ואינו מחליף אותה.
הרשימה המובנית והחלון, כפי שהם מוגדרים בקוד:
#: אירועי info שלא נדגמים לעולם. השמות ב-``LOG_INFO_SAMPLE_ALLOWLIST`` מתווספים עליהם.
INFO_SAMPLE_BUILTIN_ALLOWLIST: frozenset[str] = frozenset(
{"business_metric", "performance", "github_sync", "access_logs"}
)
#: אירוע info שאף שורה שלו לא נשמרה בחלון הזה (בשניות) נשמר בלי הגרלה.
INFO_SAMPLE_WINDOW_SECONDS = 600.0
כשהשיעור גדול מ-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)
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: "ביצוע התחברות מחדש; בדיקת עוגייה."