timber on GitHub (JakeWharton/timber)

timber README

This is a logger with a small, extensible API which provides utility on top of Android's normal Log class.

I copy this class into all the little apps I make. I'm tired of doing it. Now it's a library.

Behavior is added through Tree instances. You can install an instance by calling Timber.plant. Installation of Trees should be done as early as possible. The onCreate of your application is the most logical choice.

The DebugTree implementation will automatically figure out from which class it's being called and use that class name as its tag. Since the tags vary, it works really well when coupled with a log reader like Pidcat.

There are no Tree implementations installed by default because every time you log in production, a puppy dies.

Usage

Two easy steps:

Install any Tree instances you want in the onCreate of your application class.
Call Timber's static methods everywhere throughout your app.

Check out the sample app in timber-sample/ to see it in action.

Lint

Timber ships with embedded lint rules to detect problems in your app.

TimberArgCount (Error) - Detects an incorrect number of arguments passed to a Timber call for the specified format string.

Example.java:35: Error: Wrong argument count, format string Hello %s %s! requires 2 but format call supplies 1 [TimberArgCount]
    Timber.d("Hello %s %s!", firstName);
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TimberArgTypes (Error) - Detects arguments which are of the wrong type for the specified format string.

Example.java:35: Error: Wrong argument type for formatting argument '#0' in success = %b: conversion is 'b', received String (argument #2 in method call) [TimberArgTypes]
    Timber.d("success = %b", taskName);
                             ~~~~~~~~

TimberTagLength (Error) - Detects the use of tags which are longer than Android's maximum length of 23.

Example.java:35: Error: The logging tag can be at most 23 characters, was 35 (TagNameThatIsReallyReallyReallyLong) [TimberTagLength]
    Timber.tag("TagNameThatIsReallyReallyReallyLong").d("Hello %s %s!", firstName, lastName);
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

LogNotTimber (Warning) - Detects usages of Android's Log that should be using Timber.

Example.java:35: Warning: Using 'Log' instead of 'Timber' [LogNotTimber]
    Log.d("Greeting", "Hello " + firstName + " " + lastName + "!");
        ~

StringFormatInTimber (Warning) - Detects String.format used inside of a Timber call. Timber handles string formatting automatically.

Example.java:35: Warning: Using 'String#format' inside of 'Timber' [StringFormatInTimber]
    Timber.d(String.format("Hello, %s %s", firstName, lastName));
             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

BinaryOperationInTimber (Warning) - Detects string concatenation inside of a Timber call. Timber handles string formatting automatically and should be preferred over manual concatenation.

Example.java:35: Warning: Replace String concatenation with Timber's string formatting [BinaryOperationInTimber]
    Timber.d("Hello " + firstName + " " + lastName + "!");
             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TimberExceptionLogging (Warning) - Detects the use of null or empty messages, or using the exception message when logging an exception.

Example.java:35: Warning: Explicitly logging exception message is redundant [TimberExceptionLogging]
     Timber.d(e, e.getMessage());
                 ~~~~~~~~~~~~~~

Download

repositories {
  mavenCentral()
}

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

Documentation is available at jakewharton.github.io/timber/docs/5.x/.

Snapshots of the development version are available in Sonatype's snapshots repository.

repositories {
  mavenCentral()
  maven {
    url 'https://central.sonatype.com/repository/maven-snapshots/'
  }
}

dependencies {
  implementation 'com.jakewharton.timber:timber:5.1.0-SNAPSHOT'
}

Snapshot documentation is available at jakewharton.github.io/timber/docs/latest/.

License

Copyright 2013 Jake Wharton

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

10.9K ·GitHub

Timber

What is this?

Timber is a logger with a small, extensible API that sits on top of Android's built-in Log class. You add behavior by planting Tree instances instead of calling Log.d/Log.e directly.

Is this a standalone app or a library I add to my project?

It is a library you include in an Android app; it ships with no Tree implementations installed by default, so it logs nothing until you plant one.

How do I start using it in my app?

Plant any Tree instances you want (like DebugTree) in your Application class's onCreate, then call Timber's static methods (Timber.d, Timber.e, etc.) anywhere in your app.

Does it work outside Android apps?

No, Timber is built specifically as a wrapper around Android's Log class, so it's for Android projects.

Will it log anything if I just add the dependency without extra setup?

No. Timber stays silent until you explicitly plant a Tree (e.g. DebugTree); the library intentionally ships with zero logging trees enabled out of the box.

What does the built-in DebugTree do?

DebugTree automatically figures out which class called it and uses that class name as the log tag, which pairs well with log readers like Pidcat.

What does the TimberArgCount lint check catch?

Timber ships an embedded Android Lint rule that flags Timber calls where the number of arguments doesn't match the placeholders in the format string, e.g. passing one argument to a string expecting two.

Why use Timber instead of just calling Log directly?

Timber gives you a small, extensible API where logging behavior is defined through pluggable Tree classes, auto-tags calls for you, and avoids leaving debug logs active in production builds by default.

What are similar projects?

logger, GSYVideoPlayer, MaterialDrawer, Shizuku, platform_frameworks_base, MVPArms, leakcanary, DoKit

Which topics is it in?

logger, lint, android-development, android-library, logging, debugging, mobile-development, static-analysis, kotlin, sdk, utility, java

Creator: JakeWharton
Size: 2.8 MB
Stars: 10.9K
Updated: CommitOct 16 Release5.0.1Aug 13
Age: 13y
Commits · 90 Days

timber README

Usage

Lint

Download

License

timber (JakeWharton/timber)