Concepts

Before any of the timber documentation will make sense, you’ll need to understand some of the core concepts and terminology.

• Entries are the main data structures in timber. You can think of them as lines in an application log file. As a matter of fact, that’s usually what they end up becoming.
• Messages represent the textual content of entries. Usually, the message is the essence of a particular entry, although in timber, it is optional.
• Loggers are used by timber API consumers to generate entries and inject them into the logging system (an activity more commonly known as “logging”). Loggers can have attributes and tags that get associated with the entries that they create.
• Tags are used to mark specific entries with application-specific semantics. Tags can be specified as parameters to the logging method call or imparted by the logger.
• ThreadAttributes can be used to maintain extra application-specific metadata per thread, which will become associated with any entries created by that thread.

Some concepts are only important if you’re using the timber logging backend.

• Receivers perform the actual processing of entries by writing them into log files, sending them to network servers, etc.
• Formatters turn entries into text. A formatter is usually required by any receiver that needs a text representation of the entry (e.g., one that writes entries to the console).
• Dispatchers route entries to the correct receivers based on their configuration.

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 multiple 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.