Concepts

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.

Dependencies

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.

jar purpose
timber-api provides the timber logging API for generating timber entries
timber-backend provides the backend for processing timber entries (writing to files and log services)
timber-over-slf4j bridges timber entries to an slf4j backend
slf4j-over-timber bridges slf4j entries to the timber backend
timber-logback-support 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.

Bridging to timber

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

API dependency  
timber slf4j slf4j-over-timber
timber jcl jcl-over-slf4j, slf4j-over-timber
timber log4j log4j-over-slf4j, slf4j-over-timber

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.

Bridging from timber

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 logging backend.

Caveat

In general, unless you’re delivering an application, you shouldn’t depend on any timber jar except timber-api. 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.

Help improve this page.