timber

Overview ¶

This is a logger implementation that supports multiple log levels, multiple output destinations with configurable formats and levels for each. It also supports granular output configuration to get more detailed logging for specific files/packages. Timber includes support for standard XML or JSON config files to get you started quickly. It's also easy to configure in code if you want to DIY.

Basic use:

import "timber"
timber.LoadConfiguration("timber.xml")
timber.Debug("Debug message!")

IMPORTANT: timber has not default destination configured so log messages will be dropped until a destination is configured

It can be used as a drop-in replacement for the standard logger by changing the log import statement from:

import "log"

to

import log "timber"

It can also be used as the output of the standard logger with

log.SetFlags(0)
log.SetOutput(timber.Global)

Configuration in code is also simple:

timber.AddLogger(timber.ConfigLogger{
	LogWriter: new(timber.ConsoleWriter),
	Level:     timber.DEBUG,
	Formatter: timber.NewPatFormatter("[%D %T] [%L] %S %M"),
})

XML Config file:

<logging>
  <filter enabled="true">
	<tag>stdout</tag>
	<type>console</type>
	<!-- level is (:?FINEST|FINE|DEBUG|TRACE|INFO|WARNING|ERROR) -->
	<level>DEBUG</level>
  </filter>
  <filter enabled="true">
	<tag>file</tag>
	<type>file</type>
	<level>FINEST</level>
	<granular>
	  <level>INFO</level>
	  <path>path/to/package.FunctionName</path>
	</granular>
	<granular>
	  <level>WARNING</level>
	  <path>path/to/package</path>
	</granular>
	<property name="filename">log/server.log</property>
	<property name="format">server [%D %T] [%L] %M</property>
  </filter>
  <filter enabled="false">
	<tag>syslog</tag>
	<type>socket</type>
	<level>FINEST</level>
	<property name="protocol">unixgram</property>
	<property name="endpoint">/dev/log</property>
    <format name="pattern">%L %M</property>
  </filter>
</logging>

The <tag> is ignored.

To configure the pattern formatter all filters accept:

<format name="pattern">[%D %T] %L %M</format>

Pattern format specifiers (not the same as log4go!):

%T - Time: 17:24:05.333 HH:MM:SS.ms
%t - Time: 17:24:05 HH:MM:SS
%D - Date: 2011-12-25 yyyy-mm-dd
%d - Date: 2011/12/25 yyyy/mm/dd
%L - Level (FNST, FINE, DEBG, TRAC, WARN, EROR, CRIT)
%S - Source: full runtime.Caller line and line number
%s - Short Source: just file and line number
%x - Extra Short Source: just file without .go suffix
%M - Message
%% - Percent sign
%P - Caller Path: packagePath.CallingFunctionName
%p - Caller Path: packagePath

the string number prefixes are allowed e.g.: %10s will pad the source field to 10 spaces pattern defaults to %M Both log4go synatax of <property name="format"> and new <format name=type> are supported the property syntax will only ever support the pattern formatter To configure granulars:

• Create one or many <granular> within a filter
• Define a <level> and <path> within, where path can be path to package or path to package.FunctionName. Function name definitions override package paths.

Code Architecture: A MultiLogger <logging> which consists of many ConfigLoggers <filter>. ConfigLoggers have three properties: LogWriter <type>, Level (as a threshold) <level> and LogFormatter <format>.

In practice, this means that you define ConfigLoggers with a LogWriter (where the log prints to eg. socket, file, stdio etc), the Level threshold, and a LogFormatter which formats the message before writing. Because the LogFormatters and LogWriters are simple interfaces, it is easy to write your own custom implementations.

Once configured, you only deal with the "Logger" interface and use the log methods in your code

The motivation for this package grew from a need to make some changes to the functionality of log4go (which had already been integrated into a larger project). I tried to maintain compatiblity with log4go for the interface and configuration. The main issue I had with log4go was that each of logger types had incisistent and incompatible configuration. I looked at contributing changes to log4go, but I would have needed to break existing use cases so I decided to do a rewrite from scratch.