Skip to content
Structured, composable logging for Go
Go
Branch: master
Clone or download

Latest commit

kevinburke logger: make LvlFromString slightly more flexible
Also return the correct level for "WARN", "Warn" etc. While we are at
it, lowercase the returned error string - staticcheck among others
warns about uppercased error messages.
Latest commit b30bc20 Jan 9, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
ext Resolve most of the golint issues Oct 2, 2017
term Use `github.com/mattn/go-isatty` for tty detection Oct 19, 2017
.mailmap Generate up-to-date CONTRIBUTORS list Oct 2, 2017
.travis.yml travis.yml: add more recent Go versions Jan 9, 2020
CONTRIBUTORS add Varun Agrawal to CONTRIBUTORS Aug 18, 2018
LICENSE initial public version May 20, 2014
README.md Generate up-to-date CONTRIBUTORS list Oct 2, 2017
bench_test.go Add the benchmarks from uber-go/zap Jun 22, 2016
doc.go doc: fixed bug in the initial example Oct 19, 2017
format.go formatJsonValue returns map rather than a formatted string Aug 18, 2018
handler.go Resolve most of the golint issues Oct 2, 2017
handler_go13.go Use atomic.Value instead of unsafe pointers on Go 1.4 May 13, 2016
handler_go14.go Use atomic.Value instead of unsafe pointers on Go 1.4 May 13, 2016
log15_test.go formatJsonValue returns map rather than a formatted string Aug 18, 2018
logger.go logger: make LvlFromString slightly more flexible Jan 9, 2020
logger_test.go logger: make LvlFromString slightly more flexible Jan 9, 2020
root.go Use `github.com/mattn/go-isatty` for tty detection Oct 19, 2017
syslog.go Fix typo in SyslogNetHandler documentation comment Oct 24, 2016

README.md

obligatory xkcd

log15 godoc reference Build Status

Package log15 provides an opinionated, simple toolkit for best-practice logging in Go (golang) that is both human and machine readable. It is modeled after the Go standard library's io and net/http packages and is an alternative to the standard library's log package.

Features

  • A simple, easy-to-understand API
  • Promotes structured logging by encouraging use of key/value pairs
  • Child loggers which inherit and add their own private context
  • Lazy evaluation of expensive operations
  • Simple Handler interface allowing for construction of flexible, custom logging configurations with a tiny API.
  • Color terminal support
  • Built-in support for logging to files, streams, syslog, and the network
  • Support for forking records to multiple handlers, buffering records for output, failing over from failed handler writes, + more

Versioning

The API of the master branch of log15 should always be considered unstable. If you want to rely on a stable API, you must vendor the library.

Importing

import log "github.com/inconshreveable/log15"

Examples

// all loggers can have key/value context
srvlog := log.New("module", "app/server")

// all log messages can have key/value context
srvlog.Warn("abnormal conn rate", "rate", curRate, "low", lowRate, "high", highRate)

// child loggers with inherited context
connlog := srvlog.New("raddr", c.RemoteAddr())
connlog.Info("connection open")

// lazy evaluation
connlog.Debug("ping remote", "latency", log.Lazy{pingRemote})

// flexible configuration
srvlog.SetHandler(log.MultiHandler(
    log.StreamHandler(os.Stderr, log.LogfmtFormat()),
    log.LvlFilterHandler(
        log.LvlError,
        log.Must.FileHandler("errors.json", log.JsonFormat()))))

Will result in output that looks like this:

WARN[06-17|21:58:10] abnormal conn rate                       module=app/server rate=0.500 low=0.100 high=0.800
INFO[06-17|21:58:10] connection open                          module=app/server raddr=10.0.0.1

Breaking API Changes

The following commits broke API stability. This reference is intended to help you understand the consequences of updating to a newer version of log15.

  • 57a084d014d4150152b19e4e531399a7145d1540 - Added a Get() method to the Logger interface to retrieve the current handler
  • 93404652ee366648fa622b64d1e2b67d75a3094a - Record field Call changed to stack.Call with switch to github.com/go-stack/stack
  • a5e7613673c73281f58e15a87d2cf0cf111e8152 - Restored syslog.Priority argument to the SyslogXxx handler constructors

FAQ

The varargs style is brittle and error prone! Can I have type safety please?

Yes. Use log.Ctx:

srvlog := log.New(log.Ctx{"module": "app/server"})
srvlog.Warn("abnormal conn rate", log.Ctx{"rate": curRate, "low": lowRate, "high": highRate})

Regenerating the CONTRIBUTORS file

go get -u github.com/kevinburke/write_mailmap
write_mailmap > CONTRIBUTORS

License

Apache

You can’t perform that action at this time.