1# :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 — 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 103[ci-img]: https://travis-ci.com/uber-go/zap.svg?branch=master 104[ci]: https://travis-ci.com/uber-go/zap 105[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 109 110