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