Skip to main content

⚡ zap GoDoc Build Status Coverage Status

Go 中快速、结构化、分级的日志记录。

安装

go get -u go.uber.org/zap

请注意,zap 仅支持 Go 的两个最新次要版本。

Quick Start

在性能良好但不重要的情况下,使用 SugaredLogger. 它比其他结构化日志记录包快 4-10 倍,并且包括结构化和printf样式 API。

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)

当性能和类型安全至关重要时,请使用Logger. 它甚至比 the 还要快,SugaredLogger并且分配得更少,但它只支持结构化日志记录。

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

对于登录热路径的应用程序,基于反射的序列化和字符串格式化非常昂贵——它们是 CPU 密集型的并且会进行许多小分配。换句话说,使用encoding/jsonand fmt.Fprintf记录大量的interface{}s 会使您的应用程序变慢。

Zap 采取了不同的方法。它包括一个无反射、零分配的 JSON 编码器,并且基础Logger尽可能避免序列化开销和分配。SugaredLogger 通过在此基础上构建高级,zap 允许用户选择何时需要计算每个分配,以及何时他们更喜欢更熟悉、松散类型的 API。

根据其自己的基准测试套件衡量,zap 不仅比同类结构化日志记录包性能更高,而且比标准库更快。像所有基准一样,对这些基准持保留态度。1

记录一条消息和 10 个字段:

PackageTimeTime % to zapObjects Allocated
⚡ zap2900 ns/op+0%5 allocs/op
⚡ zap (sugared)3475 ns/op+20%10 allocs/op
zerolog10639 ns/op+267%32 allocs/op
go-kit14434 ns/op+398%59 allocs/op
logrus17104 ns/op+490%81 allocs/op
apex/log32424 ns/op+1018%66 allocs/op
log1533579 ns/op+1058%76 allocs/op

使用已经有 10 个上下文字段的记录器记录消息:

PackageTimeTime % to zapObjects Allocated
⚡ zap373 ns/op+0%0 allocs/op
⚡ zap (sugared)452 ns/op+21%1 allocs/op
zerolog288 ns/op-23%0 allocs/op
go-kit11785 ns/op+3060%58 allocs/op
logrus19629 ns/op+5162%70 allocs/op
log1521866 ns/op+5762%72 allocs/op
apex/log30890 ns/op+8182%55 allocs/op

记录一个静态字符串,没有任何上下文或 printf-style 模板:

PackageTimeTime % to zapObjects Allocated
⚡ zap381 ns/op+0%0 allocs/op
⚡ zap (sugared)410 ns/op+8%1 allocs/op
zerolog369 ns/op-3%0 allocs/op
standard library385 ns/op+1%2 allocs/op
go-kit606 ns/op+59%11 allocs/op
logrus1730 ns/op+354%25 allocs/op
apex/log1998 ns/op+424%7 allocs/op
log154546 ns/op+1093%22 allocs/op

Development Status: Stable

所有 API 均已完成,在 1.x 系列版本中不会进行重大更改。semver-aware 依赖管理系统的用户应该将 zap 固定到^1.

Contributing

We encourage and support an active, healthy community of contributors —
including you! Details are in the [contribution guide](CONTRIBUTING.md) and
the [code of conduct](CODE_OF_CONDUCT.md). 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.

<hr>

Released under the [MIT License](LICENSE.txt).

<sup id="footnote-versions">1</sup> 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. [↩](#anchor-versions)