أداة 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
. تشمل طرق التسجيل الشائعة ما يلي:
Log.v(String, String)
(مطوَّل)Log.d(String, String)
(تصحيح الأخطاء)Log.i(String, String)
(معلومات)Log.w(String, String)
(تحذير)Log.e(String, String)
(خطأ)
على سبيل المثال، باستخدام المكالمة التالية:
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