فهم التسجيل

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

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

إنّ تسجيل الدخول على 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 في وقت compilation. يزيل المثال التالي كل السجلّات التي تقلّ عن مستوى 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 Runtime (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 يوفّر مجموعات لفائف لمجموعات البلاگات الفرعية باستخدام التنسيق التالي لل macro:

[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++ للتسجيل، على غرار تسجيل ملف تعريف الارتباط (glog) على غرار Google يمكن استخدام libbase في كلّ من المشاريع الخارجية وهو متاح في التطبيقات التي تستخدم libbase_ndk.

الشكل 8: مكتبات السجلات ذات المستوى الأعلى

التقريبات المتعدّدة الحِزم

بسبب الاختلافات في الدقة ومستوى الدقّة، لا تتوفّر مطابقات واضحة أو دقيقة لمعايير التسجيل المختلفة. على سبيل المثال، لا يتطابقان java.util.logging.Level وandroid.util.Log لسجلّات الأخطاء بنسبة 1:1:

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 الوصول إلى سجلات الجهاز، يطلب نظام من المستخدم الموافقة على طلب الوصول أو رفضه.