Logcat — این چیست، سطوح لاگ‌گیری و کار با لاگ‌ها

Logcat در Android چیست

Logcat — بافر سیستمی Android است که تمام فرآیندها (شامل هسته Linux، system_server و برنامه‌ها) پیام‌هایی با فرمت مشخص در آن می‌نویسند. ابزار logcat که بخشی از Android SDK است، این بافر را می‌خواند و پیام‌ها را در زمان واقعی نمایش می‌دهد. از Android 4.1 (API 16) دسترسی به Logcat محدود شده است: برنامه‌ها فقط می‌توانند لاگ‌های خود را بخوانند و لاگ‌های سیستمی از طریق ADB با دسترسی debug در دسترس هستند.

هر پیام Logcat شامل پنج فیلد است: تاریخ و زمان، PID (شناسه فرآیند)، TID (شناسه نخ)، سطح لاگ‌گیری و برچسب. فرمت ثابت و برای همه نسخه‌های Android یکسان است. این امکان استفاده از ابزارهای grep، awk و sed را برای فیلتر کردن لاگ‌ها در pipelineهای CI/CD بدون وابستگی به IDE فراهم می‌کند.

لاگ‌ها در بافر حلقوی با اندازه ثابت ذخیره می‌شوند: 256 کیلوبایت برای main، 256 کیلوبایت برای system و 256 کیلوبایت برای events (Android 5+). هنگام پر شدن بافر، پیام‌های قدیمی حذف می‌شوند. توسعه‌دهنده می‌تواند اندازه بافر را از طریق PROP logcat.size یا در تنظیمات توسعه‌دهنده دستگاه تغییر دهد.

سطوح لاگ و برچسب‌ها: ساختار پیام Logcat

شش سطح لاگ‌گیری اهمیت پیام را تعیین می‌کنند. Android از سطوح استاندارد مشابه سایر پلتفرم‌ها استفاده می‌کند، اما با نام‌های ثابت خود در کلاس Log. انتخاب سطح مناسب به فیلتر کردن مؤثر لاگ‌ها و غرق نکردن پیام‌های بحرانی در پیام‌های فرعی کمک می‌کند.

برچسب‌ها: سازماندهی پیام‌ها بر اساس ماژول

برچسب (tag) — رشته‌ای تا ۲۳ کاراکتر که منبع پیام را شناسایی می‌کند. توصیه می‌شود از نام کلاس یا ماژول به عنوان برچسب استفاده کنید: MainActivity، AuthManager، NetworkModule. این امکان فیلتر کردن لاگ‌ها را بر اساس مؤلفه خاصی از برنامه فراهم می‌کند. برای یکپارچگی در تیم می‌توان ثابت‌های برچسب را در یک فایل جداگانه ایجاد کرد یا از کتابخانه Timber استفاده کرد که به طور خودکار برچسب را بر اساس نام کلاس قرار می‌دهد.

لاگ‌های crash و stack trace استثنا

در استثنای مدیریت‌نشده، Android خودش در Logcat یک stack trace کامل با مشخص کردن کلاس، متد، خط کد و زنجیره فراخوانی می‌نویسد. لاگ crash شامل نوع استثنا (NullPointerException، RuntimeException)، پیام و دنباله فراخوانی‌ها از نقطه خرابی تا نقطه ورودی برنامه است. برای تحلیل لاگ‌های crash از دستگاه‌های کاربران از Firebase Crashlytics استفاده می‌شود که stack trace را با نقشه مبهم‌سازی (mapping.txt برای Android) همگام‌سازی می‌کند.

Logcat در Android Studio: رابط، فیلترها و جستجو

Android Studio رابط گرافیکی Logcat را از طریق View → Tool Windows → Logcat (Alt + 6) فراهم می‌کند. پنجره Logcat در زمان واقعی به‌روزرسانی می‌شود، تمام پیام‌های دستگاه متصل را نشان می‌دهد و امکان پیکربندی فیلترهای انعطاف‌پذیر برای جداسازی اطلاعات مورد نیاز از جریان کلی را فراهم می‌کند.

فیلتر بر اساس سطح و برچسب

لیست کشویی Log Level پیام‌ها را بر اساس حداقل سطح فیلتر می‌کند: WARN را انتخاب کنید تا فقط هشدارها و خطاها را ببینید و VERBOSE، DEBUG و INFO را پنهان کنید. فیلد Search امکان جستجوی متن پیام یا برچسب را فراهم می‌کند — از regex پشتیبانی می‌کند که برای جستجوی پیام‌ها بر اساس الگو مفید است.

فیلترهای ذخیره شده

Saved Filters — ویژگی قدرتمند Logcat در Android Studio. می‌توانید فیلتری ایجاد کنید که فقط پیام‌های دارای برچسب برنامه شما (tag:MyApp) و سطح WARN+ را نشان دهد. فیلترها بین جلسات ذخیره می‌شوند و از لیست کشویی قابل دسترسی هستند. برای پروژه‌های با چند ماژول، برای هر ماژول یک فیلتر جداگانه ایجاد کنید.

# عبارت نمونه برای فیلتر کردن لاگ‌های برنامه
tag:"MyApp" level:WARN # فقط WARN+ برای MyApp
package:"com.mycompany" # همه لاگ‌های پکیج
-tag:"okhttp" # حذف لاگ‌های OkHttp

خروجی و تحلیل

لاگ‌های Logcat را می‌توان از طریق آیکون Save to File به یک فایل متنی خروجی گرفت. این برای پیوست کردن به تیکت‌های Jira یا تحلیل جلسات طولانی مفید است. لاگ خروجی‌گرفته شده را می‌توان در هر ویرایشگر متنی باز کرد و از grep برای جستجوی الگوها استفاده کرد. برای مشاهده فرمت‌بندی شده از ابزار logcat-color استفاده کنید.

ADB logcat: دستورات ترمینال برای کار پیشرفته

ADB logcat — نسخه کنسولی Logcat است که از طریق Android Debug Bridge قابل دسترسی است. مزیت اصلی آن امکان اجرا بر روی سرورهای CI، در اسکریپت‌های خودکار و روی دستگاه‌های بدون Android Studio است. ADB logcat از همان فیلترهای GUI پشتیبانی می‌کند، اما با انعطاف‌پذیری خط فرمان.

دستورات پایه

دستور adb logcat بدون آرگومان کل بافر را در زمان واقعی نمایش می‌دهد. برای توقف از Ctrl+C استفاده کنید. پرچم -c بافر را قبل از شروع ضبط پاک می‌کند — این زمانی مفید است که باید لاگ‌های تست فعلی را از پیام‌های قبلی جدا کنید. پرچم -b نوع بافر را انتخاب می‌کند: main، system، events، crash (Android 12+).

# پاک کردن بافر و شروع ضبط لاگ‌ها با برچسب MyApp
adb logcat -c
adb logcat MyApp:D *:S

# ذخیره لاگ‌ها در فایل
adb logcat -d > logcat_dump.txt

# فیلتر کردن بر اساس PID فرآیند
adb logcat --pid=12345

فیلتر با grep و awk

ترکیب ADB با ابزارهای یونیکس حداکثر انعطاف‌پذیری را می‌دهد. به عنوان مثال، فیلتر "*:S TAG:D" فقط پیام‌های دارای برچسب TAG با سطح DEBUG و بالاتر را نشان می‌دهد و بقیه را پنهان می‌کند. برای مشاهده فقط Exception از grep -i exception استفاده کنید. برای تحلیل فراوانی خطاها sort | uniq -c را در ستون برچسب اعمال کنید.

Logcat در CI/CD

در سرورهای CI از Logcat برای جمع‌آوری اطلاعات تشخیصی هنگام اجرای تست‌های UI استفاده می‌شود. pipeline معمولی: قبل از اجرای تست‌ها بافر پاک می‌شود، پس از اجرای تست‌ها dump لاگ‌ها به عنوان مصنوع ساخت ذخیره می‌شود. اگر تست ناموفق باشد، بر اساس لاگ‌ها می‌توان تشخیص داد که آیا شکست ناشی از ANR، استثنای مدیریت‌نشده یا timeout شبکه بوده است.

لاگ‌گیری در کد: Log.d, Log.e و Timber

کلاس android.util.Log — API داخلی برای نوشتن پیام‌ها در Logcat. Log.v, Log.d, Log.i, Log.w, Log.e و Log.wtf برچسب (رشته) و پیام (رشته) یا پیام + Throwable دریافت می‌کنند. برای قالب‌بندی پیام‌ها از String.format یا Kotlin String templates استفاده کنید — از الحاق رشته‌ها که اشیاء اضافی در heap ایجاد می‌کند خودداری کنید.

کتابخانه Timber

Timber — کتابخانه محبوب Jake Wharton که نقص‌های API داخلی Log را برطرف می‌کند. Timber به طور خودکار برچسب را بر اساس نام کلاسی که لاگ‌گیری را فراخوانی کرده قرار می‌دهد و نیازی به ارسال برچسب در هر فراخوانی ندارد. Timber همچنین از لاگ‌گیری شرطی پشتیبانی می‌کند: در ساخت Release می‌توان فراخوانی‌های Timber.v و Timber.d را با یک خط در Application.onCreate غیرفعال کرد.

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // API لاگ داخلی
        Log.d("MainActivity", "onCreate called")

        // Timber — برچسب خودکار بر اساس نام کلاس
        Timber.d("onCreate called")
    }

    private fun loadData() {
        try {
            val result = fetchFromNetwork()
            Timber.i("Data loaded: $result")
        } catch (e: IOException) {
            Timber.e(e, "Failed to load data")
        }
    }
}

لاگ‌گیری شرطی برای Release

در ساخت Release توصیه می‌شود لاگ‌های VERBOSE و DEBUG را غیرفعال کنید تا بار بافر Logcat کاهش یابد و نشت اطلاعات حساس حذف شود. Timber این کار را از طریق PlantingTree حل می‌کند: در flavor Debug درخت DebugTree (همه چیز را لاگ می‌کند) و در Release درخت CrashReportingTree (فقط ERROR را از طریق Crashlytics لاگ می‌کند) کاشته می‌شود. API داخلی Log از لاگ‌گیری شرطی پشتیبانی نمی‌کند — توسعه‌دهنده باید هر فراخوانی را با if (BuildConfig.DEBUG) احاطه کند.