Blazing fast, structured, leveled logging in Go.
Clone or download
iaroslav-ciupin and akshayjshah Add zaptest logger option to wrap zap.Option's (#610)
Add a wrapper that converts any `zap.Option` into a `zaptest.LoggerOption`.
Latest commit 67bc79d Aug 15, 2018
Permalink
Failed to load latest commit information.
benchmarks Update tests to use zap.Field alias Apr 13, 2018
buffer Pool the buffer and encoder used for generic JSON reflection (#602) Jun 27, 2018
internal Make zaptest a wrapper around internal/ztest Oct 31, 2017
scripts Really upload coverage to codecov (#446) Jun 10, 2017
zapcore MapObjectEncoder: Empty arrays should not be nil (#614) Jul 31, 2018
zapgrpc Add a gRPC compatibility wrapper (#402) Apr 14, 2017
zaptest Add zaptest logger option to wrap zap.Option's (#610) Aug 14, 2018
.codecov.yml Set a static test coverage target (#472) Jul 8, 2017
.gitignore Initial commit Feb 19, 2016
.readme.tmpl Remove duplicate word (#590) May 30, 2018
.travis.yml Test with latest patch releases of Go (#583) May 2, 2018
CHANGELOG.md Prepare for v1.9.1 Aug 6, 2018
CODE_OF_CONDUCT.md Add a code of conduct (#486) Aug 2, 2017
CONTRIBUTING.md Add a code of conduct (#486) Aug 2, 2017
FAQ.md Add github.com/blendle/zapdriver to list of extensions (#596) May 30, 2018
LICENSE.txt Update year in licensing setup (#462) Jun 30, 2017
Makefile Test on Go 1.10 and 1.9 Apr 13, 2018
README.md Remove duplicate word (#590) May 30, 2018
array.go Add an alias for zapcore.Field Apr 13, 2018
array_test.go MapObjectEncoder: Empty arrays should not be nil (#614) Jul 31, 2018
check_license.sh Update year in licensing setup (#462) Jun 30, 2017
common_test.go Export zap's internal observing logger (#372) Mar 14, 2017
config.go Make user-supplied sinks operate on URIs (#606) Jul 19, 2018
config_test.go Skip zap stack frames in stacktrace output (#491) Aug 17, 2017
doc.go Fix GoDoc references to Printf (#587) May 2, 2018
encoder.go Add documentation and examples for zap (#466) Jul 8, 2017
encoder_test.go Add RegisterEncoder functionality (#348) Mar 10, 2017
error.go Add an alias for zapcore.Field Apr 13, 2018
error_test.go MapObjectEncoder: Empty arrays should not be nil (#614) Jul 31, 2018
example_test.go Small documentation formatting fixes (#473) Jul 9, 2017
field.go Add an alias for zapcore.Field Apr 13, 2018
field_test.go Update tests to use zap.Field alias Apr 13, 2018
flag.go Add documentation and examples for zap (#466) Jul 8, 2017
flag_test.go Add test coverage for using levels in a FlagSet (#257) Feb 15, 2017
glide.lock Add benchmarks for zerolog (#483) Jul 25, 2017
glide.yaml Add benchmarks for zerolog (#483) Jul 25, 2017
global.go Add an alias for zapcore.Field Apr 13, 2018
global_test.go Update tests to use zap.Field alias Apr 13, 2018
http_handler.go use http constants for method (#597) May 31, 2018
http_handler_test.go Clean up comments Feb 15, 2017
level.go Fix typos and remove an unnecessary conditional (#519) Oct 30, 2017
level_test.go Make zap.AtomicLevel implement fmt.Stringer (#431) May 12, 2017
logger.go Add an alias for zapcore.Field Apr 13, 2018
logger_bench_test.go Update tests to use zap.Field alias Apr 13, 2018
logger_test.go Update tests to use zap.Field alias Apr 13, 2018
options.go Add an alias for zapcore.Field Apr 13, 2018
sink.go Make user-supplied sinks operate on URIs (#606) Jul 19, 2018
sink_test.go Make user-supplied sinks operate on URIs (#606) Jul 19, 2018
stacktrace.go Remove unused code to ignore runtime stack frames (#493) Aug 18, 2017
stacktrace_ext_test.go Verify test dependencies can be found in vendor before symlinking (#516) Oct 23, 2017
stacktrace_test.go Skip zap stack frames in stacktrace output (#491) Aug 17, 2017
sugar.go Add an alias for zapcore.Field Apr 13, 2018
sugar_test.go Update tests to use zap.Field alias Apr 13, 2018
time.go Migrate zap to use zapcore Feb 15, 2017
time_test.go Migrate zap to use zapcore Feb 15, 2017
writer.go Make user-supplied sinks operate on URIs (#606) Jul 19, 2018
writer_test.go Make user-supplied sinks operate on URIs (#606) Jul 19, 2018

README.md

⚡️ 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:

Package Time Objects Allocated
⚡️ zap 3131 ns/op 5 allocs/op
⚡️ zap (sugared) 4173 ns/op 21 allocs/op
zerolog 16154 ns/op 90 allocs/op
lion 16341 ns/op 111 allocs/op
go-kit 17049 ns/op 126 allocs/op
logrus 23662 ns/op 142 allocs/op
log15 36351 ns/op 149 allocs/op
apex/log 42530 ns/op 126 allocs/op

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

Package Time Objects Allocated
⚡️ zap 380 ns/op 0 allocs/op
⚡️ zap (sugared) 564 ns/op 2 allocs/op
zerolog 321 ns/op 0 allocs/op
lion 7092 ns/op 39 allocs/op
go-kit 20226 ns/op 115 allocs/op
logrus 22312 ns/op 130 allocs/op
log15 28788 ns/op 79 allocs/op
apex/log 42063 ns/op 115 allocs/op

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

Package Time Objects Allocated
⚡️ zap 361 ns/op 0 allocs/op
⚡️ zap (sugared) 534 ns/op 2 allocs/op
zerolog 323 ns/op 0 allocs/op
standard library 575 ns/op 2 allocs/op
go-kit 922 ns/op 13 allocs/op
lion 1413 ns/op 10 allocs/op
logrus 2291 ns/op 27 allocs/op
apex/log 3690 ns/op 11 allocs/op
log15 5954 ns/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.

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.