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

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

תקנים של יומנים

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

מקור דוגמאות הנחיות לגבי רמת הערימה
RFC 5424 (syslog רגיל) ליבת 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 וציפיות לגבי גרסאות משפיעים על פלט היומן.

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

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

כיתה Purpose
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 הן:

Wrapper class פונקציות לדוגמה
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.

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

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

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

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

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

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

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

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

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

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

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