cmd/bpa-operator/vendor/go.uber.org/zap/README.md

   1 # :zap: zap [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov]
   2
   3 Blazing fast, structured, leveled logging in Go.
   4
   5 ## Installation
   6
   7 `go get -u go.uber.org/zap`
   8
   9 Note that zap only supports the two most recent minor versions of Go.
  10
  11 ## Quick Start
  12
  13 In contexts where performance is nice, but not critical, use the
  14 `SugaredLogger`. It's 4-10x faster than other structured logging
  15 packages and includes both structured and `printf`-style APIs.
  16
  17 ```go
  18 logger, _ := zap.NewProduction()
  19 defer logger.Sync() // flushes buffer, if any
  20 sugar := logger.Sugar()
  21 sugar.Infow("failed to fetch URL",
  22   // Structured context as loosely typed key-value pairs.
  23   "url", url,
  24   "attempt", 3,
  25   "backoff", time.Second,
  26 )
  27 sugar.Infof("Failed to fetch URL: %s", url)
  28 ```
  29
  30 When performance and type safety are critical, use the `Logger`. It's even
  31 faster than the `SugaredLogger` and allocates far less, but it only supports
  32 structured logging.
  33
  34 ```go
  35 logger, _ := zap.NewProduction()
  36 defer logger.Sync()
  37 logger.Info("failed to fetch URL",
  38   // Structured context as strongly typed Field values.
  39   zap.String("url", url),
  40   zap.Int("attempt", 3),
  41   zap.Duration("backoff", time.Second),
  42 )
  43 ```
  44
  45 See the [documentation][doc] and [FAQ](FAQ.md) for more details.
  46
  47 ## Performance
  48
  49 For applications that log in the hot path, reflection-based serialization and
  50 string formatting are prohibitively expensive &mdash; they're CPU-intensive
  51 and make many small allocations. Put differently, using `encoding/json` and
  52 `fmt.Fprintf` to log tons of `interface{}`s makes your application slow.
  53
  54 Zap takes a different approach. It includes a reflection-free, zero-allocation
  55 JSON encoder, and the base `Logger` strives to avoid serialization overhead
  56 and allocations wherever possible. By building the high-level `SugaredLogger`
  57 on that foundation, zap lets users *choose* when they need to count every
  58 allocation and when they'd prefer a more familiar, loosely typed API.
  59
  60 As measured by its own [benchmarking suite][], not only is zap more performant
  61 than comparable structured logging packages &mdash; it's also faster than the
  62 standard library. Like all benchmarks, take these with a grain of salt.<sup
  63 id="anchor-versions">[1](#footnote-versions)</sup>
  64
  65 Log a message and 10 fields:
  66
  67 | Package | Time | Objects Allocated |
  68 | :--- | :---: | :---: |
  69 | :zap: zap | 3131 ns/op | 5 allocs/op |
  70 | :zap: zap (sugared) | 4173 ns/op | 21 allocs/op |
  71 | zerolog | 16154 ns/op | 90 allocs/op |
  72 | lion | 16341 ns/op | 111 allocs/op |
  73 | go-kit | 17049 ns/op | 126 allocs/op |
  74 | logrus | 23662 ns/op | 142 allocs/op |
  75 | log15 | 36351 ns/op | 149 allocs/op |
  76 | apex/log | 42530 ns/op | 126 allocs/op |
  77
  78 Log a message with a logger that already has 10 fields of context:
  79
  80 | Package | Time | Objects Allocated |
  81 | :--- | :---: | :---: |
  82 | :zap: zap | 380 ns/op | 0 allocs/op |
  83 | :zap: zap (sugared) | 564 ns/op | 2 allocs/op |
  84 | zerolog | 321 ns/op | 0 allocs/op |
  85 | lion | 7092 ns/op | 39 allocs/op |
  86 | go-kit | 20226 ns/op | 115 allocs/op |
  87 | logrus | 22312 ns/op | 130 allocs/op |
  88 | log15 | 28788 ns/op | 79 allocs/op |
  89 | apex/log | 42063 ns/op | 115 allocs/op |
  90
  91 Log a static string, without any context or `printf`-style templating:
  92
  93 | Package | Time | Objects Allocated |
  94 | :--- | :---: | :---: |
  95 | :zap: zap | 361 ns/op | 0 allocs/op |
  96 | :zap: zap (sugared) | 534 ns/op | 2 allocs/op |
  97 | zerolog | 323 ns/op | 0 allocs/op |
  98 | standard library | 575 ns/op | 2 allocs/op |
  99 | go-kit | 922 ns/op | 13 allocs/op |
 100 | lion | 1413 ns/op | 10 allocs/op |
 101 | logrus | 2291 ns/op | 27 allocs/op |
 102 | apex/log | 3690 ns/op | 11 allocs/op |
 103 | log15 | 5954 ns/op | 26 allocs/op |
 104
 105 ## Development Status: Stable
 106
 107 All APIs are finalized, and no breaking changes will be made in the 1.x series
 108 of releases. Users of semver-aware dependency management systems should pin
 109 zap to `^1`.
 110
 111 ## Contributing
 112
 113 We encourage and support an active, healthy community of contributors &mdash;
 114 including you! Details are in the [contribution guide](CONTRIBUTING.md) and
 115 the [code of conduct](CODE_OF_CONDUCT.md). The zap maintainers keep an eye on
 116 issues and pull requests, but you can also report any negative conduct to
 117 oss-conduct@uber.com. That email list is a private, safe space; even the zap
 118 maintainers don't have access, so don't hesitate to hold us to a high
 119 standard.
 120
 121 <hr>
 122
 123 Released under the [MIT License](LICENSE.txt).
 124
 125 <sup id="footnote-versions">1</sup> In particular, keep in mind that we may be
 126 benchmarking against slightly older versions of other packages. Versions are
 127 pinned in zap's [glide.lock][] file. [↩](#anchor-versions)
 128
 129 [doc-img]: https://godoc.org/go.uber.org/zap?status.svg
 130 [doc]: https://godoc.org/go.uber.org/zap
 131 [ci-img]: https://travis-ci.org/uber-go/zap.svg?branch=master
 132 [ci]: https://travis-ci.org/uber-go/zap
 133 [cov-img]: https://codecov.io/gh/uber-go/zap/branch/master/graph/badge.svg
 134 [cov]: https://codecov.io/gh/uber-go/zap
 135 [benchmarking suite]: https://github.com/uber-go/zap/tree/master/benchmarks
 136 [glide.lock]: https://github.com/uber-go/zap/blob/master/glide.lock