عرض السجلّات باستخدام Logcat

تساعدك نافذة Logcat في "استوديو Android" في تصحيح الأخطاء في تطبيقك من خلال عرض السجلات من جهازك في الوقت الفعلي، مثل الرسائل التي أضفتها إلى تطبيقك مع الفئة Log أو الرسائل من الخدمات التي تعمل على Android أو رسائل النظام، مثلاً عند تجميع البيانات غير المرغوب فيها. عندما يقدم تطبيق استثناءً، تعرض Logcat رسالة متبوعةً بعملية تتبُّع تسلسل استدعاء الدوال البرمجية المرتبطة تحتوي على روابط إلى سطر الرمز.

بدء استخدام نافذة Logcat

لعرض رسائل السجلّ لتطبيقك، عليك إجراء ما يلي.

  1. في استوديو Android، أنشئ تطبيقك وشغِّله على جهاز أو محاكي.
  2. اختَر View (عرض) > Tool Windows (عرض أداة Windows) > Logcat من شريط القوائم.

يتم تلقائيًا تمرير Logcat إلى النهاية. يؤدي النقر على طريقة عرض Logcat أو التمرير للأعلى باستخدام عجلة الماوس إلى إيقاف هذه الميزة. لإعادة تفعيلها، انقر على الانتقال إلى End انتقِل إلى رمز النهاية. من شريط الأدوات. يمكنك أيضًا استخدام شريط الأدوات لمحو Logcat أو إيقافها مؤقتًا أو إعادة تشغيلها.

واجهة مستخدم نافذة Logcat

الشكل 1. تعمل Logcat على تنسيق السجلات لتسهيل فحص المعلومات المفيدة، مثل العلامات والرسائل، وتحديد أنواع مختلفة من السجلات، مثل التحذيرات والأخطاء.

كيفية قراءة السجلات

يحتوي كل سجل على تاريخ وطابع زمني وعملية ورقم تعريف سلسلة محادثات وعلامة واسم الحزمة والأولوية والرسالة المرتبطة به. تحتوي العلامات المختلفة على لون فريد يساعد في تحديد نوع السجل. ويكون لكل إدخال في السجلّ أولوية قدرها FATAL أو ERROR أو WARNING أو INFO أو DEBUG أو VERBOSE.

على سبيل المثال، تكون الأولوية لرسالة السجلّ التالية DEBUG وعلامة ProfileInstaller:

2022-12-29 04:00:18.823 30249-30321 ProfileInstaller        com.google.samples.apps.sunflower    D  Installing profile for com.google.samples.apps.sunflower

ضبط عرض السجلّ

يعرض عرض السجل القياسي تاريخ كل سجل والعملية الزمنية ومعرّف سلسلة المحادثات والعلامة واسم الحزمة والأولوية والرسالة المرتبطة به. وفقًا للإعدادات التلقائية، لا تكون سطور الرسائل ملتفة في عرض السجلّ، ولكن يمكنك استخدام خيار الالتفاف الجزئي رمز الالتفاف الناعم من شريط أدوات Logcat.

يمكنك التبديل إلى العرض مكثّف، والذي يحتوي على معلومات عرض تلقائية أقل، من خلال النقر على ضبط خيارات تنسيق Logcat من شريط الأدوات Logcat.

لضبط مقدار المعلومات التي تريد عرضها بشكل أكبر، اختَر تعديل طرق العرض، واختَر ما إذا كنت تريد عرض الطابع الزمني أو العلامات أو أرقام تعريف العمليات أو أسماء الحِزم.

تغيير الألوان

لتغيير الألوان، انتقِل إلى استوديو Android > الإعدادات > المحرّر > نظام الألوان. لتغيير الألوان في عرض السجلّ، اختَر Android Logcat. لتغيير ألوان الفلتر، اختَر فلتر Logcat.

خيارات الضبط الإضافية

للحصول على خيارات ضبط إضافية، انتقِل إلى استوديو Android > الإعدادات > الأدوات > Logcat. من هنا، يمكنك اختيار حجم المخزن المؤقت لدورة Logcat والفلتر التلقائي لنوافذ Logcat الجديدة، وما إذا كنت تريد إضافة فلاتر من السجلّ إلى الإكمال التلقائي.

استخدام Logcat في نوافذ متعددة

تساعدك علامات التبويب على التبديل بسهولة بين الأجهزة أو طلبات البحث المختلفة. يمكنك إنشاء عدة علامات تبويب Logcat من خلال النقر على علامة تبويب جديدة رمز "علامة تبويب جديدة". يتيح لك النقر بزر الماوس الأيمن على علامة تبويب إعادة تسميتها وإعادة ترتيبها.

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

نوافذ Logcat متعددة الشكل 2. قسِّم نوافذ Logcat في "استوديو Android".

من شريط أدوات Logcat، يمكنك إمّا التمرير إلى نهاية السجلّات، أو يمكنك النقر على سطر معيّن لإبقاء هذا السطر مرئيًا.

في Android Studio، يمكنك إجراء عمليات بحث ذات قيمة أساسية من حقل طلب البحث الرئيسي مباشرةً. يوفر نظام الاستعلام هذا دقة ما تريد الاستعلام عنه وكذلك استبعاد السجلات بناءً على القيم الأساسية. بينما لديك خيار استخدام التعبيرات العادية، فلا تضطر إلى الاعتماد عليها في الاستعلامات. للاطّلاع على الاقتراحات، اضغط على Ctrl + Space في حقل طلب البحث.

قائمة الاقتراحات في حقل طلب البحث الشكل 3. اضغط على Ctrl + Space في حقل طلب البحث للاطّلاع على قائمة بطلبات البحث المقترَحة.

فيما يلي بعض الأمثلة على المفاتيح التي يمكنك استخدامها في استعلامك:

  • tag: يتطابق مع الحقل tag في إدخال السجلّ.
  • package: يتطابق مع اسم الحزمة لتطبيق التسجيل.
  • process: يتطابق مع اسم العملية لتطبيق التسجيل.
  • message: يتطابق مع جزء الرسالة في إدخال السجلّ.
  • level: يطابق مستوى السجلّ المحدَّد أو الأعلى، مثلاً DEBUG.
  • age: يتطابق مع ما إذا كان الطابع الزمني للإدخال حديثًا. يتم تحديد القيم كرقم متبوعًا بحرف يحدد الوحدة الزمنية: s للثواني وm للدقائق وh للساعات وd للأيام. على سبيل المثال، يعمل age: 5m على فلترة الرسائل التي تم تسجيلها في آخر 5 دقائق فقط.

النفي والتعبيرات العادية

تتيح الحقول التالية استخدام خاصية النفي ومطابقة التعبير العادي: tag وpackage وmessage وline.

يتم التعبير عن النفي من خلال إضافة - في البداية إلى اسم الحقل. على سبيل المثال، يطابق -tag:MyTag إدخالات السجلّ التي لا يحتوي tag على السلسلة فيها MyTag.

يتم التعبير عن مطابقة التعبير العادي من خلال إلحاق ~ باسم الحقل. مثلاً: tag~:My.*Tag

يمكن الجمع بين النفي ومُعدِّلات التعبير العادي. مثلاً، -tag~:My.*Tag.

العوامل المنطقية والأقواس

تتوافق لغة طلب البحث مع عاملَي التشغيل AND وOR اللذين يتم التعبير عنهما باستخدام & و| والأقواس. مثلاً:

(tag:foo | level:ERROR) & package:mine

تجدر الإشارة إلى أنّه يتم فرض أولوية عامل التشغيل العادية، وبالتالي ما يلي:

tag:foo | level:ERROR & package:mine

يتم تقييمه على أنّه:

tag:foo | (level:ERROR & package:mine)

العوامل المنطقية الضمنية

في حال عدم تطبيق عوامل التشغيل المنطقية، ستقيّم لغة طلب البحث تلقائيًا عبارات متعددة من فلاتر key-value غير مُلغاة باستخدام المفتاح نفسه مثل OR، وكل العناصر الأخرى باستخدام AND.

مثلاً:

tag:foo tag:bar package:myapp

يتم تقييمه على أنّه:

(tag:foo | tag:bar) & package:myapp

مع ذلك:

tag:foo -tag:bar package:myapp

يتم تقييمه على أنّه:

tag:foo & -tag:bar & package:myapp

إذا تم فصل عبارات طلبات بحث متعددة بمسافة بيضاء بدون عامل تشغيل منطقي، سيتم التعامل معها باعتبارها حرف AND ذات أولوية منخفضة. على سبيل المثال، المصطلح foo bar tag:bar1 | tag:bar2 يوازي 'foo bar' & (tag: bar1 | tag: bar2).

طلبات البحث الخاصة

package:mine

يتيح مفتاح الحزمة استخدام قيمة خاصة mine. تتطابق هذه القيمة الخاصة مع أي أسماء حزم مضمنة في المشروع المفتوح.

level

يتطابق طلب البحث level مع مستوى السجلّ لرسالة Logcat، حيث يكون مستوى إدخال السجلّ أكبر من مستوى طلب البحث أو مساويًا له.

على سبيل المثال، يتطابق level:INFO مع أي إدخال في السجلّ بمستوى سجلّ INFO أو WARN أو ERROR أو ASSERT. المستوى غير حسّاس لحالة الأحرف. المستويات الصالحة هي: VERBOSE وDEBUG وINFO وWARN وERROR وASSERT.

age

يتطابق طلب البحث age مع الإدخالات بناءً على طابعها الزمني، ويتم تنسيقه على النحو التالي age:<number><unit>، حيث يشير

  • <number> هو عدد صحيح
  • <unit> هو واحد من s وm وh وd (الثواني والدقائق والساعات والأيام).

وفقًا للقائمة التالية، يتطابق طلب البحث age مع رسائل السجلّ التي تحتوي على طابع زمني في النطاق الموضّح في القيمة. على سبيل المثال: يتطابق طلب البحث age:5m مع الإدخالات ذات الطابع الزمني قبل 5 دقائق على الأكثر.

age:30s
age:5m
age:3h
age:1d

يُرجى العِلم أنّه تتم مقارنة الطابع الزمني بالطابع الزمني للمضيف، وليس بالجهاز المتصل به. إذا لم يتم ضبط وقت الجهاز بشكل صحيح، فقد لا يعمل هذا الاستعلام كما هو متوقع.

مفتاح is

يمكنك استخدام مفتاح is على النحو التالي:

  • يطابق is:crash إدخالات السجلّ التي تمثل تعطُّل التطبيق (سواء كان أصليًا أو بلغة Java).
  • يطابق is:stacktrace إدخالات السجلّ التي تمثل أي شيء يشبه تتبُّع تكديس Java، بغض النظر عن مستوى السجلّ.

مفتاح name

يتيح لك المفتاح name تقديم اسم فريد لفلتر محفوظ حتى يسهل التعرّف عليه في القائمة المنسدلة لسجلّ الفلاتر. على الرغم من عدم ظهور خطأ لتحديد name أكثر من مرة، لا يستخدم بيئة التطوير المتكاملة سوى آخر قيمة محدّدة لـ name في طلب البحث.

عرض سجلّ طلبات البحث

يمكنك عرض سجلّ طلبات البحث بالنقر على عرض السجلّ رمز الفلتر بجانب حقل طلب البحث. لإضافة استعلام إلى المفضلة بحيث يبقى في أعلى القائمة عبر جميع مشاريع الاستوديو، انقر على النجمة بجانبه. يمكنك أيضًا استخدام المفتاح name: لتسهيل التعرّف على طلبات البحث المفضّلة. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على طلبات البحث الخاصة.

واجهة مستخدم لوضع طلب بحث في المفضّلة

الشكل 4. يمكنك إضافة طلب بحث إلى المفضّلة من خلال النقر على النجمة التي بجانبه.

تتبُّع السجلات المتعلّقة بأعطال التطبيق وإعادة تشغيله

عندما تلاحظ Logcat أن عملية تطبيقك قد توقفت وإعادة تشغيلها، فإنها تعرض رسالة في الإخراج، مثل PROCESS ENDED وPROCESS STARTED. يؤدي إعادة تشغيل Logcat إلى الاحتفاظ بإعدادات الجلسة، مثل تقسيم علامات التبويب والفلاتر وخيارات العرض، كي تتمكّن من متابعة الجلسة بسهولة.

نافذة Logcat لأعطال التطبيق

الشكل 5. عند إعادة تشغيل عملية التطبيق، تطبع Logcat رسالة تفيد بأن العملية قد انتهت ثم بدأت.