• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

benchmarks/H23-Jul-2017-

buffer/H23-Jul-2017-

internal/H23-Jul-2017-

scripts/H23-Jul-2017-

zapcore/H23-Jul-2017-

zapgrpc/H23-Jul-2017-

zaptest/H23-Jul-2017-

.codecov.ymlH A D23-Jul-2017801

.gitignoreH A D23-Jul-2017293

.readme.tmplH A D23-Jul-20173.4 KiB

.travis.ymlH A D23-Jul-2017340

CHANGELOG.mdH A D23-Jul-20179 KiB

CONTRIBUTING.mdH A D23-Jul-20172.2 KiB

FAQ.mdH A D23-Jul-20175.4 KiB

MakefileH A D23-Jul-20172.2 KiB

README.mdH A D23-Jul-20174.7 KiB

array.goH A D23-Jul-20178 KiB

array_test.goH A D23-Jul-20175.1 KiB

check_license.shH A D23-Jul-2017294

common_test.goH A D23-Jul-20172 KiB

config.goH A D23-Jul-20178.6 KiB

config_test.goH A D23-Jul-20173.8 KiB

doc.goH A D23-Jul-20175.1 KiB

encoder.goH A D23-Jul-20172.7 KiB

encoder_test.goH A D23-Jul-20173.3 KiB

error.goH A D23-Jul-20172.7 KiB

error_test.goH A D23-Jul-20173.7 KiB

example_test.goH A D23-Jul-20179.8 KiB

field.goH A D23-Jul-201710.6 KiB

field_test.goH A D23-Jul-20178 KiB

flag.goH A D23-Jul-20171.6 KiB

flag_test.goH A D23-Jul-20173.2 KiB

glide.lockH A D23-Jul-20172.4 KiB

glide.yamlH A D23-Jul-2017771

global.goH A D23-Jul-20173.3 KiB

global_test.goH A D23-Jul-20174.1 KiB

http_handler.goH A D23-Jul-20172.4 KiB

http_handler_test.goH A D23-Jul-20174.2 KiB

level.goH A D23-Jul-20174.6 KiB

level_test.goH A D23-Jul-20173.7 KiB

logger.goH A D23-Jul-20179.9 KiB

logger_bench_test.goH A D23-Jul-20175.4 KiB

logger_test.goH A D23-Jul-201714.1 KiB

options.goH A D23-Jul-20173.9 KiB

stacktrace.goH A D23-Jul-20172.8 KiB

stacktrace_test.goH A D23-Jul-20171.6 KiB

sugar.goH A D23-Jul-201710.2 KiB

sugar_test.goH A D23-Jul-201713.1 KiB

time.goH A D23-Jul-20171.2 KiB

time_test.goH A D23-Jul-20171.5 KiB

writer.goH A D23-Jul-20173.1 KiB

writer_test.goH A D23-Jul-20173.7 KiB

README.md

1# :zap: zap [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov]
2
3Blazing fast, structured, leveled logging in Go.
4
5## Installation
6
7`go get -u go.uber.org/zap`
8
9Note that zap only supports the two most recent minor versions of Go.
10
11## Quick Start
12
13In contexts where performance is nice, but not critical, use the
14`SugaredLogger`. It's 4-10x faster than than other structured logging
15packages and includes both structured and `printf`-style APIs.
16
17```go
18logger, _ := zap.NewProduction()
19defer logger.Sync() // flushes buffer, if any
20sugar := logger.Sugar()
21sugar.Infow("failed to fetch URL",
22  // Structured context as loosely typed key-value pairs.
23  "url", url,
24  "attempt", 3,
25  "backoff", time.Second,
26)
27sugar.Infof("Failed to fetch URL: %s", url)
28```
29
30When performance and type safety are critical, use the `Logger`. It's even
31faster than the `SugaredLogger` and allocates far less, but it only supports
32structured logging.
33
34```go
35logger, _ := zap.NewProduction()
36defer logger.Sync()
37logger.Info("failed to fetch URL",
38  // Structured context as strongly typed Field values.
39  zap.String("url", url),
40  zap.Int("attempt", 3),
41  zap.Duration("backoff", time.Second),
42)
43```
44
45See the [documentation][doc] and [FAQ](FAQ.md) for more details.
46
47## Performance
48
49For applications that log in the hot path, reflection-based serialization and
50string formatting are prohibitively expensive — they're CPU-intensive
51and make many small allocations. Put differently, using `encoding/json` and
52`fmt.Fprintf` to log tons of `interface{}`s makes your application slow.
53
54Zap takes a different approach. It includes a reflection-free, zero-allocation
55JSON encoder, and the base `Logger` strives to avoid serialization overhead
56and allocations wherever possible. By building the high-level `SugaredLogger`
57on that foundation, zap lets users *choose* when they need to count every
58allocation and when they'd prefer a more familiar, loosely typed API.
59
60As measured by its own [benchmarking suite][], not only is zap more performant
61than comparable structured logging packages — it's also faster than the
62standard library. Like all benchmarks, take these with a grain of salt.<sup
63id="anchor-versions">[1](#footnote-versions)</sup>
64
65Log a message and 10 fields:
66
67| Package | Time | Bytes Allocated | Objects Allocated |
68| :--- | :---: | :---: | :---: |
69| :zap: zap | 1692 ns/op | 705 B/op | 2 allocs/op |
70| :zap: zap (sugared) | 2507 ns/op | 1610 B/op | 20 allocs/op |
71| go-kit | 6327 ns/op | 2895 B/op | 66 allocs/op |
72| lion | 8036 ns/op | 5807 B/op | 63 allocs/op |
73| logrus | 8970 ns/op | 6092 B/op | 78 allocs/op |
74| apex/log | 17101 ns/op | 3832 B/op | 65 allocs/op |
75| log15 | 21398 ns/op | 5632 B/op | 93 allocs/op |
76
77Log a message with a logger that already has 10 fields of context:
78
79| Package | Time | Bytes Allocated | Objects Allocated |
80| :--- | :---: | :---: | :---: |
81| :zap: zap | 467 ns/op | 0 B/op | 0 allocs/op |
82| :zap: zap (sugared) | 597 ns/op | 80 B/op | 2 allocs/op |
83| lion | 5172 ns/op | 4074 B/op | 38 allocs/op |
84| go-kit | 6892 ns/op | 3078 B/op | 53 allocs/op |
85| logrus | 8102 ns/op | 4564 B/op | 63 allocs/op |
86| apex/log | 15332 ns/op | 2897 B/op | 51 allocs/op |
87| log15 | 16905 ns/op | 2642 B/op | 44 allocs/op |
88
89Log a static string, without any context or `printf`-style templating:
90
91| Package | Time | Bytes Allocated | Objects Allocated |
92| :--- | :---: | :---: | :---: |
93| :zap: zap | 465 ns/op | 0 B/op | 0 allocs/op |
94| standard library | 602 ns/op | 80 B/op | 2 allocs/op |
95| :zap: zap (sugared) | 647 ns/op | 80 B/op | 2 allocs/op |
96| go-kit | 994 ns/op | 656 B/op | 13 allocs/op |
97| lion | 1402 ns/op | 1224 B/op | 10 allocs/op |
98| logrus | 2299 ns/op | 1505 B/op | 27 allocs/op |
99| apex/log | 3148 ns/op | 584 B/op | 11 allocs/op |
100| log15 | 6329 ns/op | 1592 B/op | 26 allocs/op |
101
102## Development Status: Stable
103
104All APIs are finalized, and no breaking changes will be made in the 1.x series
105of releases. Users of semver-aware dependency management systems should pin
106zap to `^1`.
107
108<hr>
109
110Released under the [MIT License](LICENSE.txt).
111
112<sup id="footnote-versions">1</sup> In particular, keep in mind that we may be
113benchmarking against slightly older versions of other packages. Versions are
114pinned in zap's [glide.lock][] file. [↩](#anchor-versions)
115
116[doc-img]: https://godoc.org/go.uber.org/zap?status.svg
117[doc]: https://godoc.org/go.uber.org/zap
118[ci-img]: https://travis-ci.org/uber-go/zap.svg?branch=master
119[ci]: https://travis-ci.org/uber-go/zap
120[cov-img]: https://codecov.io/gh/uber-go/zap/branch/master/graph/badge.svg
121[cov]: https://codecov.io/gh/uber-go/zap
122[benchmarking suite]: https://github.com/uber-go/zap/tree/master/benchmarks
123[glide.lock]: https://github.com/uber-go/zap/blob/master/glide.lock
124