# :zap: zap [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov] Blazing fast, structured, leveled logging in Go. ## Installation `go get -u go.uber.org/zap` Note that zap only supports the two most recent minor versions of Go. ## Quick Start In contexts where performance is nice, but not critical, use the `SugaredLogger`. It's 4-10x faster than other structured logging packages and includes both structured and `printf`-style APIs. ```go logger, _ := zap.NewProduction() defer logger.Sync() // flushes buffer, if any sugar := logger.Sugar() sugar.Infow("failed to fetch URL", // Structured context as loosely typed key-value pairs. "url", url, "attempt", 3, "backoff", time.Second, ) sugar.Infof("Failed to fetch URL: %s", url) ``` When performance and type safety are critical, use the `Logger`. It's even faster than the `SugaredLogger` and allocates far less, but it only supports structured logging. ```go logger, _ := zap.NewProduction() defer logger.Sync() logger.Info("failed to fetch URL", // Structured context as strongly typed Field values. zap.String("url", url), zap.Int("attempt", 3), zap.Duration("backoff", time.Second), ) ``` See the [documentation][doc] and [FAQ](FAQ.md) for more details. ## Performance For applications that log in the hot path, reflection-based serialization and string formatting are prohibitively expensive — they're CPU-intensive and make many small allocations. Put differently, using `encoding/json` and `fmt.Fprintf` to log tons of `interface{}`s makes your application slow. Zap takes a different approach. It includes a reflection-free, zero-allocation JSON encoder, and the base `Logger` strives to avoid serialization overhead and allocations wherever possible. By building the high-level `SugaredLogger` on that foundation, zap lets users *choose* when they need to count every allocation and when they'd prefer a more familiar, loosely typed API. As measured by its own [benchmarking suite][], not only is zap more performant than comparable structured logging packages — it's also faster than the standard library. Like all benchmarks, take these with a grain of salt.[1](#footnote-versions) Log a message and 10 fields: | Package | Time | Time % to zap | Objects Allocated | | :------ | :--: | :-----------: | :---------------: | | :zap: zap | 1744 ns/op | +0% | 5 allocs/op | :zap: zap (sugared) | 2483 ns/op | +42% | 10 allocs/op | zerolog | 918 ns/op | -47% | 1 allocs/op | go-kit | 5590 ns/op | +221% | 57 allocs/op | slog | 5640 ns/op | +223% | 40 allocs/op | apex/log | 21184 ns/op | +1115% | 63 allocs/op | logrus | 24338 ns/op | +1296% | 79 allocs/op | log15 | 26054 ns/op | +1394% | 74 allocs/op Log a message with a logger that already has 10 fields of context: | Package | Time | Time % to zap | Objects Allocated | | :------ | :--: | :-----------: | :---------------: | | :zap: zap | 193 ns/op | +0% | 0 allocs/op | :zap: zap (sugared) | 227 ns/op | +18% | 1 allocs/op | zerolog | 81 ns/op | -58% | 0 allocs/op | slog | 322 ns/op | +67% | 0 allocs/op | go-kit | 5377 ns/op | +2686% | 56 allocs/op | apex/log | 19518 ns/op | +10013% | 53 allocs/op | log15 | 19812 ns/op | +10165% | 70 allocs/op | logrus | 21997 ns/op | +11297% | 68 allocs/op Log a static string, without any context or `printf`-style templating: | Package | Time | Time % to zap | Objects Allocated | | :------ | :--: | :-----------: | :---------------: | | :zap: zap | 165 ns/op | +0% | 0 allocs/op | :zap: zap (sugared) | 212 ns/op | +28% | 1 allocs/op | zerolog | 95 ns/op | -42% | 0 allocs/op | slog | 296 ns/op | +79% | 0 allocs/op | go-kit | 415 ns/op | +152% | 9 allocs/op | standard library | 422 ns/op | +156% | 2 allocs/op | apex/log | 1601 ns/op | +870% | 5 allocs/op | logrus | 3017 ns/op | +1728% | 23 allocs/op | log15 | 3469 ns/op | +2002% | 20 allocs/op ## Development Status: Stable All APIs are finalized, and no breaking changes will be made in the 1.x series of releases. Users of semver-aware dependency management systems should pin zap to `^1`. ## Contributing We encourage and support an active, healthy community of contributors — including you! Details are in the [contribution guide](CONTRIBUTING.md) and the [code of conduct](CODE_OF_CONDUCT.md). The zap maintainers keep an eye on issues and pull requests, but you can also report any negative conduct to oss-conduct@uber.com. That email list is a private, safe space; even the zap maintainers don't have access, so don't hesitate to hold us to a high standard.
Released under the [MIT License](LICENSE.txt). 1 In particular, keep in mind that we may be benchmarking against slightly older versions of other packages. Versions are pinned in the [benchmarks/go.mod][] file. [↩](#anchor-versions) [doc-img]: https://pkg.go.dev/badge/go.uber.org/zap [doc]: https://pkg.go.dev/go.uber.org/zap [ci-img]: https://github.com/uber-go/zap/actions/workflows/go.yml/badge.svg [ci]: https://github.com/uber-go/zap/actions/workflows/go.yml [cov-img]: https://codecov.io/gh/uber-go/zap/branch/master/graph/badge.svg [cov]: https://codecov.io/gh/uber-go/zap [benchmarking suite]: https://github.com/uber-go/zap/tree/master/benchmarks [benchmarks/go.mod]: https://github.com/uber-go/zap/blob/master/benchmarks/go.mod