أداة سطر أوامر 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" "معلومات" ذات الأولوية أو أعلى وتلك التي تحتوي على العلامة "تطبيقي" ذات الأولوية "تصحيح الأخطاء" أو أعلى:

    adb logcat ActivityManager:I MyApp:D *:S

    يعيّن العنصر الأخير في التعبير السابق، *:S، مستوى الأولوية جميع العلامات إلى "silent"، مما يضمن تسجيل الرسائل باستخدام "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: يعرض الوقت في وحدة المعالجة المركزية بالثواني بدءًا من آخر تشغيل.
    • 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