zap README

The project's README from github.com/uber-go/zap. As one markdown file: README.md.

:zap: zap

Blazing fast, structured, leveled logging in Go.

Zap logo

GoDoc Build Status Coverage Status

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: zap 656 ns/op +0% 5 allocs/op
:zap: zap (sugared) 935 ns/op +43% 10 allocs/op
zerolog 380 ns/op -42% 1 allocs/op
go-kit 2249 ns/op +243% 57 allocs/op
slog (LogAttrs) 2479 ns/op +278% 40 allocs/op
slog 2481 ns/op +278% 42 allocs/op
apex/log 9591 ns/op +1362% 63 allocs/op
log15 11393 ns/op +1637% 75 allocs/op
logrus 11654 ns/op +1677% 79 allocs/op

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

Package Time Time % to zap Objects Allocated
:zap: zap 67 ns/op +0% 0 allocs/op
:zap: zap (sugared) 84 ns/op +25% 1 allocs/op
zerolog 35 ns/op -48% 0 allocs/op
slog 193 ns/op +188% 0 allocs/op
slog (LogAttrs) 200 ns/op +199% 0 allocs/op
go-kit 2460 ns/op +3572% 56 allocs/op
log15 9038 ns/op +13390% 70 allocs/op
apex/log 9068 ns/op +13434% 53 allocs/op
logrus 10521 ns/op +15603% 68 allocs/op

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

Package Time Time % to zap Objects Allocated
:zap: zap 63 ns/op +0% 0 allocs/op
:zap: zap (sugared) 81 ns/op +29% 1 allocs/op
zerolog 32 ns/op -49% 0 allocs/op
standard library 124 ns/op +97% 1 allocs/op
slog 196 ns/op +211% 0 allocs/op
slog (LogAttrs) 200 ns/op +217% 0 allocs/op
go-kit 213 ns/op +238% 9 allocs/op
apex/log 771 ns/op +1124% 5 allocs/op
logrus 1439 ns/op +2184% 23 allocs/op
log15 2069 ns/op +3184% 20 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 [email protected]. 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. ↩

zap (uber-go/zap)

Searching Database…

24.7K ·GitHub
Zap
这是什么？Zap 是一个为 Go 语言打造的结构化、分级日志库，专为高频热路径日志场景下的高性能需求而设计。
它是框架还是库？它是一个需要导入使用的 Go 库，不是独立的应用程序或框架，没有服务器或界面组件。
我要怎么把它加到项目里？运行 'go get -u go.uber.org/zap' 命令，然后导入它，再从 SugaredLogger 或 Logger 接口中任选一个使用。
用它需要什么特别的条件吗，比如特定的 Go 版本？只需要 Go 工具链即可；zap 只支持最近的两个 Go 次要版本。
和 SugaredLogger 相比，高速的 Logger 会有什么代价吗？类型安全的 Logger 速度更快、内存分配更少，但只支持结构化日志（不支持 printf 风格的调用）；而 SugaredLogger 稍慢、内存分配更多，但同时支持结构化和 printf 风格的接口。
zap 为什么比其他日志包快？它使用了不依赖反射、零内存分配的 JSON 编码器，并避免了序列化开销；而其他依赖 encoding/json 或 fmt.Fprintf 风格格式化的库则没有这些优化。
zap 比标准库和其他日志库快多少？基准测试显示，zap 记录一个静态字符串耗时 63 ns/op，且零内存分配；标准库为 124 ns/op，而 logrus、apex/log 等包则超过 1000 ns/op。
zap 的 API 够稳定，可以放心依赖吗？可以。zap 目前处于稳定状态，所有 1.x 版本的 API 均已定型，1.x 系列内也没有计划引入不兼容的变更。
我该选 Logger 还是 SugaredLogger？如果每次内存分配都很关键，并且只需要结构化日志，就用 Logger；如果想要 printf 风格的便利性，并能接受一定的性能损耗，就用 SugaredLogger。
What are similar projects?zerolog, gofr, kratos, chi, quic-go, httprouter, pino, telegraf
Which topics is it in?logging, golang, performance, go, api, library, developer-tools, mit, open-source
Creator
uber-go
Size
1.9 MB
Stars
24.7K
Updated
CommitSep 16Releasev1.28.0Apr 28
Age
10y
Commits · 90 Days