הסבר על רישום ביומן

במאמר הזה מוסבר על תהליך הרישום ביומן, כולל סטנדרטים של יומנים, הנחיות לגבי רמות, סיווגים, מטרות וקירובים של כמה מחסניות.

תקני יומן

הרישום ב-Android הוא מורכב בגלל השילוב של סטנדרטים שונים שמשולבים ב-logcat. בהמשך מפורטים התקנים העיקריים שבהם נעשה שימוש:

מקור דוגמאות הנחיות לגבי רמת השילוב
‫RFC 5424 (syslog standard) ליבת Linux, הרבה אפליקציות Unix ליבה, תהליכי רקע של המערכת
android.util.Log רישום ביומן של אפליקציות ומסגרת Android מסגרת Android ואפליקציית מערכת
java.util.logging.Level רישום כללי ב-Java אפליקציה שאינה אפליקציית מערכת

איור 1: דרישות לגבי רמת היומן.

למרות שכל אחד מהתקנים האלה בנוי מרמות דומות, הם שונים ברמת הפירוט. אלה הערכים המקבילים המשוערים בין התקנים:

רמה של RFC 5424 רמת החומרה RFC 5424 תיאור RFC 5424 android.util.Log java.util.logging.Level
0 חירום אי אפשר להשתמש במערכת Log.e / Log.wtf SEVERE
1 התראה חובה לנקוט פעולה באופן מיידי Log.e / Log.wtf SEVERE
2 קריטית תנאים קריטיים Log.e / Log.wtf SEVERE
3 שגיאה תנאי שגיאה Log.e SEVERE
4 אזהרה תנאי אזהרה Log.w WARNING
5 הודעה רגיל אבל משמעותי Log.w WARNING
6 מידע הודעות מידע Log.i INFO
7 ניפוי באגים הודעות ברמת ניפוי הבאגים Log.d CONFIG, FINE
- - הודעות מפורטות Log.v FINER / FINEST

איור 2: רמות הרישום ביומן של syslog,‏ Android ו-Java.

הנחיות לגבי רמת הרישום ביומן

יש הנחיות קיימות לכל תקן של יומן. רמת היומן שנבחרה תואמת לתקן המתאים שבו משתמשים, כמו שימוש בתקן syslog לפיתוח ליבה.

באיורים הבאים מוצגים סדרי רמות היומן, מהנמוכה לגבוהה:

ERROR היומנים האלה תמיד נשמרים.
WARN היומנים האלה תמיד נשמרים.
INFO היומנים האלה תמיד נשמרים.
DEBUG היומנים האלה נאספים אבל נמחקים בזמן הריצה.
VERBOSE היומנים האלה אף פעם לא נאספים באפליקציה, אלא רק במהלך הפיתוח.

איור 3: android.util.Log

CONFIG רמת ההודעה להודעות הגדרה סטטיות
FINE רמת ההודעה שמספקת פרטי מעקב
FINER מציין הודעת מעקב מפורטת למדי
FINEST מציין הודעת מעקב מפורטת מאוד
INFO רמת ההודעה להודעות עם מידע לציבור
SEVERE רמת ההודעה שמציינת כשל חמור
WARNING רמת ההודעה שמציינת בעיה פוטנציאלית

איור 4: java.util.Logging.Level.

0 חירום אי אפשר להשתמש במערכת
1 התראה חובה לנקוט פעולה באופן מיידי
2 קריטית תנאים קריטיים
3 שגיאה תנאי שגיאה
4 אזהרה תנאי אזהרה
5 הודעה מצב רגיל אבל משמעותי
6 מידע הודעות עם מידע חשוב
7 ניפוי באגים הודעות ברמת ניפוי הבאגים

איור 5: RFC 5424 – סעיף 6.2.1.

רישום ביומן של אפליקציות

רישום סלקטיבי ביומן מתבצע באמצעות TAG לפי מחלקה android.util.Log באמצעות Log#isLoggable, כמו שמוצג בהמשך: 

if (Log.isLoggable("FOO_TAG", Log.VERBOSE)) {
 Log.v("FOO_TAG", "Message for logging.");
}

אפשר לכוונן את היומנים בזמן ריצה כדי לספק רמת רישום ביומן לפי הבחירה, כמו שמוצג בהמשך:

adb shell setprop log.tag.FOO_TAG VERBOSE

מאפייני log.tag.* מאופסים בהפעלה מחדש. יש גם וריאציות קבועות שנשארות גם אחרי הפעלה מחדש. לדוגמה:

adb shell setprop persist.log.tag.FOO_TAG VERBOSE

בדיקות Log#isLoggable משאירות עקבות ביומן בקוד האפליקציה. דגלים בוליאניים DEBUG מדלגים על עקבות של יומנים באמצעות אופטימיזציות של קומפיילר שמוגדרות לערך false, כמו שמוצג בהמשך:

private final static boolean DEBUG = false;


…
If (DEBUG) {
 Log.v("FOO_TAG", "Extra debug logging.");
}

אפשר להסיר את הרישום ביומן לכל APK בנפרד באמצעות ערכות כללי ProGuard על ידי R8 בזמן ההידור. בדוגמה הבאה, כל מה שמתחת לרמת INFO נמחק מהיומן של android.util.Log:

# This allows proguard to strip isLoggable() blocks containing only <=INFO log
# code from release builds.
-assumenosideeffects class android.util.Log {
  static *** i(...);
  static *** d(...);
  static *** v(...);
  static *** isLoggable(...);
}
-maximumremovedandroidloglevel 4

האפשרות הזו שימושית כשמטפלים בכמה סוגים של גרסאות build של אפליקציות (לדוגמה, גרסאות build לפיתוח לעומת גרסאות build להפצה), כשמצפים שהקוד הבסיסי יהיה זהה, אבל רמות היומן המותרות שונות. צריך להגדיר מדיניות ברורה לאפליקציות (במיוחד לאפליקציות מערכת) ולפעול לפיה כדי להחליט איך סוגי build וציפיות לגבי גרסאות משפיעים על פלט היומן.

רישום ביומן המערכת ב-Android Runtime‏ (ART)

יש כמה מחלקות שזמינות לאפליקציות ולשירותים של המערכת:

כיתה מטרה
android.telephony.Rlog רישום ביומן של הרדיו
android.util.Log רישום כללי ביומן של האפליקציה
android.util.EventLog רישום ביומן של אירועים אבחוניים של משלב מערכות
android.util.Slog Platform framework logging

איור 6: מחלקות ושימושים של יומני מערכת זמינים.

למרות ש-android.util.Log ו-android.util.Slog משתמשים באותם תקנים של רמת יומן, Slog הוא מחלקה של @hide שאפשר להשתמש בה רק בפלטפורמה. הרמות EventLog ממופות לרשומות בקובץ event.logtags ב-/system/etc/event-log-tags.

רישום ביומן מקומי

הרישום ביומן ב-C/C++‎ מתבצע לפי התקן syslog, כאשר syslog(2) מתאים לליבת Linux‏ syslog ששולטת במאגר printk, ו-syslog(3) מתאים ליומן המערכת הכללי. ‫Android משתמשת בספרייה liblog לרישום כללי של פעולות המערכת.

‫liblog מספק עטיפות לקבוצות של קובצי משנה של יומנים באמצעות הפורמט הבא של מאקרו:

[Sublog Buffer ID] LOG [Log Level ID]

לדוגמה, RLOGD מתאים ל-[Radio log buffer ID] LOG [Debug Level]. אלה העטיפות העיקריות של liblog:

מחלקה עוטפת פונקציות לדוגמה
log_main.h ALOGV, ALOGW
log_radio.h RLOGD, RLOGE
log_system.h SLOGI, SLOGW

איור 7: עטיפות.liblog

ל-Android יש ממשקים ברמה גבוהה יותר לרישום ביומן, שמועדפים על פני שימוש ישיר, כפי שמוצג בהמשך:liblog

ספרייה שימוש
async_safe ספרייה לרישום ביומן רק מסביבות אסינכרוניות בטוחות לאותות
libbase ספריית רישום ביומן שמספקת ממשק של זרם C++‎ לרישום ביומן, בדומה לרישום ביומן בסגנון Google ‏ (glog). אפשר להשתמש ב-libbase גם בפרויקטים חיצוניים, והוא זמין באפליקציות שמשתמשות ב-libbase_ndk.

איור 8: ספריות של יומני רישום ברמה גבוהה יותר.

קירובים של כמה מחסניות

בגלל הבדלים ברמת הפירוט וברמת הכוונה, אין התאמות ברורות או מדויקות בין תקני רישום שונים ביומן. לדוגמה, הרמות java.util.logging.Level ו-android.util.Log ביומני שגיאות לא תואמות אחת לשנייה:

java.util.Logging.Level android.util.Log
SEVERE Log.wtf
SEVERE Log.e

איור 9: רמת השגיאה ביומן הרישום הרגיל של Java לעומת יומן הרישום של Android.

במקרים כאלה, צריך להשתמש בתקן הספציפי כדי לקבוע איזו רמה להחיל.

במהלך פיתוח מערכת עם כמה רכיבים ברמת ה-stack, צריך לפעול לפי איור 1 כדי לקבוע באיזה תקן להשתמש בכל רכיב. באיור 2 מופיע מדריך משוער להודעות ברמה.

אבטחה ופרטיות

אין לרשום ביומן פרטים אישיים מזהים (PII). הפרטים האלה כוללים, בין היתר:

  • כתובות אימייל
  • מספרי טלפון
  • שמות

באופן דומה, פרטים מסוימים נחשבים רגישים גם אם הם לא פרטים אישיים מזהים באופן מובהק.

לדוגמה, למרות שמידע על אזור זמן לא נחשב לפרטים אישיים מזהים, הוא כן מצביע על המיקום המשוער של המשתמש.

צריך לטפל במדיניות בנושא יומנים ובפרטים מקובלים כחלק מבדיקת האבטחה והפרטיות לפני השחרור.

מקובצי היומן במכשיר

הגישה לכל יומני המכשיר, כולל השימוש ב-android.permission.READ_LOGS, מוגבלת:

  • אם אפליקציה ברקע מבקשת גישה לכל יומני המכשיר, הבקשה נדחית באופן אוטומטי, אלא אם האפליקציה:
    • שיתוף של ה-UID של המערכת.
    • נעשה שימוש בתהליך מערכת מקורי (UID < APP_UID).
    • אזור זמן: DropBoxManager.
    • הגישה היא רק למאגר הזמני של יומן האירועים.
    • נעשה שימוש ב-EventLog API.
    • משתמש בבדיקות עם מכשור.
  • אם אפליקציה בחזית עם READ_LOGS מבקשת גישה ליומני המכשיר, המערכת מבקשת מהמשתמש לאשר או לדחות את בקשת הגישה.