Skip to content
Blazing fast, structured, leveled logging in Go.
Go Other
  1. Go 99.6%
  2. Other 0.4%
Branch: master
Clone or download
abhinav Prepare release v1.13.0 (#762)
This prepares release v1.13.0 with #758 in it.
Latest commit 33e58d4 Nov 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmarks Switch to Go modules Oct 30, 2019
buffer Pool the buffer and encoder used for generic JSON reflection (#602) Jun 27, 2018
internal internal/readme: Use benchmarks submodule Oct 30, 2019
zapcore Support nil fields for pointers to primitives (#758) Nov 13, 2019
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 ci: Use Go modules and ./... Oct 30, 2019
.readme.tmpl Re-run benchmarks and add % over zap measurement (#720) Jun 19, 2019
.travis.yml ci: Manage lint decision in travis.yml Oct 30, 2019
CHANGELOG.md Prepare release v1.13.0 (#762) Nov 13, 2019
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 ci: Manage lint decision in travis.yml Oct 30, 2019
README.md Preparing release v1.12.0 (#752) Oct 30, 2019
array.go Add an alias for zapcore.Field Apr 13, 2018
array_test.go Fix inconsistency between MapObjectEncoder's AddByteString and Append… Apr 29, 2019
checklicense.sh license: allow github to detect MIT license (#743) Sep 26, 2019
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 Fix typo in comment (#681) Feb 15, 2019
field.go Support nil fields for pointers to primitives (#758) Nov 13, 2019
field_test.go Support nil fields for pointers to primitives (#758) Nov 13, 2019
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.yaml Re-run benchmarks and add % over zap measurement (#720) Jun 19, 2019
global.go Fix call depth of standard logger in go1.12 (#706) Apr 29, 2019
global_go112.go Fix call depth of standard logger in go1.12 (#706) Apr 29, 2019
global_prego112.go Fix call depth of standard logger in go1.12 (#706) Apr 29, 2019
global_test.go global_test: Fix for modules Oct 30, 2019
go.mod Switch to Go modules Oct 30, 2019
go.sum Switch to Go modules Oct 30, 2019
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 TestStacktraceFiltersVendorZap: Fix for modules Oct 30, 2019
stacktrace_test.go
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
tools.go ci: Use Go modules and ./... Oct 30, 2019
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 Time % to zap Objects Allocated
⚡️ zap 862 ns/op +0% 5 allocs/op
⚡️ zap (sugared) 1250 ns/op +45% 11 allocs/op
zerolog 4021 ns/op +366% 76 allocs/op
go-kit 4542 ns/op +427% 105 allocs/op
apex/log 26785 ns/op +3007% 115 allocs/op
logrus 29501 ns/op +3322% 125 allocs/op
log15 29906 ns/op +3369% 122 allocs/op

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

Package Time Time % to zap Objects Allocated
⚡️ zap 126 ns/op +0% 0 allocs/op
⚡️ zap (sugared) 187 ns/op +48% 2 allocs/op
zerolog 88 ns/op -30% 0 allocs/op
go-kit 5087 ns/op +3937% 103 allocs/op
log15 18548 ns/op +14621% 73 allocs/op
apex/log 26012 ns/op +20544% 104 allocs/op
logrus 27236 ns/op +21516% 113 allocs/op

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

Package Time Time % to zap Objects Allocated
⚡️ zap 118 ns/op +0% 0 allocs/op
⚡️ zap (sugared) 191 ns/op +62% 2 allocs/op
zerolog 93 ns/op -21% 0 allocs/op
go-kit 280 ns/op +137% 11 allocs/op
standard library 499 ns/op +323% 2 allocs/op
apex/log 1990 ns/op +1586% 10 allocs/op
logrus 3129 ns/op +2552% 24 allocs/op
log15 3887 ns/op +3194% 23 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 the benchmarks/go.mod file.

You can’t perform that action at this time.