⚡ zap

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 than other structured logging packages and includes both structured and printf-style APIs.

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.

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 and FAQ 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.¹

Log a message and 10 fields:

Package	Time	Bytes Allocated	Objects Allocated
⚡ zap	1692 ns/op	705 B/op	2 allocs/op
⚡ zap (sugared)	2507 ns/op	1610 B/op	20 allocs/op
go-kit	6327 ns/op	2895 B/op	66 allocs/op
lion	8036 ns/op	5807 B/op	63 allocs/op
logrus	8970 ns/op	6092 B/op	78 allocs/op
apex/log	17101 ns/op	3832 B/op	65 allocs/op
log15	21398 ns/op	5632 B/op	93 allocs/op

Log a message with a logger that already has 10 fields of context:

Package	Time	Bytes Allocated	Objects Allocated
⚡ zap	467 ns/op	0 B/op	0 allocs/op
⚡ zap (sugared)	597 ns/op	80 B/op	2 allocs/op
lion	5172 ns/op	4074 B/op	38 allocs/op
go-kit	6892 ns/op	3078 B/op	53 allocs/op
logrus	8102 ns/op	4564 B/op	63 allocs/op
apex/log	15332 ns/op	2897 B/op	51 allocs/op
log15	16905 ns/op	2642 B/op	44 allocs/op

Log a static string, without any context or printf-style templating:

Package	Time	Bytes Allocated	Objects Allocated
⚡ zap	465 ns/op	0 B/op	0 allocs/op
standard library	602 ns/op	80 B/op	2 allocs/op
⚡ zap (sugared)	647 ns/op	80 B/op	2 allocs/op
go-kit	994 ns/op	656 B/op	13 allocs/op
lion	1402 ns/op	1224 B/op	10 allocs/op
logrus	2299 ns/op	1505 B/op	27 allocs/op
apex/log	3148 ns/op	584 B/op	11 allocs/op
log15	6329 ns/op	1592 B/op	26 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.

---

Released under the MIT License.

¹ In particular, keep in mind that we may be benchmarking against slightly older versions of other packages. Versions are pinned in zap's glide.lock file. ↩