vendor/github.com/go-kit/kit/log/README.md

   1 # package log
   2
   3 `package log` provides a minimal interface for structured logging in services.
   4 It may be wrapped to encode conventions, enforce type-safety, provide leveled
   5 logging, and so on. It can be used for both typical application log events,
   6 and log-structured data streams.
   7
   8 ## Structured logging
   9
  10 Structured logging is, basically, conceding to the reality that logs are
  11 _data_, and warrant some level of schematic rigor. Using a stricter,
  12 key/value-oriented message format for our logs, containing contextual and
  13 semantic information, makes it much easier to get insight into the
  14 operational activity of the systems we build. Consequently, `package log` is
  15 of the strong belief that "[the benefits of structured logging outweigh the
  16 minimal effort involved](https://www.thoughtworks.com/radar/techniques/structured-logging)".
  17
  18 Migrating from unstructured to structured logging is probably a lot easier
  19 than you'd expect.
  20
  21 ```go
  22 // Unstructured
  23 log.Printf("HTTP server listening on %s", addr)
  24
  25 // Structured
  26 logger.Log("transport", "HTTP", "addr", addr, "msg", "listening")
  27 ```
  28
  29 ## Usage
  30
  31 ### Typical application logging
  32
  33 ```go
  34 w := log.NewSyncWriter(os.Stderr)
  35 logger := log.NewLogfmtLogger(w)
  36 logger.Log("question", "what is the meaning of life?", "answer", 42)
  37
  38 // Output:
  39 // question="what is the meaning of life?" answer=42
  40 ```
  41
  42 ### Contextual Loggers
  43
  44 ```go
  45 func main() {
  46         var logger log.Logger
  47         logger = log.NewLogfmtLogger(log.NewSyncWriter(os.Stderr))
  48         logger = log.With(logger, "instance_id", 123)
  49
  50         logger.Log("msg", "starting")
  51         NewWorker(log.With(logger, "component", "worker")).Run()
  52         NewSlacker(log.With(logger, "component", "slacker")).Run()
  53 }
  54
  55 // Output:
  56 // instance_id=123 msg=starting
  57 // instance_id=123 component=worker msg=running
  58 // instance_id=123 component=slacker msg=running
  59 ```
  60
  61 ### Interact with stdlib logger
  62
  63 Redirect stdlib logger to Go kit logger.
  64
  65 ```go
  66 import (
  67         "os"
  68         stdlog "log"
  69         kitlog "github.com/go-kit/kit/log"
  70 )
  71
  72 func main() {
  73         logger := kitlog.NewJSONLogger(kitlog.NewSyncWriter(os.Stdout))
  74         stdlog.SetOutput(kitlog.NewStdlibAdapter(logger))
  75         stdlog.Print("I sure like pie")
  76 }
  77
  78 // Output:
  79 // {"msg":"I sure like pie","ts":"2016/01/01 12:34:56"}
  80 ```
  81
  82 Or, if, for legacy reasons, you need to pipe all of your logging through the
  83 stdlib log package, you can redirect Go kit logger to the stdlib logger.
  84
  85 ```go
  86 logger := kitlog.NewLogfmtLogger(kitlog.StdlibWriter{})
  87 logger.Log("legacy", true, "msg", "at least it's something")
  88
  89 // Output:
  90 // 2016/01/01 12:34:56 legacy=true msg="at least it's something"
  91 ```
  92
  93 ### Timestamps and callers
  94
  95 ```go
  96 var logger log.Logger
  97 logger = log.NewLogfmtLogger(log.NewSyncWriter(os.Stderr))
  98 logger = log.With(logger, "ts", log.DefaultTimestampUTC, "caller", log.DefaultCaller)
  99
 100 logger.Log("msg", "hello")
 101
 102 // Output:
 103 // ts=2016-01-01T12:34:56Z caller=main.go:15 msg=hello
 104 ```
 105
 106 ## Supported output formats
 107
 108 - [Logfmt](https://brandur.org/logfmt) ([see also](https://blog.codeship.com/logfmt-a-log-format-thats-easy-to-read-and-write))
 109 - JSON
 110
 111 ## Enhancements
 112
 113 `package log` is centered on the one-method Logger interface.
 114
 115 ```go
 116 type Logger interface {
 117         Log(keyvals ...interface{}) error
 118 }
 119 ```
 120
 121 This interface, and its supporting code like is the product of much iteration
 122 and evaluation. For more details on the evolution of the Logger interface,
 123 see [The Hunt for a Logger Interface](http://go-talks.appspot.com/github.com/ChrisHines/talks/structured-logging/structured-logging.slide#1),
 124 a talk by [Chris Hines](https://github.com/ChrisHines).
 125 Also, please see
 126 [#63](https://github.com/go-kit/kit/issues/63),
 127 [#76](https://github.com/go-kit/kit/pull/76),
 128 [#131](https://github.com/go-kit/kit/issues/131),
 129 [#157](https://github.com/go-kit/kit/pull/157),
 130 [#164](https://github.com/go-kit/kit/issues/164), and
 131 [#252](https://github.com/go-kit/kit/pull/252)
 132 to review historical conversations about package log and the Logger interface.
 133
 134 Value-add packages and suggestions,
 135 like improvements to [the leveled logger](https://godoc.org/github.com/go-kit/kit/log/level),
 136 are of course welcome. Good proposals should
 137
 138 - Be composable with [contextual loggers](https://godoc.org/github.com/go-kit/kit/log#With),
 139 - Not break the behavior of [log.Caller](https://godoc.org/github.com/go-kit/kit/log#Caller) in any wrapped contextual loggers, and
 140 - Be friendly to packages that accept only an unadorned log.Logger.
 141
 142 ## Benchmarks & comparisons
 143
 144 There are a few Go logging benchmarks and comparisons that include Go kit's package log.
 145
 146 - [imkira/go-loggers-bench](https://github.com/imkira/go-loggers-bench) includes kit/log
 147 - [uber-common/zap](https://github.com/uber-common/zap), a zero-alloc logging library, includes a comparison with kit/log