Timber — was es ist, Bibliotheks-API und Anwendungsbeispiele

Was ist Timber

Timber ist eine Open-Source-Bibliothek für Android, die von Jake Wharton im Jahr 2013 als Alternative zum standardmäßigen android.util.Log entwickelt wurde. Die Kernidee von Timber ist es, die statische Log-API mit obligatorischem manuellen Tag durch einen automatischen Mechanismus zu ersetzen, der die Aufrufquelle über den Stack ermittelt.

Die Bibliothek basiert auf dem Architekturmuster Composite mit Bäumen (Tree). Anstelle einer einzigen Log-Klasse mit festem Verhalten verwaltet Timber einen „Wald" aus Bäumen — jeder Baum ist für seinen eigenen Ausgabekanal verantwortlich: Konsole, Datei, Crashlytics, entfernter Server. Der Entwickler kann beliebig viele Bäume hinzufügen und kombinieren.

Laut Google I/O 2019 wird Timber von Google als Best Practice für das Logging in Android-Anwendungen empfohlen. Die Bibliothek belegt weniger als 10 KB in der APK und hat keine externen Abhängigkeiten, was sie zur idealen Wahl für Projekte jeder Größenordnung macht.

Timber löst das Problem inkonsistenter Tags in großen Teams. Wenn jeder Entwickler Tags manuell schreibt, sind Tippfehler und Unstimmigkeiten unvermeidlich — eine Klasse wird als „MainActivity" protokolliert, eine andere als „MAIN_ACTIVITY". Timber leitet den Tag automatisch aus dem Klassennamen ab: MainActivity.kt → Tag MainActivity.

Timber-Architektur: Bäume und Wald

Architektur von Timber besteht aus zwei Komponenten: der zentralen statischen Klasse Timber und der abstrakten Klasse Timber.Tree. Timber fungiert als Fassade, die jeden Log-Aufruf an alle gepflanzten Bäume delegiert. Jeder Baum entscheidet, ob die Nachricht verarbeitet werden soll, und wenn ja, wohin sie gesendet wird.

DebugTree — Integrierte Implementierung für die Entwicklung

DebugTree ist die mit der Bibliothek gelieferte Standard-Tree-Implementierung. Sie bestimmt den Tag durch Analyse des Aufrufstapels: Sie geht 8 Frame vom Timber.d()-Aufrufpunkt nach oben und findet den Klassennamen, der die Log-Methode aufgerufen hat. DebugTree deaktiviert sich automatisch (gibt nichts aus) in Release-Builds, da es BuildConfig.DEBUG prüft.

Wie der Wald funktioniert

Forest (Wald) — die Sammlung aller gepflanzten Bäume. Wenn die Methode Timber.d("Nachricht") aufgerufen wird, übergibt die Bibliothek die Nachricht iterativ an alle Bäume in der Reihenfolge ihrer Pflanzung. Jeder Baum kann die Nachricht nach Level, Tag oder Inhalt filtern und auf seine eigene Weise verarbeiten.

Die Pflanzreihenfolge ist wichtig: Der zuerst gepflanzte Baum wird zuerst verarbeitet. Es wird empfohlen, DebugTree als letzten zu pflanzen, damit benutzerdefinierte Bäume (z.B. Crashlytics) die Nachricht verarbeiten, bevor sie Logcat erreicht.

Thread-Sicherheit

Timber ist thread-sicher — alle Methoden sind über eine interne Sperre synchronisiert. Dies garantiert, dass Nachrichten aus verschiedenen Threads nicht vermischt werden. Innerhalb eines benutzerdefinierten Baums liegt die Synchronisierung jedoch in der Verantwortung des Entwicklers: Wenn der Baum in eine Datei schreibt, müssen synchronized oder ReentrantLock verwendet werden.

// Waldinitialisierung der Bäume in 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 und Einrichtung von Timber in einem Android-Projekt

Installation von Timber erfolgt durch Hinzufügen einer einzigen Abhängigkeit zu build.gradle. Die Bibliothek ist auf Maven Central unter dem Artefakt com.jakewharton.timber:timber veröffentlicht. Die aktuelle Version ab 2024 ist 5.0.1, das letzte stabile Update.

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

Minimale Einrichtung nach der Installation — Pflanzen von DebugTree in Application.onCreate. Ohne diesen Schritt ignoriert Timber alle Log-Aufrufe, ohne Ausnahmen auszulösen. Dies ist ein sicheres Standardverhalten: Wenn kein Baum gepflanzt ist, läuft die Bibliothek im Leerlauf mit minimalem Overhead.

Laut Jake Wharton, 2023 stehen 70% der Timber-Probleme neuer Benutzer im Zusammenhang mit vergessener oder falscher Initialisierung. Timber erzeugt keinen Fehler, wenn keine Bäume vorhanden sind — Entwickler erwarten, dass Logs in Logcat erscheinen, aber es passiert nichts.

Für Tests bietet Timber Timber.asTree() — eine Methode, die den aktuellen Baum oder null zurückgibt. Dies ist praktisch für Unit-Tests: Sie können den Baum durch einen Mock ersetzen und überprüfen, ob die Log-Nachricht mit dem richtigen Level und Tag gesendet wurde.

Erstellen eines eigenen Tree für benutzerdefinierte Log-Verarbeitung

Benutzerdefinierter Baum — der Hauptgrund, Timber anstelle der Standard-Log-API zu verwenden. Durch Überschreiben von Tree-Methoden können Sie Logs jeder Stufe an Crashlytics, das Dateisystem, Remote Config oder Ihren eigenen Server weiterleiten.

class CrashReportingTree : Timber.Tree() {

    override fun isLoggable(tag: String?, priority: Int): Boolean {
        // Nur Error und WTF für 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")
        }
    }
}

Zu überschreibende Methoden: isLoggable(tag, priority) — ein Filter, der bestimmt, ob die Nachricht verarbeitet werden soll (Basisimplementierung gibt true zurück). log(priority, tag, message, t) — die Hauptverarbeitungslogik. prepareLog(priority, tag, throwable, message, args) — wird vor der Formatierung aufgerufen, ermöglicht die Änderung der Nachricht vor der Verarbeitung.

Ein wichtiger Vorteil benutzerdefinierter Bäume ist keine Reflexion. Im Gegensatz zu vielen Logging-Frameworks verwendet Timber keine Reflection-API zur Bestimmung des Tags oder Levels. Der Tag wird durch Analyse des Aufrufstapels (Throwable.stackTrace) berechnet, was um Größenordnungen schneller ist.

Timber vs. standardmäßiger android.util.Log

Vergleich von Timber und der Standard-Log-API zeigt vier Hauptunterschiede: automatischer Tag, Unterstützung der String-Formatierung mit Varargs, mehrere Ausgabekanäle und sicheres Verhalten ohne Initialisierung.

Hauptargument gegen Timber — Abhängigkeit von einer Drittanbieter-Bibliothek. Für ein einfaches Projekt mit minimalem Logging kann die Verwendung von Timber übertrieben sein. Laut Google Play Console, 2024 verwenden jedoch mehr als 60% der Top-1000-Apps im Google Play Timber, was seine Zuverlässigkeit und Effizienz bestätigt.

Die Leistung von Timber in Release-Builds ist vergleichbar mit der Standard-Log-API. Wenn keine Bäume gepflanzt sind, prüft die Methode Timber.d() das Vorhandensein von Bäumen (ein if) und kehrt zurück — ohne String-Formatierung. Dies ist schneller als Log.d() mit Verkettung, die immer ausgeführt wird.

Best Practices bei der Verwendung von Timber

Erste Regel — überprüfen Sie immer die Timber-Initialisierung in Tests. Verwenden Sie Timber.asTree(), um zu überprüfen, ob ein Baum gepflanzt ist. In Unit-Tests pflanzen Sie TestTree, der Nachrichten in einer Liste für Assert-Prüfungen speichert.

Zweite Regel — mischen Sie Timber und android.util.Log nicht im selben Projekt. Wenn das Projekt bereits Timber verwendet, sollten alle neuen Log-Aufrufe darüber laufen. Das Mischen führt zu doppelten Nachrichten und Verwirrung bei der Analyse.

Dritte Regel — pflanzen Sie CrashReportingTree ohne Überprüfung von BuildConfig.DEBUG. Im Gegensatz zu DebugTree sollte der Crash-Baum sowohl in Debug als auch in Release funktionieren — dies stellt sicher, dass Testfehler ebenfalls vom Crash-Reporting-System erfasst werden.

Vierte Regel — verwenden Sie die integrierten Timber-Level: Timber.v(), Timber.d(), Timber.i(), Timber.w(), Timber.e(), Timber.wtf(). Vermeiden Sie den direkten Aufruf von Timber.log() mit numerischer Priorität — dies reduziert die Lesbarkeit des Codes und erschwert die Refaktorisierung.

Fünfte Regel — für Bibliotheken und Module verwenden Sie Timber.tag("CustomTag"). Diese Methode gibt einen temporären Baum mit überschriebenem Tag zurück, ohne die globale Konfiguration zu beeinflussen. Dies ermöglicht das Loggen aus Bibliothekscode mit einer benutzerdefinierten Kennung.