.readme.tmpl raw

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