Timber — bu nima, kutubxona API-si va foydalanish misollari

Timber nima

Timber — 2013 yilda Jeyk Uorton (Jake Wharton) tomonidan standart android.util.Log ga muqobil sifatida yaratilgan Android uchun ochiq kodli kutubxona. Timber ning asosiy g'oyasi — majburiy qo'lda tag bilan statik Log API ni chaqiruv manbasini stek orqali aniqlaydigan avtomatik mexanizm bilan almashtirish.

Kutubxona Composite daraxtlar (Tree) bilan arxitektura namunasi asosida qurilgan. Ruxsat etilgan xatti-harakatga ega yagona Log sinfi o'rniga, Timber daraxtlardan iborat “o'rmon” ni boshqaradi — har bir daraxt o'z chiqish kanali uchun javobgardir: konsol, fayl, Crashlytics, uzoq server. Dasturchi istalgan miqdordagi daraxtlarni qo'shib, ularni birlashtirishi mumkin.

Google I/O 2019 ma'lumotlariga ko'ra, Timber Google tomonidan Android ilovalarida loglash uchun eng yaxshi amaliyot sifatida tavsiya etilgan. Kutubxona APKda 10 KB dan kam joy egallaydi va tashqi bog'liqliklarga ega emas, bu uni istalgan miqyosdagi loyihalar uchun ideal tanlovga aylantiradi.

Timber katta jamoalarda mos kelmaydigan taglar muammosini hal qiladi. Har bir dasturchi tag ni qo'lda yozganda, imlo xatolari va tafovutlar muqarrar — bir sinf “MainActivity”, boshqasi “MAIN_ACTIVITY” sifatida loglanadi. Timber avtomatik ravishda tag ni sinf nomidan chiqaradi:MainActivity.kt → tag MainActivity.

Timber arxitekturasi: daraxtlar va o'rmon

Timber arxitekturasi ikkita komponentdan iborat: markaziy statik sinf Timber va abstrakt sinf Timber.Tree. Timber fasad vazifasini bajaradi, har bir log chaqiruvini barcha ekilgan (planted) daraxtlarga topshiradi. Har bir daraxt xabarni qayta ishlash kerakmi yoki yo'qmi va agar kerak bo'lsa — uni qayerga yo'naltirishni hal qiladi.

DebugTree — ishlab chiqish uchun o'rnatilgan implementatsiya

DebugTree — kutubxona bilan taqdim etiladigan standart Tree implementatsiyasi. U tag ni chaqiruv stekini tahlil qilish orqali aniqlaydi: Timber.d() chaqiruv nuqtasidan 8 ramka yuqoriga ko'tariladi va log metodini chaqirgan sinf nomini topadi. DebugTree release qurilmalarida avtomatik ravishda o'chadi (hech narsa chiqarmaydi), chunki BuildConfig.DEBUG ni tekshiradi.

“O'rmon” ning ishlash printsipi

Forest (o'rmon) — barcha ekilgan daraxtlarning to'plami. Timber.d(“message”) metodi chaqirilganda, kutubxona xabarni ekish tartibida barcha daraxtlarga iterativ ravishda uzatadi. Har bir daraxt xabarni daraja, tag yoki mazmun bo'yicha filtrlashi va o'z usulida qayta ishlashi mumkin.

Ekish tartibi muhim: birinchi ekilgan daraxt birinchi bo'lib qayta ishlanadi. Maxsus daraxtlar (masalan, Crashlytics) xabarni Logcatga tushishdan oldin qayta ishlashi uchun DebugTree ni oxirgi ekish tavsiya etiladi.

Ip xavfsizligi

Timber ip xavfsiz — barcha metodlar ichki qulf orqali sinxronlashtirilgan. Bu turli iplardan kelgan xabarlarning aralashmasligini kafolatlaydi. Biroq, maxsus daraxt ichida sinxronizatsiya dasturchi zimmasiga tushadi: agar daraxt faylga yozsa, synchronized yoki ReentrantLock dan foydalanish kerak.

// Application.onCreate da daraxtlar o'rmonini inicializatsiya qilish
class App : Application() {
    override fun onCreate() {
        super.onCreate()

        if (BuildConfig.DEBUG) {
            Timber.plant(Timber.DebugTree())
        }

        Timber.plant(CrashReportingTree())
        Timber.plant(FileLoggingTree())

        Timber.i("Timber planted with 3 trees")
    }
}

Timber ni Android loyihasida o'rnatish va sozlash

Timber ni o'rnatish build.gradle ga bitta bog'liqlik qo'shish orqali amalga oshiriladi. Kutubxona Maven Central da com.jakewharton.timber:timber artefakti ostida nashr etilgan. 2024 yil uchun joriy versiya — 5.0.1, oxirgi barqaror yangilanish.

// build.gradle (Module: app)
dependencies {
    implementation 'com.jakewharton.timber:timber:5.0.1'
}

O'rnatishdan keyin minimal sozlash — DebugTree ni Application.onCreate da ekish. Bu qadamsiz Timber barcha log chaqiruvlarini e'tiborsiz qoldiradi, istisno tashlamaydi. Bu xavfsiz standart xatti-harakat: agar daraxt ekilmagan bo'lsa, kutubxona minimal yuk bilan bo'sh ishlaydi.

Jake Wharton, 2023 ma'lumotlariga ko'ra, yangi foydalanuvchilarda Timber bilan bog'liq muammolarning 70% unutilgan yoki noto'g'ri inicializatsiya bilan bog'liq. Timber daraxt bo'lmaganda xato yaratmaydi — dasturchilar loglar Logcatda paydo bo'lishini kutishadi, lekin hech narsa sodir bo'lmaydi.

Sinov uchun Timber Timber.asTree() metodini taqdim etadi — joriy daraxtni yoki null qaytaradigan metod. Bu unit testlarda tekshirish uchun qulay: daraxtni mock bilan almashtirish va log xabari to'g'ri daraja va tag bilan yuborilganligini tekshirish mumkin.

Loglarni maxsus qayta ishlash uchun o'z Tree ngi yaratish

Maxsus daraxt — standart Log API o'rniga Timber dan foydalanishning asosiy sababi. Tree metodlarini bekor qilish orqali istalgan darajadagi loglarni Crashlytics, fayl tizimi, Remote Config yoki o'z serveringizga yo'naltirish mumkin.

class CrashReportingTree : Timber.Tree() {

    override fun isLoggable(tag: String?, priority: Int): Boolean {
        // Faqat crash-reporting uchun Error va WTF
        return priority >= Log.ERROR
    }

    override fun log(priority: Int, tag: String?,
                   message: String, t: Throwable?) {
        if (t != null) {
            FirebaseCrashlytics.getInstance()
                .recordException(t)
        } else {
            FirebaseCrashlytics.getInstance()
                .log("[$tag] $message")
        }
    }
}

Bekor qilinadigan metodlar: isLoggable(tag, priority) — xabarni qayta ishlash kerakligini aniqlaydigan filtr (asosiy implementatsiya true qaytaradi). log(priority, tag, message, t) — qayta ishlashning asosiy mantig'i. prepareLog(priority, tag, throwable, message, args) — formatlashdan oldin chaqiriladi, xabarni qayta ishlashdan oldin o'zgartirish imkonini beradi.

Maxsus daraxtlarning muhim afzalligi — refleksiyaning yo'qligi. Ko'plab logging freymvorklaridan farqli o'laroq, Timber tag yoki darajani aniqlash uchun Reflection API dan foydalanmaydi. Tag chaqiruv stekini tahlil qilish (Throwable.stackTrace) orqali hisoblanadi, bu bir daraja tezroq ishlaydi.

Timber vs standart android.util.Log

Timber va standart Log API ni solishtirish to'rtta asosiy farqni ko'rsatadi: avtomatik tag, varargs bilan satr formatlashni qo'llab-quvvatlash, bir nechta chiqish kanallari imkoniyati va inicializatsiya bo'lmaganda xavfsiz xatti-harakat.

Timber ga qarshi asosiy dalil — uchinchi tomon kutubxonasiga bog'liqlik. Minimal loglash bilan oddiy loyiha uchun Timber dan foydalanish ortiqcha bo'lishi mumkin. Biroq, Google Play Console, 2024 ma'lumotlariga ko'ra, Google Play dagi top-1000 ilovalarning 60% dan ortig'i Timber dan foydalanadi, bu uning ishonchliligi va samaradorligini tasdiqlaydi.

Timber ning release qurilmalaridagi ishlashi standart Log API dan kam emas. Ekilgan daraxtlar bo'lmaganda, Timber.d() metodi daraxtlarning mavjudligini tekshiradi (bitta if) va qaytadi — satr formatlashsiz. Bu har doim bajariladigan konkatenatsiya bilan Log.d() dan tezroq.

Timberdan foydalanishda best practices

Birinchi qoida — har doim testlarda Timber inicializatsiyasini tekshiring. Daraxt ekilganligini tasdiqlash uchun Timber.asTree() dan foydalaning. Unit testlarida assert tekshiruvlari uchun xabarlarni ro'yxatda saqlaydigan TestTree eking.

Ikkinchi qoida — bir loyihada Timber va android.util.Log ni aralashtirmang. Agar loyiha allaqachon Timber dan foydalanayotgan bo'lsa, barcha yangi log chaqiruvlari u orqali o'tishi kerak. Aralashtirish xabarlarning takrorlanishiga va tahlil qilishda chalkashlikka olib keladi.

Uchinchi qoida — CrashReportingTree ni BuildConfig.DEBUG tekshiruvisiz eking. DebugTree dan farqli o'laroq, crash daraxti ham debug, ham release rejimida ishlashi kerak — bu test xatolarining ham crash-reporting tizimiga tushishini kafolatlaydi.

To'rtinchi qoida — Timber ning o'rnatilgan darajalaridan foydalaning: Timber.v(), Timber.d(), Timber.i(), Timber.w(), Timber.e(), Timber.wtf(). Raqamli priority bilan Timber.log() ni to'g'ridan-to'g'ri chaqirishdan saqlaning — bu kod o'qilishini kamaytiradi va refaktoringni murakkablashtiradi.

Beshinchi qoida — kutubxona va modullar uchun Timber.tag(“CustomTag”) dan foydalaning. Bu metod global konfiguratsiyaga ta'sir qilmasdan, tag o'zgartirilgan vaqtinchalik daraxtni qaytaradi. Bu kutubxona kodidan maxsus identifikator bilan loglash imkonini beradi.