آشنایی با ثبت گزارش

این مقاله فرایند گزارش‌گیری را پوشش می‌دهد، ازجمله استانداردهای گزارش، دستورالعمل‌های سطح، کلاس‌ها، اهداف، و تقریب‌های چند پشته‌ای.

استانداردهای گزارش

ثبت گزارش در Android به‌دلیل ترکیب استانداردهای استفاده‌شده که در logcat ترکیب شده‌اند پیچیده است. استانداردهای اصلی مورد استفاده در زیر شرح داده شده است:

منبع نمونه‌ها راهنمای سطح دسته
‫RFC 5424 (syslog استاندارد) هسته Linux، بسیاری از برنامه‌های Unix هسته، دیمون‌های سیستم
android.util.Log چارچوب Android + ثبت گزارش برنامه چارچوب Android و برنامه سیستم
java.util.logging.Level ثبت گزارش عمومی در جاوا برنامه غیرسیستمی

شکل ۱: استانداردهای سطح گزارش.

اگرچه هریک از این استانداردها ساختار سطح مشابهی دارند، اما در جزئیات متفاوت هستند. معادل‌های تقریبی در استانداردهای مختلف به شرح زیر است:

سطح 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

شکل ۲: سطوح گزارش‌گیری syslog،‏ Android، و Java.

رهنمودهای سطح گزارش

رهنمودهای موجودی برای هر استاندارد گزارش ارائه شده است. سطح گزارش انتخابی از استاندارد مناسب مورداستفاده پیروی می‌کند، مثلاً از استاندارد syslog برای توسعه هسته استفاده می‌کند.

ترتیب سطح گزارش، از کمترین به بیشترین، در سه شکل زیر نشان داده شده است:

ERROR این گزارش‌ها همیشه نگه‌داری می‌شوند.
WARN این گزارش‌ها همیشه نگه‌داری می‌شوند.
INFO این گزارش‌ها همیشه نگه‌داری می‌شوند.
DEBUG این گزارش‌ها در زمان اجرا گردآوری می‌شوند اما از آن‌ها اطلاعاتی استخراج نمی‌شود.
VERBOSE این گزارش‌ها هرگز در برنامه‌ای گردآوری نمی‌شوند، به‌جز درطول توسعه.

شکل ۳: android.util.Log

CONFIG سطح پیام برای پیام‌های پیکربندی ایستا
FINE سطح پیام ارائه‌دهنده اطلاعات ردیابی
FINER نشان‌دهنده پیام ردیابی نسبتاً دقیق
FINEST نشان‌دهنده پیام ردیابی بسیار دقیق است
INFO سطح پیام برای پیام‌های اطلاعاتی
SEVERE سطح پیام نشان‌دهنده خطای جدی
WARNING سطح پیام نشان‌دهنده مشکل احتمالی است

شکل ۴: java.util.Logging.Level.

0 اضطراری سیستم غیرقابل استفاده است
1 هشدار کنش باید بلافاصله انجام شود
2 مهم شرایط بحرانی
3 خطا شرایط خطا
4 هشدار شرایط هشدار
5 اعلامیه وضعیت عادی اما قابل‌توجه
6 اطلاعاتی پیام‌های اطلاعاتی
7 اشکال‌زدایی کردن پیام‌های سطح اشکال‌زدایی

شکل ۵: RFC 5424 - بخش ‫۶.۲.۱.

گزارش‌گیری برنامه

گزارش‌گیری انتخابی با 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

این برای مدیریت انواع ساخت برنامه متعدد (برای مثال، ساخت‌های توسعه دربرابر ساخت‌های انتشار) مفید است، جایی که انتظار می‌رود کد زیرین یکسان باشد، اما سطوح گزارش مجاز متفاوت است. برای برنامه‌ها (به‌ویژه برنامه‌های سیستم) باید خط‌مشی صریحی تنظیم و دنبال شود تا مشخص شود انواع ساخت و انتظارات انتشار چگونه بر برونداد گزارش تأثیر می‌گذارند.

گزارش‌گیری سیستم در زمان اجرای Android (ART)

چندین کلاس دردسترس وجود دارد که برای برنامه‌ها و سرویس‌های سیستم دردسترس هستند:

کلاس هدف
android.telephony.Rlog گزارش‌گیری رادیو
android.util.Log گزارش‌گیری عمومی برنامه
android.util.EventLog گزارش رویداد تشخیص خرابی یکپارچه‌ساز سیستم
android.util.Slog گزارش‌گیری چارچوب پلاتفرم

شکل ۶: کلاس‌ها و اهداف گزارش سیستم دردسترس.

اگرچه android.util.Log و android.util.Slog از استانداردهای سطح گزارش یکسانی استفاده می‌کنند، Slog یک کلاس @hide است که فقط توسط پلاتفرم قابل استفاده است. سطوح EventLog با ورودی‌های موجود در فایل event.logtags در /system/etc/event-log-tags نگاشت شده‌اند.

ثبت بومی

ورود به سیستم در C/C++ از استاندارد syslog پیروی می‌کند و syslog(۲) مربوط به هسته Linux syslog است که بافر printk را کنترل می‌کند و syslog(۳) مربوط به گزارشگر سیستم عمومی است. ‫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

شکل ۷: liblog بسته‌بندی.

Android میاناهای سطح بالاتری برای ثبت گزارش دارد که نسبت به استفاده مستقیم liblog ترجیح داده می‌شوند، همان‌طور که در زیر نشان داده شده است:

کتابخانه کاربرد
async_safe کتابخانه فقط برای ثبت گزارش از محیط‌های ایمن از سیگنال ناهمگام
libbase کتابخانه گزارش‌گیری که رابط جاری‌سازی C++‎ برای گزارش‌گیری ارائه می‌دهد، مشابه گزارش‌گیری به سبک Google (glog). ‫libbase در هر دو پروژه خارجی قابل‌استفاده است و در برنامه‌هایی که از libbase_ndk استفاده می‌کنند دردسترس است.

شکل ۸: کتابخانه‌های گزارش سطح بالاتر.

تقریب‌های چندپشته‌ای

به‌دلیل تفاوت در جزئیات و هدف سطح، هیچ تطابق واضح یا دقیقی بین استانداردهای مختلف ثبت گزارش وجود ندارد. برای مثال، سطوح java.util.logging.Level و android.util.Log برای گزارش‌های خطای مطابقت یک‌به‌یک ندارند:

java.util.Logging.Level android.util.Log
شدید Log.wtf
شدید Log.e

شکل ۹: سطح خطا در گزارش‌گیری استاندارد جاوا در مقایسه با گزارش‌گیری Android.

در مواردی مانند این، از استاندارد فردی برای تعیین سطح موردنظر برای اعمال استفاده کنید.

درطول توسعه سیستم با مؤلفه‌های چندسطحی پشته، از شکل ۱ پیروی کنید تا مشخص شود برای هر مؤلفه از کدام استاندارد استفاده شود. برای راهنمایی تقریبی درباره پیام‌رسانی براساس سطح، «شکل ۲» را دنبال کنید.

امنیت و حریم خصوصی

اطلاعات شناساننده شخصی (PII) را ثبت نکنید. این شامل جزئیاتی مثل موارد زیر می‌شود:

  • نشانی ایمیل
  • شماره‌های تلفن
  • نام

به‌همین ترتیب، برخی جزئیات حتی اگر به‌طور صریح شناساننده شخصی نباشند، حساس درنظر گرفته می‌شوند.

برای مثال، اگرچه اطلاعات منطقه زمانی به‌عنوان اطلاعات شناساننده شخصی درنظر گرفته نمی‌شود، اما نشانه‌ای از مکان تقریبی کاربر ارائه می‌دهد.

خط‌مشی گزارش و جزئیات قابل‌قبول باید به‌عنوان بخشی از بررسی امنیت و حریم خصوصی قبل‌از انتشار مدیریت شود.

گزارش‌های دستگاه

دسترسی به همه گزارش‌های دستگاه، ازجمله استفاده از android.permission.READ_LOGS محدود شده است:

  • اگر برنامه‌ای در پس‌زمینه درخواست دسترسی به همه گزارش‌های دستگاه را داشته باشد، درخواست به‌طور خودکار رد می‌شود، مگر اینکه برنامه:
    • «شناسه کاربری» سیستم را هم‌رسانی می‌کند.
    • از فرایند سیستم بومی (UID < APP_UID) استفاده می‌کند.
    • از DropBoxManager استفاده می‌کند.
    • فقط به میان‌گیری گزارش رویداد دسترسی دارد.
    • از EventLog API استفاده می‌کند.
    • از آزمون‌های ابزاری استفاده می‌کند.
  • اگر برنامه‌ای در پیش‌زمینه با READ_LOGS درخواست دسترسی به گزارش‌های دستگاه کند، سیستم از کاربر می‌خواهد درخواست دسترسی را تأیید یا رد کند.