Logcat — ما هو، مستويات التسجيل والعمل مع السجلات

ما هو Logcat في Android

Logcat هو مخزن مؤقت لنظام Android حيث تكتب جميع العمليات (بما في ذلك نواة Linux وsystem_server والتطبيقات) رسائل بتنسيق محدد. أداة logcat المضمنة في Android SDK تقرأ هذا المخزن وتعرض الرسائل في الوقت الفعلي. بدءًا من Android 4.1 (API 16)، أصبح الوصول إلى Logcat مقيدًا: يمكن للتطبيقات قراءة سجلاتها الخاصة فقط، بينما يمكن الوصول إلى سجلات النظام عبر ADB مع وصول التصحيح.

تحتوي كل رسالة Logcat على خمسة حقول: التاريخ والوقت وPID (معرف العملية) وTID (معرف الخيط) ومستوى السجل والعلامة. التنسيق ثابت ومتطابق عبر جميع إصدارات Android. يتيح ذلك استخدام أدوات grep وawk وsed لتصفية السجلات في خطوط CI/CD دون الاعتماد على IDE.

تُخزَّن السجلات في مخزن دائري بحجم ثابت: 256 كيلوبايت لـ main و256 كيلوبايت لـ system و256 كيلوبايت لـ events (Android 5+). عند امتلاء المخزن، يتم حذف الرسائل القديمة. يمكن للمطور تغيير حجم المخزن عبر الخاصية PROP logcat.size أو في خيارات المطور للجهاز.

مستويات السجلات والعلامات: هيكل رسالة Logcat

ستة مستويات من التسجيل تحدد أهمية الرسالة. يستخدم Android مستويات قياسية مشابهة للمنصات الأخرى ولكن بأسماء ثوابت خاصة به في الفئة Log. يساعد اختيار المستوى الصحيح في تصفية السجلات بكفاءة وعدم إغراق الرسائل الهامة بالرسائل الثانوية.

العلامات: تنظيم الرسائل حسب الوحدات

العلامة (tag) — سلسلة يصل طولها إلى 23 حرفًا تحدد مصدر الرسالة. يُوصى باستخدام اسم الفئة أو الوحدة كعلامة: MainActivity أو AuthManager أو NetworkModule. يتيح ذلك تصفية السجلات حسب مكون معين من التطبيق. للتوحيد في الفريق، يمكنك إنشاء ثوابت للعلامات في ملف منفصل أو استخدام مكتبة Timber التي تقوم بإدراج العلامة تلقائيًا حسب اسم الفئة.

سجلات الأعطال وتتبع مكدس الاستثناءات

عند حدوث استثناء غير معالج، يقوم Android تلقائيًا بكتابة تتبع المكدس الكامل في Logcat مع تحديد الفئة والطريقة وسطر الكود وسلسلة الاستدعاءات. يحتوي سجل العطل على نوع الاستثناء (NullPointerException أو RuntimeException) والرسالة وتسلسل الاستدعاءات من نقطة الانهيار إلى نقطة دخول التطبيق. لتحليل سجلات الأعطال من أجهزة المستخدمين، يُستخدم Firebase Crashlytics الذي يقوم بمزامنة تتبع المكدس مع خريطة التمويه (mapping.txt لنظام Android).

Logcat في Android Studio: الواجهة والمرشحات والبحث

Android Studio يوفر واجهة رسومية لـ Logcat يمكن الوصول إليها من خلال View ← Tool Windows ← Logcat (Alt + 6). يتم تحديث نافذة Logcat في الوقت الفعلي، وتعرض جميع رسائل الجهاز المتصل وتسمح بتكوين مرشحات مرنة لعزل المعلومات المطلوبة من التدفق العام.

التصفية حسب المستوى والعلامة

القائمة المنسدلة Log Level تقوم بتصفية الرسائل حسب الحد الأدنى للمستوى: اختر WARN لرؤية التحذيرات والأخطاء فقط، مع إخفاء VERBOSE وDEBUG وINFO. يسمح حقل البحث بالبحث حسب نص الرسالة أو العلامة — مع دعم التعبيرات العادية، وهو مناسب للبحث عن الرسائل بنمط معين.

المرشحات المحفوظة

Saved Filters — ميزة قوية لـ Logcat في Android Studio. يمكنك إنشاء مرشح يعرض فقط الرسائل ذات علامة تطبيقك (tag:MyApp) والمستوى WARN+. يتم حفظ المرشحات بين الجلسات وتكون متاحة من القائمة المنسدلة. للمشاريع ذات الوحدات المتعددة، أنشئ مرشحًا منفصلًا لكل وحدة.

# تعبير مثال لتصفية سجلات التطبيق
tag:"MyApp" level:WARN # فقط WARN+ لتطبيق MyApp
package:"com.mycompany" # جميع سجلات الحزمة
-tag:"okhttp" # استثناء سجلات OkHttp

التصدير والتحليل

يمكن تصدير سجلات Logcat إلى ملف نصي عبر أيقونة Save to File. هذا مفيد لإرفاقها بالتذاكر في Jira أو تحليل الجلسات الطويلة. يمكن فتح السجل المصدر في أي محرر نصوص وتطبيق grep للبحث عن الأنماط. للعرض المنسق، استخدم أداة logcat-color.

ADB logcat: أوامر الطرفية للعمل المتقدم

ADB logcat — إصدار وحدة التحكم من Logcat، يمكن الوصول إليه عبر Android Debug Bridge. ميزته الرئيسية هي إمكانية التشغيل على خوادم CI وفي نصوص الأتمتة وعلى الأجهزة بدون Android Studio. يدعم ADB logcat جميع المرشحات نفسها التي تدعمها الواجهة الرسومية، ولكن مع مرونة سطر الأوامر.

الأوامر الأساسية

الأمر adb logcat بدون وسائط يعرض المخزن المؤقت بالكامل في الوقت الفعلي. استخدم Ctrl+C للإيقاف. العلم -c يمسح المخزن قبل بدء التسجيل — وهذا مناسب عندما تحتاج إلى عزل سجلات الاختبار الحالي عن الرسائل السابقة. العلم -b يحدد نوع المخزن: main أو system أو events أو crash (Android 12+).

# مسح المخزن وبدء تسجيل السجلات بالعلامة MyApp
adb logcat -c
adb logcat MyApp:D *:S

# حفظ السجلات في ملف
adb logcat -d > logcat_dump.txt

# التصفية حسب PID العملية
adb logcat --pid=12345

التصفية باستخدام grep وawk

الجمع بين ADB وأدوات Unix يمنح أقصى مرونة. على سبيل المثال، المرشح "*:S TAG:D" يعرض فقط الرسائل ذات العلامة TAG بمستوى DEBUG وما فوق، مخفيًا جميع الرسائل الأخرى. لعرض الاستثناءات فقط، استخدم grep -i exception. لتحليل تكرار الأخطاء، طبق sort | uniq -c على عمود العلامة.

Logcat في CI/CD

في خوادم CI، يُستخدم Logcat لجمع التشخيصات أثناء تشغيل اختبارات واجهة المستخدم. خط أنابيب نموذجي: مسح المخزن قبل تشغيل الاختبارات، حفظ تفريغ السجلات كقطعة أثرية للبناء بعد تنفيذ الاختبارات. إذا فشل الاختبار، يمكن للسجلات تحديد ما إذا كان الفشل ناتجًا عن ANR أو استثناء غير معالج أو انتهاء مهلة الشبكة.

التسجيل في الكود: Log.d وLog.e وTimber

الفئة android.util.Log — هي API مدمجة لكتابة الرسائل في Logcat. Log.v وLog.d وLog.i وLog.w وLog.e وLog.wtf تقبل علامة (سلسلة) ورسالة (سلسلة) أو رسالة + Throwable. لتنسيق الرسائل، استخدم String.format أو قوالب سلاسل Kotlin — تجنب تسلسل السلاسل الذي ينشئ كائنات غير ضرورية في heap.

مكتبة Timber

Timber — مكتبة شائعة من Jake Wharton تعالج عيوب API Log المدمجة. تقوم Timber بإدراج العلامة تلقائيًا حسب اسم الفئة التي استدعت التسجيل ولا تتطلب تمرير علامة في كل استدعاء. تدعم Timber أيضًا التسجيل الشرطي: في إصدار Release، يمكن تعطيل استدعاءات Timber.v وTimber.d بسطر واحد في Application.onCreate.

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // API Log المدمجة
        Log.d("MainActivity", "onCreate called")

        // Timber — علامة تلقائية حسب اسم الفئة
        Timber.d("onCreate called")
    }

    private fun loadData() {
        try {
            val result = fetchFromNetwork()
            Timber.i("Data loaded: $result")
        } catch (e: IOException) {
            Timber.e(e, "Failed to load data")
        }
    }
}

التسجيل الشرطي لإصدار Release

في إصدار Release يُوصى بتعطيل سجلات VERBOSE وDEBUG لتقليل الحمل على مخزن Logcat ومنع تسرب المعلومات الحساسة. يحل Timber هذه المشكلة من خلال PlantingTree: في إصدار Debug يتم زرع DebugTree (يسجل كل شيء)، وفي Release — CrashReportingTree (يسجل ERROR فقط عبر Crashlytics). API Log المدمجة لا تدعم التسجيل الشرطي — يحتاج المطور إلى تغليف كل استدعاء بـ if (BuildConfig.DEBUG).