Timber

Timber is a lightweight logging framework written in Swift. It is very performant and runs all logging-based operations away from the main-thread, ensuring that the UI or any other operations remain unaffected.

Timber is also insanely flexible. It provides a LogFormat class which allows you to specify how the log messages should look, and includes custom date formats, and various information related to the file that the log message was executed in, such as the file-name, function and line.

Timber even provides the means to move your logs away from the console, by providing your own pipe to store the log messages elsewhere such as in a file or on your own server.

Unlike a number of other available logging frameworks, Timber lets you specify log-levels for any/all of your files. Say, for instance, you wanted to disable the logging of network requests while testing a separate feature, by calling Logger.registerMinLevel(.None) in your networking class, you can disable the log messages from being output.

Installation

Cocoapods

Simply add the following to your Podfile. Please be aware that the name of the cocoapod is TimberSwift and not Timber.

pod 'TimberSwift'

Manually

Clone the repository and add all the files found in /Timber/Classes to your project.

Running unit tests

It is recommended that you run the unit tests before integrating Timber into your project. This can be done by performing the following in Timber’s root directory. Please ensure that you have bundler installed, and if not run gem install bundler first.

$ bundle install
$ make test

Basic usage

Logger.registerMinLevel(.Error) // Set the log-level for the current file if needed

Logger.debug("This will not be logged as the debug log level is < error")
Logger.error("Oh dear... An error occurred: \(some_error)")
Logger.info("The network request succeeded with status code \(status code)")
Logger.warn("The network response contains some unexpected data")
// etc...

Custom log formats

In order to override the default log format used by Timber, which is [Level Date Filename:Line] Message, you must first instantiate your own LogFormat and pass it into either the global Logger or your own.

    let logFormat = LogFormat(template: "[%@ %@ %@:%@] %@", attributes: [
        LogFormatter.Attributes.Level,
        LogFormatter.Attributes.Date(format: "HH:mm:ss"),
        LogFormatter.Attributes.FileName(fullPath: false, fileExtension: true),
        LogFormatter.Attributes.Line,
        LogFormatter.Attributes.Message
     ])

     // Attach it to the global Logger
     Logger.setFormat(logFormat)

     // Or attach it to your own logger
     someLogger.logFormat = logFormat

     // Or pass it in when you instantiate your logger
     let someLogger = Logger(minLevel: .All, logFormat: logFormat)

Documentation

Timber is fully documented, and the documentation can be found at http://maxkramer.github.io/Timber/.

Log Levels

As mentioned in Logger+LogLevels.swift, we uniformly use the same log priorities as Apache’s log4j. The is as follows:

ALL < DEBUG < TRACE < INFO < WARN < ERROR < FATAL < OFF.

Therefore, a log request of level p in a logger with level q is enabled if p >= q.

Visually:

Reference: Log4j’s architecture page.

TODO:

• Swift PM integration
• Higher level functions for logging to file(s) including log rotation
• Colours!!!