Timber — ce que c’est, API de la bibliothèque et exemples d’utilisation

Qu’est-ce que Timber

Timber est une bibliothèque open source pour Android créée par Jake Wharton en 2013 comme alternative au android.util.Log standard. L’idée clé de Timber est de remplacer l’API Log statique avec tag manuel obligatoire par un mécanisme automatique qui détermine la source de l’appel via la pile.

La bibliothèque est construite sur le modèle architectural Composite avec Arbres (Tree). Au lieu d’une seule classe Log avec un comportement fixe, Timber gère une « forêt » d’arbres — chaque arbre est responsable de son propre canal de sortie : console, fichier, Crashlytics, serveur distant. Le développeur peut ajouter n’importe quel nombre d’arbres et les combiner.

Selon Google I/O 2019, Timber est recommandé par Google comme une bonne pratique pour le logging dans les applications Android. La bibliothèque occupe moins de 10 Ko dans l’APK et n’a aucune dépendance externe, ce qui en fait un choix idéal pour des projets de toute envergure.

Timber résout le problème des tags incohérents dans les grandes équipes. Lorsque chaque développeur écrit des tags manuellement, les fautes de frappe et les divergences sont inévitables — une classe est enregistrée comme « MainActivity », une autre comme « MAIN_ACTIVITY ». Timber dérive automatiquement le tag du nom de la classe : MainActivity.kt → tag MainActivity.

Architecture de Timber : Arbres et Forêt

Architecture de Timber se compose de deux composants : la classe statique centrale Timber et la classe abstraite Timber.Tree. Timber agit comme une façade qui délègue chaque appel de log à tous les arbres plantés. Chaque arbre décide s’il doit traiter le message et, si oui, où l’envoyer.

DebugTree — Implémentation intégrée pour le développement

DebugTree est l’implémentation standard de Tree fournie avec la bibliothèque. Elle détermine le tag en analysant la pile d’appels : elle remonte de 8 frames à partir du point d’appel Timber.d() et trouve le nom de la classe qui a invoqué la méthode de log. DebugTree se désactive automatiquement (ne produit rien) dans les builds release car il vérifie BuildConfig.DEBUG.

Comment fonctionne la Forêt

Forest (Forêt) — la collection de tous les arbres plantés. Lorsque la méthode Timber.d("message") est appelée, la bibliothèque transmet itérativement le message à tous les arbres dans l’ordre de leur plantation. Chaque arbre peut filtrer le message par niveau, tag ou contenu, et le traiter à sa manière.

L’ordre de plantation est important : le premier arbre planté est traité en premier. Il est recommandé de planter DebugTree en dernier, afin que les arbres personnalisés (par exemple, Crashlytics) traitent le message avant qu’il n’atteigne Logcat.

Sécurité des threads

Timber est thread-safe — toutes les méthodes sont synchronisées via un verrou interne. Cela garantit que les messages provenant de différents threads ne se mélangent pas. Cependant, à l’intérieur d’un arbre personnalisé, la synchronisation est de la responsabilité du développeur : si l’arbre écrit dans un fichier, synchronized ou ReentrantLock doivent être utilisés.

// Initialisation de la forêt d’arbres dans Application.onCreate
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")
    }
}

Installation et configuration de Timber dans un projet Android

Installation de Timber se fait en ajoutant une seule dépendance au build.gradle. La bibliothèque est publiée sur Maven Central sous l’artefact com.jakewharton.timber:timber. La version actuelle en 2024 est la 5.0.1, la dernière mise à jour stable.

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

Configuration minimale après l’installation — planter DebugTree dans Application.onCreate. Sans cette étape, Timber ignorera tous les appels de log sans lever d’exceptions. C’est un comportement par défaut sûr : si aucun arbre n’est planté, la bibliothèque tourne à vide avec une surcharge minimale.

Selon Jake Wharton, 2023, 70 % des problèmes de Timber chez les nouveaux utilisateurs sont liés à une initialisation oubliée ou incorrecte. Timber ne génère pas d’erreur quand il n’y a pas d’arbres — les développeurs s’attendent à voir les logs dans Logcat, mais rien ne se produit.

Pour les tests, Timber fournit Timber.asTree() — une méthode qui retourne l’arbre actuel ou null. C’est pratique pour les tests unitaires : vous pouvez remplacer l’arbre par un mock et vérifier que le message de log a été envoyé avec le bon niveau et le bon tag.

Création d’un Tree personnalisé pour le traitement personnalisé des logs

Arbre personnalisé — la principale raison d’utiliser Timber plutôt que l’API Log standard. En redéfinissant les méthodes de Tree, vous pouvez router des logs de n’importe quel niveau vers Crashlytics, le système de fichiers, Remote Config ou votre propre serveur.

class CrashReportingTree : Timber.Tree() {

    override fun isLoggable(tag: String?, priority: Int): Boolean {
        // Seulement Error et WTF pour le crash-reporting
        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")
        }
    }
}

Méthodes à redéfinir : isLoggable(tag, priority) — un filtre qui détermine si le message doit être traité (l’implémentation de base retourne true). log(priority, tag, message, t) — la logique de traitement principale. prepareLog(priority, tag, throwable, message, args) — appelé avant le formatage, permet de modifier le message avant son traitement.

Un avantage important des arbres personnalisés est l’absence de réflexion. Contrairement à de nombreux frameworks de logging, Timber n’utilise pas l’API Reflection pour déterminer le tag ou le niveau. Le tag est calculé en analysant la pile d’appels (Throwable.stackTrace), ce qui est des ordres de grandeur plus rapide.

Timber vs android.util.Log standard

Comparaison de Timber et de l’API Log standard montre quatre différences clés : tag automatique, prise en charge du formatage de chaîne avec varargs, multiples canaux de sortie et comportement sûr sans initialisation.

Principal argument contre Timber — dépendance à une bibliothèque tierce. Pour un projet simple avec un logging minimal, l’utilisation de Timber peut être excessive. Cependant, selon Google Play Console, 2024, plus de 60 % des 1000 meilleures applications du Google Play utilisent Timber, ce qui confirme sa fiabilité et son efficacité.

Les performances de Timber dans les builds release sont comparables à celles de l’API Log standard. Lorsqu’aucun arbre n’est planté, la méthode Timber.d() vérifie la présence d’arbres (un if) et retourne — sans formatage de chaîne. C’est plus rapide que Log.d() avec concaténation, qui s’exécute toujours.

Bonnes pratiques d’utilisation de Timber

Première règle — vérifiez toujours l’initialisation de Timber dans les tests. Utilisez Timber.asTree() pour vérifier qu’un arbre est planté. Dans les tests unitaires, plantez TestTree qui sauvegarde les messages dans une liste pour les vérifications assert.

Deuxième règle — ne mélangez pas Timber et android.util.Log dans le même projet. Si le projet utilise déjà Timber, tous les nouveaux appels de log doivent passer par lui. Le mélange entraîne des messages en double et de la confusion lors de l’analyse.

Troisième règle — plantez CrashReportingTree sans vérifier BuildConfig.DEBUG. Contrairement à DebugTree, l’arbre de crash doit fonctionner à la fois en debug et en release — cela garantit que les erreurs de test sont également capturées par le système de rapport de crash.

Quatrième règle — utilisez les niveaux intégrés de Timber : Timber.v(), Timber.d(), Timber.i(), Timber.w(), Timber.e(), Timber.wtf(). Évitez d’appeler Timber.log() directement avec une priorité numérique — cela réduit la lisibilité du code et complique le refactoring.

Cinquième règle — pour les bibliothèques et modules, utilisez Timber.tag("CustomTag"). Cette méthode retourne un arbre temporaire avec un tag redéfini sans affecter la configuration globale. Cela permet de logger depuis du code de bibliothèque avec un identifiant personnalisé.