tree: e0762ce4c14b389d4cc8b0076b2b411db054d547 [path history] [tgz]
  1. .codecov.yml
  2. .gitignore
  3. .readme.tmpl
  4. .travis.yml
  5. CHANGELOG.md
  6. CODE_OF_CONDUCT.md
  7. CONTRIBUTING.md
  8. FAQ.md
  9. LICENSE.txt
  10. Makefile
  11. README.md
  12. array.go
  13. buffer/
  14. check_license.sh
  15. config.go
  16. doc.go
  17. encoder.go
  18. error.go
  19. field.go
  20. flag.go
  21. glide.lock
  22. glide.yaml
  23. global.go
  24. global_go112.go
  25. global_prego112.go
  26. http_handler.go
  27. internal/
  28. level.go
  29. logger.go
  30. options.go
  31. sink.go
  32. stacktrace.go
  33. sugar.go
  34. time.go
  35. writer.go
  36. zapcore/
vendor/go.uber.org/zap/README.md

:zap: zap GoDoc Build Status Coverage Status

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.

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.1

Log a message and 10 fields:

PackageTimeObjects Allocated
:zap: zap3131 ns/op5 allocs/op
:zap: zap (sugared)4173 ns/op21 allocs/op
zerolog16154 ns/op90 allocs/op
lion16341 ns/op111 allocs/op
go-kit17049 ns/op126 allocs/op
logrus23662 ns/op142 allocs/op
log1536351 ns/op149 allocs/op
apex/log42530 ns/op126 allocs/op

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

PackageTimeObjects Allocated
:zap: zap380 ns/op0 allocs/op
:zap: zap (sugared)564 ns/op2 allocs/op
zerolog321 ns/op0 allocs/op
lion7092 ns/op39 allocs/op
go-kit20226 ns/op115 allocs/op
logrus22312 ns/op130 allocs/op
log1528788 ns/op79 allocs/op
apex/log42063 ns/op115 allocs/op

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

PackageTimeObjects Allocated
:zap: zap361 ns/op0 allocs/op
:zap: zap (sugared)534 ns/op2 allocs/op
zerolog323 ns/op0 allocs/op
standard library575 ns/op2 allocs/op
go-kit922 ns/op13 allocs/op
lion1413 ns/op10 allocs/op
logrus2291 ns/op27 allocs/op
apex/log3690 ns/op11 allocs/op
log155954 ns/op26 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 and the code of conduct. 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.

1 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.