.readme.tmpl

Documentation: go.uber.org/zap

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