timber

KO | EN

gitlite — search

#javascript #golang #android #rust #linux #docker #java #awesome #cli #vue #pytorch #ios #mcp #openai

(★ 66)

Configurable Logger for Go

File Explorer

Download Latest Version (.zip)

.gitignore
buffered_writer.go
config.go
config_json.go
config_xml.go
console_writer.go
file_writer.go
LICENSE.md
pattern_formatter.go
pattern_formatter_test.go
README.md
socket_writer.go
syslog_formatter.go
timber.go
timber.json
timber.xml
timber_test.go

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Timber!
=======

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.

Features
--------
* Log levels: Finest, Fine, Debug, Trace, Info, Warn, Error, Critical
* External configuration via XML and JSON
* Multiple log destinations (console, file, socket)
* Configurable format per destination
* Extensible and pluggable design (if you configure via code rather than XML)

Motivation
----------
I like the log4go design with multiple configurable loggers, but it did not support adding formatters to all of the loggers (it is only supported for files).  I thought about trying to contribute patches to log4go but some of the features I wanted would break complete backwards compatibility so I decided to do a rewrite from scratch.

I try to expose everything possible that I think might be useful for someone to replace or extend.

Usage
-----
The easiest way to use Timber is to use configure the built-in singleton:

import (
		log "timber"
	)

func main() {
		// load xml config, json also supported
		log.LoadConfiguration("timber.xml")
		log.Info("Timber!!!")
	}

An example timber.xml and timber.json are included in the package. Timber does implement the interface of the go log package so replacing the log with Timber will work ok.

`log.Close()` should be called before your program exits to make sure all the buffers are drained and all messages are printed.

Design
------

`Logger` is the interface that is used for logging itself with methods like Warn, Critical, Error, etc.  All of these functions expect a Printf-like arguments and syntax for the message.

`LogFormatter` is a generic interface for taking a `LogRecord` and formatting into a string to be logged. `PatFormatter` is the only included implementation of this interface.

`LogWriter` interface wraps an underlying `Writer` but doesn't allow errors to propagate. There are implementations for writing to files, sockets and the console.

`Timber` is a `MultiLogger` which just means that it implements the `Logger` interface but can log messages to multiple destinations.  Each destination has a `LogWriter`, `level` and `LogFormatter`.

`Global` is the default unconfigured instance of `Timber` which may be configured and used or, less commonly, replaced with your own instance (be sure to call `Global.Close()` before replacing for proper cleanup).

Are you planning to wrap Timber in your own logger? Ever notice that if you wrap the go log package or log4go the source file that gets printed is always your wrapper?  `Timber.FileDepth`  sets how far up the stack to go to find the file you actually want.  It's set to `DefaultFileDepth` so add your wrapper stack depth to that.

Completeness
------------
* Some of the runtime configuration changes have not been implemented, such as `MultiLogger.SetLevel` and `MultiLogger.SetFormatter` which change the Level or `LogFormatter` on-the-fly.  Loggers may be added at any time with `AddLogger` but there is no way to delete loggers right now.

Compatibility
-------------
* I don't support the log4go special handling of the first parameter and probably never will.  Right now, all of the `Logger` methods just expect a Printf-like syntax.  If there is demand, I may get the proc syntax in for delayed evaluation.
* `PatFormatter` format codes are not the same as log4go
* `PatFormatter` always adds a newline at the end of the string so if there's already one there, then you'll get 2 so using Timber to replace the go log package may look a bit messy depending on how you formatted your logging.

timber

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

timber

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README