أداة سطر أوامر Logcat

Logcat هي أداة سطر أوامر تُظهر سجلّ رسائل النظام، بما في ذلك الرسائل التي كتبتها من تطبيقك بفئة Log.

تتناول هذه الصفحة أداة سطر الأوامر logcat، ولكن يمكنك أيضًا عرض رسائل السجلّ من نافذة Logcat في "استوديو Android". للحصول على معلومات حول عرض السجلات وتصفيتها من "استوديو Android"، يُرجى الاطّلاع على عرض السجلات وكتابتها باستخدام Logcat.

نظرة عامة على نظام التسجيل

نظام تسجيل بيانات Android هو مجموعة من المخازن المؤقتة المنظَّمة الدائرية التي تتم صيانتها من خلال عملية النظام logd. ويتم تثبيت مجموعة الموارد الاحتياطية المتاحة وتحديدها من خلال النظام. الموارد الاحتياطية الأكثر صلة هي:

  • main: يحفظ معظم سجلات التطبيقات.
  • system: يُخزن الرسائل الصادرة من نظام التشغيل Android.
  • crash: تخزين سجلّات الأعطال لكل إدخال في السجلّ أولوية وعلامة تحدّد أصل السجلّ ورسالة السجلّ الفعلية.

إنّ واجهة C/C++ الأساسية لنظام التسجيل هي المكتبة المشتركة liblog وعنوانها <android/log.h>. وفي النهاية، تستدعي جميع مرافق التسجيل الخاصة باللغات (بما في ذلك android.util.Log) الدالة __android_log_write. يستدعي تلقائيًا الدالة __android_log_logd_logger، التي ترسل إدخال السجلّ إلى logd باستخدام مقبس. بدءًا من المستوى 30 لواجهة برمجة التطبيقات، يمكن تغيير وظيفة التسجيل عن طريق استدعاء __android_set_log_writer. يمكنك الاطّلاع على مزيد من المعلومات في مستندات NDK.

تخضع السجلّات التي يعرضها adb logcat لأربعة مستويات من الفلترة:

فلترة وقت التجميع
قد تتم إزالة بعض السجلات بالكامل من البرنامج الثنائي وفقًا لإعدادات التحويل البرمجي. على سبيل المثال، يمكن ضبط ProGuard لإزالة الطلبات المرسَلة إلى Log.d من رمز Java.
فلترة خصائص النظام
تطلب liblog مجموعة من خصائص النظام لتحديد الحد الأدنى لمستوى الخطورة الذي يجب إرساله إلى logd. إذا كانت سجلاتك تحتوي على العلامة MyApp، يتم وضع علامة في المربّع بجانب السمات التالية ومن المتوقّع أن تحتوي على الحرف الأول من الحد الأدنى لمستوى الخطورة (V أو D أو I أو W أو E أو S لإيقاف جميع السجلّات):
  • log.tag.MyApp
  • persist.log.tag.MyApp
  • log.tag
  • persist.log.tag
فلترة التطبيقات
إذا لم يتم ضبط أي من السمات، سيستخدم liblog الحد الأدنى للأولوية الذي يتم ضبطه من خلال __android_log_set_minimum_priority. وقد تم ضبط الإعدادات التلقائية على INFO.
فلترة العرض
يتيح adb logcat استخدام فلاتر إضافية يمكنها تقليل كمية السجلات المعروضة من logd. للحصول على مزيد من التفاصيل، يمكنك الاطّلاع على القسم حول مخرجات سجلّ الفلترة.

بنية سطر الأوامر

لتشغيل logcat من خلال واجهة أوامر adb، يكون الاستخدام العام هو:

[adb] shell logcat [<option>] ... [<filter-spec>] ...

ويتوفّر أيضًا اختصار للمصطلح adb logcat، ولكنّه يتسع نطاقه ليشمل adb shell logcat.

الخيارات

لدى "logcat" الكثير من الخيارات. وتعتمد الخيارات المتاحة على إصدار نظام التشغيل للجهاز الذي تستخدمه. للاطّلاع على مساعدة بشأن logcat الخاصة بالجهاز الذي تستخدمه، يمكنك تنفيذ ما يلي:

    adb logcat --help
    

بما أنّ logcat هي أداة مخصّصة لمطوّري أنظمة التشغيل ومطوّري التطبيقات (والتي يُتوقّع أن يستخدم مطوِّرو التطبيقات "استوديو Android" بدلاً منها)، فإن العديد من الخيارات لا يمكن استخدامها إلا في root.

نتائج سجلّ الفلتر

علامة رسالة السجلّ هي سلسلة قصيرة تشير إلى مكوّن النظام الذي تنشأ منه الرسالة. على سبيل المثال، "عرض" لنظام الملف الشخصي.

الأولوية هي إحدى قيم الأحرف التالية، مرتّبة من الأولوية الأدنى إلى الأعلى:

    • V: مطوّل (أولوية أدنى)
    • D: تصحيح الأخطاء
    • I: معلومات
    • W: تحذير
    • E: خطأ
    • F: خطير
    • S: صامت (أعلى أولوية، حيث لا تتم طباعة أي شيء على الإطلاق)
  • للحصول على قائمة بالعلامات المستخدَمة في النظام مع تحديد الأولويات، شغِّل logcat وراقِب أول عمودَين من كل رسالة، على النحو التالي: <priority>/<tag>.

    في ما يلي مثال على نتيجة logcat مختصرة تم الحصول عليها باستخدام الأمر logcat -v brief output. توضِّح النتيجة أنّ الرسالة تتعلّق بمستوى الأولوية "I" وعلامة "ActivityManager":

    I/ActivityManager(  585): Starting activity: Intent { action=android.intent.action...}
    

    لخفض مخرجات السجلّ إلى مستوى يمكن إدارته، يمكنك حصر نتائج السجلّ باستخدام تعبيرات الفلاتر. تتيح لك تعبيرات الفلاتر أن توضّح للنظام تركيبات أولوية العلامات التي تهمّك. ويعيق النظام الرسائل الأخرى المتعلقة بالعلامات المحدّدة.

    ويتّبع تعبير الفلتر هذا التنسيق tag:priority ...، حيث يشير tag إلى العلامة التي تهمّك، في حين يشير priority إلى الحدّ الأدنى من مستوى الأولوية الذي يجب إعداد تقارير عنه لهذه العلامة. وتتم كتابة الرسائل الخاصة بهذه العلامة ذات الأولوية المحدّدة أو أعلى منها في السجلّ. قدِّم أي عدد من مواصفات tag:priority في تعبير فلتر واحد. سلسلة المواصفات محددة بمسافات.

    في ما يلي مثال على تعبير فلتر يمنع جميع رسائل السجلّ باستثناء الرسائل التي تحتوي على العلامة "ActivityManager" في الأولوية "Info" أو أعلى، وتلك التي تحتوي على العلامة "MyApp" ذات الأولوية "Debug" أو أعلى:

    adb logcat ActivityManager:I MyApp:D *:S
    

    يضبط العنصر الأخير في التعبير السابق، *:S، مستوى الأولوية لجميع العلامات على "صامت"، ما يضمن عرض الرسائل المسجّلة التي تحتوي على "ActivityManager" و "MyApp" فقط. يضمن استخدام السمة *:S أن تقتصر نتائج السجلّ على الفلاتر التي حدّدتها صراحةً. يتيح تطبيق *:S استخدام الفلاتر كقائمة مسموح بها لنتائج السجلّ.

    ملاحظة: في بعض وحدات التحكّم، يتم حجز الحرف "*" بواسطة واجهة الأوامر. إذا كنت تستخدم واجهة أوامر مشابهة، ضمِّن تعبير الفلتر بين علامتَي اقتباس: adb logcat "ActivityManager:I MyApp:D *:S".

    يعرض تعبير الفلتر التالي جميع رسائل السجلّ التي تتضمن "تحذيرًا" بمستوى الأولوية والأعلى في جميع العلامات:

    adb logcat *:W
    

    إذا كنت تشغّل logcat من كمبيوتر التطوير بدلاً من تشغيله على واجهة أوامر adb بعيدة، يمكنك أيضًا ضبط تعبير فلتر تلقائي من خلال تصدير قيمة لمتغير البيئة ANDROID_LOG_TAGS:

    export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"
    

    لا يتم تصدير الفلتر ANDROID_LOG_TAGS إلى المحاكي/الجهاز في حال تشغيل logcat من واجهة مستخدم بعيدة أو استخدام adb shell logcat.

    تنسيق إخراج سجلّ التحكّم

    تحتوي رسائل السجلّ على عدد من حقول البيانات الوصفية بالإضافة إلى العلامة والأولوية. يمكنك تعديل تنسيق الإخراج للرسائل بحيث تعرض حقل بيانات وصفية معيّنًا. لإجراء ذلك، استخدِم الخيار -v وحدِّد أحد تنسيقات الإخراج المتوافقة التالية:

    • brief: يعرض هذا المقياس الأولوية والعلامة ومعرّف PID للعملية التي تؤدي إلى إرسال الرسالة.
    • long: يعرض جميع حقول البيانات الوصفية ويفصل الرسائل بسطور فارغة.
    • process: يعرض معرّف PID فقط.
    • raw: يعرض رسالة السجلّ الأولية بدون حقول بيانات وصفية أخرى.
    • tag: يعرض هذا الخيار الأولوية والعلامة فقط.
    • thread: تنسيق قديم يعرض الأولوية وPID وTID لسلسلة المحادثات التي تصدر الرسالة.
    • threadtime (الخيار التلقائي): يعرض التاريخ ووقت الاستدعاء والأولوية والعلامة وPID وTID لسلسلة المحادثات التي أصدرت الرسالة.
    • time: لعرض تاريخ ووقت الاستدعاء والأولوية والعلامة ومعرّف PID للعملية التي تُصدر الرسالة.

    عند بدء logcat، حدِّد تنسيق الإخراج الذي تريده باستخدام خيار -v:

    [adb] logcat [-v <format>]
    

    في ما يلي مثال يوضّح كيفية إنشاء رسائل بتنسيق الإخراج thread:

    adb logcat -v thread
    

    يمكنك تحديد تنسيق واحد فقط للإخراج باستخدام الخيار -v. ومع ذلك، يمكنك تحديد أي عدد تريده من المعدِّلات، شرط أن تكون منطقية. يتجاهل logcat أدوات التعديل التي لا معنى لها.

    معدِّلات التنسيق

    وتُغيّر معدِّلات التنسيق إخراج logcat. لتحديد معدِّل التنسيق، استخدِم الخيار -v على النحو التالي:

    adb logcat -b all -v color -d
    

    تتضمّن كل رسالة في سجلّ Android علامة وأولوية مرتبطة بها. يمكنك الجمع بين أي معدِّل تنسيق مع أي من خيارات التنسيق التالية:

    • brief
    • long
    • process
    • raw
    • tag
    • thread
    • threadtime
    • time

    لتنسيق تفاصيل عنصر التعديل التالية، أدخِل logcat -v --help في سطر الأوامر:

    • color: تعرض كل مستوى من مستويات الأولوية بلون مختلف.
    • descriptive: يعرض أوصاف أحداث المخزن المؤقت للسجلات. ويؤثر هذا المعدِّل فقط في رسائل المخزن المؤقت لسجلات الأحداث وليس له أي تأثير في المخازن المؤقتة الأخرى غير الثنائية. تأتي أوصاف الفعاليات من قاعدة بيانات علامات سجلّ الفعاليات.
    • epoch: لعرض الوقت بالثواني بدءًا من 1 كانون الثاني (يناير) 1970.
    • monotonic: لعرض الوقت بوحدة المعالجة المركزية (CPU) بدءًا من آخر تشغيل.
    • printable: يضمن هذا الإجراء تخطّي أي محتوى تسجيل ثنائي.
    • uid: يتم عرض المعرّف الفريد للمنتج أو معرّف Android للعملية التي يتم تسجيلها في حال كانت عناصر التحكّم في الوصول تسمح بذلك.
    • usec: لعرض الوقت بدقة بالميكرو ثانية.
    • UTC: لعرض الوقت بالتوقيت العالمي المنسّق (UTC).
    • year: لإضافة السنة إلى الوقت المعروض
    • zone: لإضافة المنطقة الزمنية المحلية إلى الوقت المعروض.

    عرض المخازن المؤقتة البديلة للسجلات

    يحتفظ نظام تسجيل Android بالعديد من المخازن المؤقتة الدائرية لرسائل السجلّ، ولا يتم إرسال جميع رسائل السجلّ إلى المخزن المؤقت التلقائي الدائري. لعرض رسائل السجلّ الإضافية، شغِّل الأمر logcat مع الخيار -b لطلب عرض مخزن مؤقت دائري بديل. يمكنك عرض أي من الموارد الاحتياطية البديلة التالية:

    • radio: لعرض المخزن المؤقت الذي يحتوي على رسائل ذات صلة بالراديو/الاتصال الهاتفي.
    • events: يعرض رسائل المخزن المؤقت لأحداث النظام الثنائي المفسَّر.
    • main: يعرض المخزن المؤقت للسجلات الرئيسية (التلقائي)، والذي لا يحتوي على رسائل النظام وسجلّ الأعطال.
    • system: يعرض المخزن المؤقت لسجلات النظام (الإعداد التلقائي).
    • crash: يعرض المخزن المؤقت لسجلات الأعطال (التلقائي).
    • all: يعرض كل المخازن المؤقتة.
    • default: التقارير عن الموارد الاحتياطية main وsystem وcrash

    استخدام الخيار -b هو:

    [adb] logcat [-b <buffer>]
    

    في ما يلي مثال على كيفية عرض مخزن مؤقت للسجلات يحتوي على رسائل الراديو والرسائل الهاتفية:

    adb logcat -b radio
    

    لتحديد علامات -b متعدّدة لجميع المخازن المؤقتة التي تريد طباعتها، أدخِل ما يلي:

    logcat -b main -b radio -b events
    

    يمكنك تحديد علامة -b واحدة مع قائمة من المخازن المؤقتة مفصولة بفواصل، على سبيل المثال:

    logcat -b main,radio,events
    

    تسجيل من الرمز

    تتيح لك الفئة Log إنشاء إدخالات السجلّ في الرمز الخاص بك والتي يتم عرضها في أداة logcat. تتضمن طرق التسجيل الشائعة ما يلي:

    على سبيل المثال، باستخدام الاستدعاء التالي:

    Kotlin

    Log.i("MyActivity", "MyClass.getView() — get item number $position")
    

    Java

    Log.i("MyActivity", "MyClass.getView() — get item number " + position);
    

    ناتج "logcat" مشابه لما يلي:

    I/MyActivity( 1557): MyClass.getView() — get item number 1