ابزار خط فرمان 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 ارسال می‌کند. از سطح میانای برنامه‌سازی کاربردی ۳۰، عملکرد گزارش‌گیری را می‌توان با فراخوانی __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 Studio استفاده کنند)، بسیاری از گزینه‌ها فقط به‌عنوان root قابل‌استفاده هستند.

فیلتر کردن خروجی گزارش

برچسب پیام گزارش رشته کوتاهی است که مؤلفه سیستم را که پیام از آنجا منشأ می‌گیرد نشان می‌دهد. برای مثال، «View» برای سیستم View.

اولویت یکی از مقادیر نویسه زیر است که از پایین‌ترین به بالاترین اولویت مرتب شده است:

• ‫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» با اولویت «اطلاعات» یا بالاتر دارند و پیام‌هایی که برچسب «MyApp» با اولویت «اشکال‌زدایی» یا بالاتر دارند:

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"

اگر logcat را از پوسته ازراه‌دور اجرا می‌کنید یا از adb shell logcat استفاده می‌کنید، فیلتر ANDROID_LOG_TAGS به نمونه شبیه‌ساز/دستگاه صادر نمی‌شود.

کنترل کردن قالب خروجی گزارش

پیام‌های گزارش علاوه‌بر برچسب و اولویت، حاوی تعدادی فیلد فراداده هستند. می‌توانید قالب خروجی پیام‌ها را تغییر دهید تا فیلد فراداده خاصی را نمایش دهند. برای انجام این کار، از گزینه -v استفاده کنید و یکی از قالب‌های خروجی پشتیبانی‌شده زیر را مشخص کنید:

• brief: اولویت، برچسب، و شناسه فرایند صادرکننده پیام را نمایش می‌دهد.
• long: همه فیلدهای فراداده را نمایش می‌دهد و پیام‌ها را با خطوط خالی از هم جدا می‌کند.
• process: فقط PID را نمایش می‌دهد.
• raw: پیام گزارش خام را بدون فیلدهای فراداده دیگر نمایش می‌دهد.
• tag: فقط اولویت و برچسب را نمایش می‌دهد.
• thread: قالبی قدیمی که اولویت، PID، و TID رشته صادرکننده پیام را نشان می‌دهد.
• threadtime (پیش‌فرض): تاریخ، زمان فراخوانی، اولویت، برچسب، PID، و TID رشته صادرکننده پیام را نمایش می‌دهد.
• time: تاریخ، زمان فراخوانی، اولویت، برچسب، و شناسه فرایند صادرکننده پیام را نمایش می‌دهد.

هنگام شروع 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: شرح رویدادهای میان‌گیر گزارش را نشان می‌دهد. این اصلاح‌کننده فقط بر پیام‌های میان‌گیر گزارش رویداد تأثیر می‌گذارد و بر سایر میان‌گیرهای غیردودویی تأثیری ندارد. شرح رویدادها از پایگاه داده event-log-tags گرفته می‌شود.
• ‫epoch: زمان را برحسب ثانیه از ۱ ژانویه ۱۹۷۰ نمایش می‌دهد.
• monotonic: زمان را برحسب ثانیه CPU از آخرین راه‌اندازی نمایش می‌دهد.
• printable: اطمینان حاصل می‌کند که هرگونه محتوای ثبت دودویی گریز داده شود.
• uid: اگر کنترل‌های دسترسی اجازه دهند، شناسه کاربر یا شناسه Android فرایند ثبت‌شده را نمایش می‌دهد.
• usec: زمان را با دقت میکروثانیه نمایش می‌دهد.
• 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) (خطا)

برای مثال، بااستفاده از فراخوانی زیر:

کاتلین

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

جاوا

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

logcat چیزی شبیه به موارد زیر را برونداد می‌کند:

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