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