1![obligatory xkcd](http://imgs.xkcd.com/comics/standards.png) 2 3# log15 [![godoc reference](https://godoc.org/github.com/inconshreveable/log15?status.png)](https://godoc.org/github.com/inconshreveable/log15) [![Build Status](https://travis-ci.org/inconshreveable/log15.svg?branch=master)](https://travis-ci.org/inconshreveable/log15) 4 5Package 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`](http://golang.org/pkg/io/) and [`net/http`](http://golang.org/pkg/net/http/) packages and is an alternative to the standard library's [`log`](http://golang.org/pkg/log/) package. 6 7## Features 8- A simple, easy-to-understand API 9- Promotes structured logging by encouraging use of key/value pairs 10- Child loggers which inherit and add their own private context 11- Lazy evaluation of expensive operations 12- Simple Handler interface allowing for construction of flexible, custom logging configurations with a tiny API. 13- Color terminal support 14- Built-in support for logging to files, streams, syslog, and the network 15- Support for forking records to multiple handlers, buffering records for output, failing over from failed handler writes, + more 16 17## Versioning 18The API of the master branch of log15 should always be considered unstable. If you want to rely on a stable API, 19you must vendor the library. 20 21## Importing 22 23```go 24import log "github.com/inconshreveable/log15" 25``` 26 27## Examples 28 29```go 30// all loggers can have key/value context 31srvlog := log.New("module", "app/server") 32 33// all log messages can have key/value context 34srvlog.Warn("abnormal conn rate", "rate", curRate, "low", lowRate, "high", highRate) 35 36// child loggers with inherited context 37connlog := srvlog.New("raddr", c.RemoteAddr()) 38connlog.Info("connection open") 39 40// lazy evaluation 41connlog.Debug("ping remote", "latency", log.Lazy{pingRemote}) 42 43// flexible configuration 44srvlog.SetHandler(log.MultiHandler( 45 log.StreamHandler(os.Stderr, log.LogfmtFormat()), 46 log.LvlFilterHandler( 47 log.LvlError, 48 log.Must.FileHandler("errors.json", log.JsonFormat())))) 49``` 50 51Will result in output that looks like this: 52 53``` 54WARN[06-17|21:58:10] abnormal conn rate module=app/server rate=0.500 low=0.100 high=0.800 55INFO[06-17|21:58:10] connection open module=app/server raddr=10.0.0.1 56``` 57 58## Breaking API Changes 59The following commits broke API stability. This reference is intended to help you understand the consequences of updating to a newer version 60of log15. 61 62- 57a084d014d4150152b19e4e531399a7145d1540 - Added a `Get()` method to the `Logger` interface to retrieve the current handler 63- 93404652ee366648fa622b64d1e2b67d75a3094a - `Record` field `Call` changed to `stack.Call` with switch to `github.com/go-stack/stack` 64- a5e7613673c73281f58e15a87d2cf0cf111e8152 - Restored `syslog.Priority` argument to the `SyslogXxx` handler constructors 65 66## FAQ 67 68### The varargs style is brittle and error prone! Can I have type safety please? 69Yes. Use `log.Ctx`: 70 71```go 72srvlog := log.New(log.Ctx{"module": "app/server"}) 73srvlog.Warn("abnormal conn rate", log.Ctx{"rate": curRate, "low": lowRate, "high": highRate}) 74``` 75 76### Regenerating the CONTRIBUTORS file 77 78``` 79go get -u github.com/kevinburke/write_mailmap 80write_mailmap > CONTRIBUTORS 81``` 82 83## License 84Apache 85