Before any of the timber documentation will make sense, you’ll need to understand some of the core concepts and terminology.
Some concepts are only important if you’re using the timber logging backend.
Timber draws a clear distinction between code that generates log entries (using the timber API) and code that processes those log entries (using the timber backend). API consumers generally don’t know or care about the specifics of how entries are processed. That is determined solely by the application.
Timber is broken down into a number of individual jars that each provide a subset of its overall functionality. This is to allow for more flexibility at run time and a cleaner internal architecture. You should depend only on the jars that you need for your specific use case.
||provides the timber logging API for generating timber entries|
||provides the backend for processing timber entries (writing to files and log services)|
||bridges timber entries to an slf4j backend|
||bridges slf4j entries to the timber backend|
||provides support for using custom logback implementations with timber|
Any code that logs using the timber API must depend on
timber-api. Any application that uses the timber backend
must depend on
timber-backend. The other jars provided by timber are used to integrate with other logging systems.
A given process normally uses a single logging backend, chosen by the application developer. This makes it so that there is a single logging configuration that (often) writes to a single application log file. Given that most applications take advantage of third-party libraries (written by different developers using different logging APIs), some bridging is required to get entries from those APIs to the selected logging backend. Timber is no different. If you choose the timber backend, you may want to include some bridging jars to collect the entries generated by libraries using other logging APIs.
The main bridges provided by timber are to and from slf4j which itself provides several bridges to other logging systems). This allows timber to collect entries from many popular logging APIs. It perfectly acceptable to include both the timber bridge for slf4j and one or more of the other bridges at the same time. The only restriction is that you can’t include more than one backend for any given logging system. If you do this, you’ll probably get an error from that logging system.
The following table lists the jars that you need to include to gather entries generated by various logging APIs
Depending on the number of libraries you’re using, your application may match mutiple rows in the table above with the same backend. In that case, you’ll need to add the jars from all the rows.
If you have a library that uses the timber logging API as part of an application that’s using an slf4j-compatible
logging backend, you need to include the dependency
timber-over-slf4j. This jar will bridge all timber entries
into the slf4j system. You can’t use both this jar and the
timber-backend jar simultaneously since they both
provide a timber backend. Doing so doesn’t really make sense anyway, since you normally only want to use one
In general, unless you’re delivering an application, you shouldn’t depend on any timber jar except
Doing so means that you’re tying your application to a specific logging backend and that will frustrate anyone
trying to use your library. If you’re creating a library and you find yourself wanting to use a definition from
timber-backend (or any of the other jars), you’re probably doing something wrong.