Timber مع Kotlin: دليل شامل مع أمثلة

1. ما هي Timber ولماذا تحتاجها؟

Timber هي مكتبة خفيفة الوزن لتسجيل الأحداث (Logging) في تطبيقات Android، مكتوبة بلغة Kotlin. طورها جايك وارثون (Jake Wharton)، أحد أبرز مطوري Android والمعروف بمشاريع مثل Retrofit وOkHttp وDagger. الهدف الأساسي من Timber هو تخليص المطور من كتابة الكود المتكرر عند تسجيل الأحداث وتوفير آلية مرنة لإدارة السجلات في مراحل التطوير المختلفة.

لماذا تحتاج Timber بينما يوجد android.util.Log القياسي؟ أولاً، تضيف Timber تلقائياً اسم الفئة والطريقة إلى كل سجل، مما يجعل تتبع الأخطاء أسهل بكثير. لم يعد عليك كتابة Log.d(TAG, "message")، يكفي استدعاء Timber.d("message"). ثانياً، توفر Timber نظام "الأشجار" (Trees) الذي يسمح بتوزيع السجلات على قنوات مختلفة: مثلاً، في نسخة التصحيح (debug) يتم عرض كل شيء في Logcat، بينما في نسخة الإصدار (release) يتم إرسال الأخطاء فقط إلى Crashlytics أو خدمة تحليلات أخرى.

الميزة الثالثة المهمة هي أن Timber تقوم تلقائياً بتعطيل جميع السجلات في نسخة الإصدار إذا لم تقم بإعداد شجرة خاصة للإنتاج. هذا لا يحسن الأداء فحسب، بل يمنع أيضاً تسرب البيانات الحساسة عبر السجلات. المكتبة مشهورة جداً لدرجة أنها تُستخدم في آلاف المشاريع التجارية وتُوصى بها Google في أدلتها الرسمية لتطوير Android.

2. التثبيت

يتم توزيع Timber عبر Maven Central. للتثبيت، أضف التبعية إلى ملف build.gradle (على مستوى الوحدة):

dependencies {
    implementation 'com.jakewharton.timber:timber:5.0.1'
}

إذا كنت تستخدم Kotlin DSL (build.gradle.kts):

dependencies {
    implementation("com.jakewharton.timber:timber:5.0.1")
}

بعد مزامنة Gradle، تصبح المكتبة جاهزة للاستخدام. لاحظ أن Timber لا تتطلب أذونات إضافية في ملف AndroidManifest.xml.

3. البداية السريعة — مثال عملي بسيط

للبدء، يجب "زراعة شجرة" (plant a tree) — أي تسجيل معالج للسجلات. أسهل طريقة هي استخدام الشجرة المدمجة Timber.DebugTree، التي تعرض السجلات في Logcat بمستوى DEBUG وما فوق:

import timber.log.Timber

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        if (BuildConfig.DEBUG) {
            Timber.plant(Timber.DebugTree())
        }
    }
}

الآن يمكنك كتابة السجلات في أي مكان في التطبيق:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        Timber.d("تم إنشاء النشاط")
        Timber.i("المستخدم فتح الشاشة الرئيسية")
        Timber.w("حدث شيء مريب")
        Timber.e("حدث خطأ: %s", "انتهت مهلة الشبكة")
    }
}

في Logcat سترى ما يلي تقريباً:

D/MainActivity: تم إنشاء النشاط
I/MainActivity: المستخدم فتح الشاشة الرئيسية
W/MainActivity: حدث شيء مريب
E/MainActivity: حدث خطأ: انتهت مهلة الشبكة

لاحظ أن Timber حددت تلقائياً اسم الفئة (MainActivity) وأضافته كوسم (tag). لم تعد بحاجة لإنشاء ثابت TAG يدوياً.

4. الدوال/الطرق/الفئات الرئيسية

4.1. Timber.d() — تسجيل التصحيح (Debug)

التوقيع: fun d(message: String, vararg args: Any?)

الوظيفة: تعرض رسالة تصحيح بمستوى DEBUG. تُستخدم للسجلات المؤقتة أثناء التطوير. في نسخة الإصدار لا يتم عرضها افتراضياً.

Timber.