github.com/ubiq/go-ethereum@v3.0.1+incompatible/log/README.md (about)

     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  
     5  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`](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
    18  The API of the master branch of log15 should always be considered unstable. If you want to rely on a stable API,
    19  you must vendor the library.
    20  
    21  ## Importing
    22  
    23  ```go
    24  import log "github.com/inconshreveable/log15"
    25  ```
    26  
    27  ## Examples
    28  
    29  ```go
    30  // all loggers can have key/value context
    31  srvlog := log.New("module", "app/server")
    32  
    33  // all log messages can have key/value context
    34  srvlog.Warn("abnormal conn rate", "rate", curRate, "low", lowRate, "high", highRate)
    35  
    36  // child loggers with inherited context
    37  connlog := srvlog.New("raddr", c.RemoteAddr())
    38  connlog.Info("connection open")
    39  
    40  // lazy evaluation
    41  connlog.Debug("ping remote", "latency", log.Lazy{pingRemote})
    42  
    43  // flexible configuration
    44  srvlog.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  
    51  Will result in output that looks like this:
    52  
    53  ```
    54  WARN[06-17|21:58:10] abnormal conn rate                       module=app/server rate=0.500 low=0.100 high=0.800
    55  INFO[06-17|21:58:10] connection open                          module=app/server raddr=10.0.0.1
    56  ```
    57  
    58  ## Breaking API Changes
    59  The following commits broke API stability. This reference is intended to help you understand the consequences of updating to a newer version
    60  of 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?
    69  Yes. Use `log.Ctx`:
    70  
    71  ```go
    72  srvlog := log.New(log.Ctx{"module": "app/server"})
    73  srvlog.Warn("abnormal conn rate", log.Ctx{"rate": curRate, "low": lowRate, "high": highRate})
    74  ```
    75  
    76  ## License
    77  Apache