• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

ext/H09-Jan-2020-295201

term/H09-Jan-2020-17482

.mailmapH A D09-Jan-20201,014 2726

.travis.ymlH A D09-Jan-2020144 1210

CONTRIBUTORSH A D09-Jan-20201.1 KiB3029

LICENSEH A D09-Jan-2020551 1410

README.mdH A D09-Jan-20203.3 KiB8562

bench_test.goH A D09-Jan-20203.7 KiB208176

doc.goH A D09-Jan-202012 KiB3341

format.goH A D09-Jan-20206.3 KiB284219

handler.goH A D09-Jan-202010 KiB354209

handler_go13.goH A D09-Jan-2020513 2717

handler_go14.goH A D09-Jan-2020471 2414

log15_test.goH A D09-Jan-202012.5 KiB599463

logger.goH A D09-Jan-20204.9 KiB218154

logger_test.goH A D09-Jan-2020534 3127

root.goH A D09-Jan-20201.7 KiB6942

syslog.goH A D09-Jan-20201.5 KiB5642

README.md

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