این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ابزار خط فرمان Logcat

Logcat یک ابزار خط فرمان است که گزارشی از پیام‌های سیستم از جمله پیام‌هایی را که از برنامه خود با کلاس Log نوشته‌اید حذف می‌کند.

این صفحه در مورد ابزار خط فرمان logcat است، اما شما همچنین می توانید پیام های گزارش را از پنجره Logcat در Android Studio مشاهده کنید. برای اطلاعات در مورد مشاهده و فیلتر کردن گزارش‌ها از Android Studio، مشاهده و نوشتن گزارش‌ها با Logcat را ببینید.

نمای کلی سیستم ورود به سیستم

سیستم لاگ اندروید مجموعه ای از بافرهای دایره ای ساختار یافته است که توسط logd فرآیند سیستم نگهداری می شود. مجموعه بافرهای موجود توسط سیستم ثابت و تعریف شده است. مرتبط ترین بافرها عبارتند از:

main : اکثر گزارش های برنامه را ذخیره می کند.
system : پیام هایی را که از سیستم عامل اندروید نشات می گیرند ذخیره می کند.
crash : گزارش‌های خرابی را ذخیره می‌کند. هر ورودی گزارش دارای یک اولویت است، یک برچسب که مبدأ گزارش را مشخص می کند و پیام واقعی گزارش را مشخص می کند.

رابط اصلی C/C++ برای سیستم گزارش‌گیری، liblog کتابخانه مشترک و هدر آن <android/log.h> است. همه امکانات ثبت‌نام مخصوص زبان (از جمله android.util.Log ) در نهایت تابع __android_log_write فراخوانی می‌کنند. به طور پیش‌فرض، تابع __android_log_logd_logger را فراخوانی می‌کند که ورودی گزارش را با استفاده از یک سوکت به logd می‌فرستد. با شروع API سطح 30، عملکرد گزارش‌گیری را می‌توان با فراخوانی __android_set_log_writer تغییر داد. اطلاعات بیشتر در اسناد NDK موجود است.

گزارش های نمایش داده شده توسط adb logcat تحت چهار سطح فیلتر قرار می گیرند:

فیلتر زمان کامپایل: بسته به تنظیمات کامپایل، برخی از گزارش‌ها ممکن است به طور کامل از باینری حذف شوند. به عنوان مثال، ProGuard را می توان طوری پیکربندی کرد که تماس های Log.d را از کد جاوا حذف کند.
فیلتر ویژگی سیستم: liblog مجموعه‌ای از ویژگی‌های سیستم را جستجو می‌کند تا حداقل سطح شدت را برای ارسال به logd تعیین کند. اگر گزارش‌های شما دارای برچسب MyApp هستند، ویژگی‌های زیر بررسی می‌شوند و انتظار می‌رود که حاوی حرف اول حداقل شدت باشد ( V ، D ، I ، W ، E ، یا S برای غیرفعال کردن همه گزارش‌ها):
فیلتر کردن برنامه: اگر هیچ یک از ویژگی ها تنظیم نشده باشد، 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 قابل استفاده هستند.

خروجی ورود به سیستم فیلتر

تگ یک پیام گزارش یک رشته کوتاه است که مؤلفه سیستم را نشان می دهد که پیام از آنجا منشأ می گیرد. به عنوان مثال، "نمایش" برای سیستم نمایش.

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

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"

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

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

پیام‌های گزارش شامل تعدادی فیلد فراداده علاوه بر برچسب و اولویت هستند. می‌توانید قالب خروجی پیام‌ها را طوری تغییر دهید که یک فیلد فوق‌داده خاص را نمایش دهند. برای انجام این کار، از گزینه -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

هر پیام لاگ اندروید دارای یک برچسب و اولویت مرتبط با آن است. می توانید هر اصلاح کننده فرمت را با یکی از گزینه های قالب زیر ترکیب کنید:

brief
long
process
raw
tag
thread
threadtime
time

برای قالب بندی جزئیات اصلاح کننده زیر، logcat -v --help در خط فرمان وارد کنید:

color : هر سطح اولویت را با رنگ متفاوتی نشان می دهد.
descriptive : شرح رویداد بافر گزارش را نشان می دهد. این اصلاح کننده فقط بر پیام های بافر گزارش رویداد تأثیر می گذارد و تأثیری بر سایر بافرهای غیر باینری ندارد. توضیحات رویداد از پایگاه داده رویداد-log-tags آمده است.
epoch : زمان را بر حسب ثانیه از اول ژانویه 1970 نشان می دهد.
monotonic : زمان را بر حسب ثانیه CPU نشان می دهد که از آخرین بوت شروع می شود.
printable : اطمینان حاصل می کند که هر گونه محتوای ورود به سیستم باینری فرار شده است.
uid : اگر توسط کنترل های دسترسی مجاز باشد، UID یا شناسه Android فرآیند ثبت شده را نمایش می دهد.
usec : زمان را با دقت در میکروثانیه نمایش می دهد.
UTC : زمان را به صورت UTC نمایش می دهد.
year : سال را به زمان نمایش داده شده اضافه می کند.
zone : منطقه زمانی محلی را به زمان نمایش داده شده اضافه می کند.

مشاهده بافرهای لاگ جایگزین

سیستم لاگ اندروید چندین بافر دایره‌ای را برای پیام‌های گزارش نگه می‌دارد و همه پیام‌های گزارش به بافر دایره‌ای پیش‌فرض ارسال نمی‌شوند. برای مشاهده پیام‌های گزارش اضافی، دستور 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