فهم التسجيل

تتناول هذه المقالة عملية التسجيل، بما في ذلك معايير السجلّ وإرشادات المستوى والفئات والأغراض والتقريبات المتعدّدة.

معايير السجلّ

تتسم عملية تسجيل الدخول على 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 آثار سجلّ في رمز التطبيق. تتجاوز علامات Boolean 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

ويكون ذلك مفيدًا عند التعامل مع أنواع متعددة من إصدارات التطبيق (على سبيل المثال، إصدارات التطوير مقابل الإصدارات العلنية) حيث يُتوقّع أن يكون الرمز البرمجي الأساسي هو نفسه، ولكن تختلف مستويات السجلّ المسموح بها. يجب ضبط سياسة واضحة واتّباعها للتطبيقات (خاصةً تطبيقات النظام) لتحديد كيفية تأثير أنواع الإصدارات وتوقعات الإصدار على ناتج السجلّ.

تسجيل بيانات النظام في وقت تشغيل Android (ART)

تتوفّر عدة فئات للتطبيقات والخدمات على النظام، وهي:

الفئة الغرض
android.telephony.Rlog تسجيل بيانات الراديو
android.util.Log تسجيل بيانات التطبيق العامة
android.util.EventLog تسجيل أحداث التشخيص لمُدمِج الأنظمة
android.util.Slog تسجيل إطار عمل النظام الأساسي

الشكل 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
شديد Log.wtf
شديد Log.e

الشكل 9: مستوى الخطأ في تسجيل الدخول العادي إلى Java مقارنةً بتسجيل الدخول إلى Android

في حالات مثل هذه، استخدِم المعيار الفردي لتحديد المستوى الذي يجب تطبيقه.

أثناء تطوير النظام باستخدام مكوّنات متعددة على مستوى الحزمة، اتّبِع الشكل 1 لتحديد المعيار الذي يجب استخدامه لكل مكوّن. للحصول على دليل تقريبي بشأن الرسائل حسب المستوى، يُرجى الرجوع إلى الشكل 2.

الأمان والخصوصية

لا تسجِّل معلومات تحديد الهوية الشخصية (PII). ويشمل ذلك تفاصيل مثل:

  • عناوين البريد الإلكتروني
  • أرقام الهواتف
  • الأسماء

وبالمثل، تُعد بعض التفاصيل حساسة حتى إذا لم تكن تحدّد الهوية الشخصية بشكل صريح.

على سبيل المثال، على الرغم من أنّ معلومات المنطقة الزمنية لا تُعدّ معلومات تكشف الهوية الشخصية، إلا أنّها تشير إلى الموقع الجغرافي التقريبي للمستخدم.

يجب التعامل مع سياسة السجل والتفاصيل المقبولة كجزء من مراجعة الأمان والخصوصية قبل الإصدار.

سجلّات الجهاز

يتم حظر الوصول إلى جميع سجلّات الجهاز، بما في ذلك استخدام android.permission.READ_LOGS، في الحالات التالية:

  • إذا طلب تطبيق يعمل في الخلفية الوصول إلى جميع سجلات الجهاز، سيتم رفض الطلب تلقائيًا ما لم يستوفِ التطبيق الشروط التالية:
    • يشارك رقم تعريف المستخدم في النظام.
    • يستخدم عملية نظام أصلية (UID < APP_UID).
    • يتم استخدام DropBoxManager.
    • لا يمكن الوصول إلا إلى المخزن المؤقت لسجلّ الأحداث.
    • يستخدم واجهة برمجة التطبيقات EventLog.
    • تستخدِم اختبارات مزوَّدة بأدوات.
  • إذا طلب تطبيق يعمل في المقدّمة ويتضمّن READ_LOGS الوصول إلى سجلات الجهاز، سيطلب النظام من المستخدم الموافقة على طلب الوصول أو رفضه.