首发地址：https://jianghushinian.cn/2023/03/19/use-of-zap-in-go-third-party-log-library/
zap 是由 Uber 公司开源的一款 Go 日志库，就像它的命名一样，zap 以快著称。官方 GitHub 仓库中只用一句话来概括 zap：「在 Go 中进行快速、结构化、分级的日志记录」。这句话简单明了的概括了 zap 的核心特性，今天我们就来介绍下 zap 日志库的基本使用和高级特性，以及如何在实际应用程序中使用，来提高应用程序的可靠性。
特点
zap 具有如下特点：
快，非常快，这也是 zap 最显著的特点。速度快的原因是 zap 避免使用 interface{} 和反射，并且使用 sync.Pool 减少堆内存分配。在 zap 面前 Logrus 的执行速度只有被吊打的份，你可以在官方 GitHub 仓库中看到 zap 与不同日志库的速度对比。
支持结构化日志记录。这是一个优秀的日志库必备功能。
支持七种日志级别：Debug、Info、Warn、Error、DPanic、Panic、Fatal，其中 DPanic 是指在开发环境下（development）记录日志后会进行 panic。
支持输出调用堆栈。
支持 Hooks 机制。
使用
基本使用
zap 基本使用方式如下：
package main
import ( "time"
"go.uber.org/zap")
func main() { // 生产环境 { logger, _ := zap.NewProduction() defer logger.Sync() // 刷新 buffer，保证日志最终会被输出
url := "https://jianghushinian.cn/" logger.Info("production failed to fetch URL", zap.String("url", url), // 因为没有使用 interface{} 和反射机制，所以需要指定具体类型 zap.Int("attempt", 3), zap.Duration("backoff", time.Second), ) }
// 开发环境 { logger, _ := zap.NewDevelopment() defer logger.Sync()
url := "https://jianghushinian.cn/" logger.Debug("development failed to fetch URL", zap.String("url", url), zap.Int("attempt", 3), zap.Duration("backoff", time.Second), ) }}
复制代码
zap 针对生产环境和开发环境提供了不同的函数来创建 Logger 对象。
如果想在日志后面追加 key-value，则需要根据 value 的数据类型使用 zap.String、zap.Int 等方法实现。这一点在使用上显然不如 Logrus 等其他日志库来的方便，但这也是 zap 速度快的原因之一，zap 内部尽量避免使用 interface{} 和反射来提高代码执行效率。
记录日志的 logger.Xxx 方法签名如下：
func (log *Logger) Info(msg string, fields ...Field)
复制代码
其中 fields 是 zapcore.Field 类型，用来存储 key-value，并记录 value 类型，不管是 zap.String 还是 zap.Int 底层都是 zapcore.Field 类型来记录的。zap 为每一种 Go 的内置类型都定义了对应的 zap.Xxx 方法，甚至还实现 zap.Any() 来支持 interface{}。
执行以上代码，控制台得到如下输出：
{"level":"info","ts":1679212318.10218,"caller":"zap/main.go:16","msg":"production failed to fetch URL","url":"https://jianghushinian.cn/","attempt":3,"backoff":1}2023-03-19T15:51:58.102+0800 DEBUG zap/main.go:29 development failed to fetch URL {"url": "https://jianghushinian.cn/", "attempt": 3, "backoff": "1s"}
复制代码
可以发现，通过 zap.NewProduction() 创建的日志对象输出格式为 JSON，而通过 zap.NewDevelopment() 创建的日志对象输出格式为 Text，日志后面追加的 key-value 会被转换成 JSON。并且，两者输出的字段内容也略有差异，如生产环境日志输出的时间格式为 Unix epoch 利于程序解析，而开发环境日志输出的时间格式为 ISO8601 更利于人类阅读。
导致以上这些差异的原因是配置不同，我们来看下 zap.NewProduction 和 zap.NewDevelopment 的代码实现：
func NewProduction(options ...Option) (*Logger, error) { return NewProductionConfig().Build(options...)}
func NewProductionConfig() Config { return Config{ Level: NewAtomicLevelAt(InfoLevel), Development: false, Sampling: &SamplingConfig{ Initial: 100, Thereafter: 100, }, Encoding: "json", EncoderConfig: NewProductionEncoderConfig(), OutputPaths: []string{"stderr"}, ErrorOutputPaths: []string{"stderr"}, }}
func NewDevelopment(options ...Option) (*Logger, error) { return NewDevelopmentConfig().Build(options...)}
func NewDevelopmentConfig() Config { return Config{ Level: NewAtomicLevelAt(DebugLevel), Development: true, Encoding: "console", EncoderConfig: NewDevelopmentEncoderConfig(), OutputPaths: []string{"stderr"}, ErrorOutputPaths: []string{"stderr"}, }}
复制代码
可以看到，两者在实现思路上是一样的，都是先创建一个配置对象 zap.Config，然后再调用配置对象的 Build 方法来构建 Logger。
zap.Config 定义如下：
type Config struct { Level AtomicLevel `json:"level" yaml:"level"` Development bool `json:"development" yaml:"development"` DisableCaller bool `json:"disableCaller" yaml:"disableCaller"` DisableStacktrace bool `json:"disableStacktrace" yaml:"disableStacktrace"` Sampling *SamplingConfig `json:"sampling" yaml:"sampling"` Encoding string `json:"encoding" yaml:"encoding"` EncoderConfig zapcore.EncoderConfig `json:"encoderConfig" yaml:"encoderConfig"` OutputPaths []string `json:"outputPaths" yaml:"outputPaths"` ErrorOutputPaths []string `json:"errorOutputPaths" yaml:"errorOutputPaths"` InitialFields map[string]interface{} `json:"initialFields" yaml:"initialFields"`}
复制代码
每个配置项说明如下：
Level: 日志级别。
Development: 是否为开发模式。
DisableCaller: 禁用调用信息，值为 true 时，日志中将不再显示记录日志时所在的函数调用文件名和行号。
DisableStacktrace: 禁用堆栈跟踪捕获。
Sampling: 采样策略配置，单位为每秒，作用是限制日志在每秒内的输出数量，以此来防止全局的 CPU 和 I/O 负载过高。
Encoding: 指定日志编码器，目前支持 json 和 console。
EncoderConfig: 编码配置，决定了日志字段格式。
OutputPaths: 配置日志输出位置，URLs 或文件路径，可配置多个。
ErrorOutputPaths: zap 包内部出现错误的日志输出位置，URLs 或文件路径，可配置多个，默认 os.Stderr。
InitialFields: 初始化字段配置，该配置的字段会以结构化的形式打印在每条日志输出中。
我们再来对比下 NewProductionEncoderConfig() 和 NewDevelopmentEncoderConfig() 这两个配置的不同：
func NewProductionEncoderConfig() zapcore.EncoderConfig { return zapcore.EncoderConfig{ TimeKey: "ts", LevelKey: "level", NameKey: "logger", CallerKey: "caller", FunctionKey: zapcore.OmitKey, MessageKey: "msg", StacktraceKey: "stacktrace", LineEnding: zapcore.DefaultLineEnding, EncodeLevel: zapcore.LowercaseLevelEncoder, EncodeTime: zapcore.EpochTimeEncoder, EncodeDuration: zapcore.SecondsDurationEncoder, EncodeCaller: zapcore.ShortCallerEncoder, }}
func NewDevelopmentEncoderConfig() zapcore.EncoderConfig { return zapcore.EncoderConfig{ // Keys can be anything except the empty string. TimeKey: "T", LevelKey: "L", NameKey: "N", CallerKey: "C", FunctionKey: zapcore.OmitKey, MessageKey: "M", StacktraceKey: "S", LineEnding: zapcore.DefaultLineEnding, EncodeLevel: zapcore.CapitalLevelEncoder, EncodeTime: zapcore.ISO8601TimeEncoder, EncodeDuration: zapcore.StringDurationEncoder, EncodeCaller: zapcore.ShortCallerEncoder, }}
复制代码
对比来看，两者有很多不同的配置，比如生产环境下 EncodeTime 值为 zapcore.EpochTimeEncoder，开发环境下 EncodeTime 值为 zapcore.ISO8601TimeEncoder。这就是生产环境日志输出的时间格式为 Unix epoch 而开发环境日志输出的时间格式为 ISO8601 的原因。
zapcore.EncoderConfig 其他几个常用的配置项说明如下：
MessageKey: 日志信息的键名，默认 msg。
LevelKey: 日志级别的键名，默认 level。
TimeKey: 日志时间的键名。
EncodeLevel: 日志级别的格式，默认为小写，如 info。
除了提供 zap.NewProduction() 和 zap.NewDevelopment() 两个构造函数外，zap 还提供了 zap.NewExample() 来创建一个 Logger 对象，这个方法主要用于测试，这里就不多介绍了。
给语法加点糖
zap 虽然速度足够快，但是多数情况下，我们并不需要极致的性能，而是想让代码写起来更爽一些。zap 为我们提供了解决方案 —— SugaredLogger。
package main
import ( "time"
"go.uber.org/zap")
func main() { logger, _ := zap.NewProduction() defer logger.Sync()
url := "https://jianghushinian.cn/" sugar := logger.Sugar() sugar.Infow("production failed to fetch URL", "url", url, "attempt", 3, "backoff", time.Second, ) sugar.Info("Info") sugar.Infof("Infof: %s", url) sugar.Infoln("Infoln")}
复制代码
通过 logger.Sugar() 方法可以将一个 Logger 对象转换成一个 SugaredLogger 对象。
SugaredLogger 提供了更人性化的接口，日志中追加 key-value 时不在需要 zap.String("url", url) 这种显式指明类型的写法，只需要保证 key 为 string 类型，value 则可以为任意类型，能够减少我们编写的代码量。
此外，为了满足不同需求，SugaredLogger 提供了四种方式输出日志：sugar.Xxx、sugar.Xxxw、sugar.Xxxf、sugar.Xxxln。
执行以上代码，控制台得到如下输出：
{"level":"info","ts":1679217743.5967638,"caller":"zap/sugar.go:15","msg":"production failed to fetch URL","url":"https://jianghushinian.cn/","attempt":3,"backoff":1}{"level":"info","ts":1679217743.5969589,"caller":"zap/sugar.go:20","msg":"Info"}{"level":"info","ts":1679217743.5969741,"caller":"zap/sugar.go:21","msg":"Infof: https://jianghushinian.cn/"}{"level":"info","ts":1679217743.5969841,"caller":"zap/sugar.go:22","msg":"Infoln"}
复制代码
我们知道，这种方便的写法是有一定代价的，所以开发中是否需要使用 SugaredLogger 来记录日志，需要根据程序的特点来决定。SugaredLogger 与 Logger 的性能对比同样可以在官方 GitHub 仓库中看到。
定制 Logger
通过查看 zap.NewProduction() 和 zap.NewDevelopment() 两个构造函数源码，我们知道可以使用 zap.Config 对象的 Build 方法创建 Logger 对象。那么我们很容易能够想到，如果要定制 Logger，只需要创建一个定制的 zap.Config 即可。
package main
import ( "go.uber.org/zap" "go.uber.org/zap/zapcore")
func newCustomLogger() (*zap.Logger, error) { cfg := zap.Config{ Level: zap.NewAtomicLevelAt(zap.DebugLevel), Development: false, Encoding: "json", EncoderConfig: zapcore.EncoderConfig{ TimeKey: "time", LevelKey: "level", NameKey: "logger", CallerKey: "", // 不记录日志调用位置 FunctionKey: zapcore.OmitKey, MessageKey: "message", LineEnding: zapcore.DefaultLineEnding, EncodeLevel: zapcore.LowercaseLevelEncoder, EncodeTime: zapcore.RFC3339TimeEncoder, EncodeDuration: zapcore.SecondsDurationEncoder, EncodeCaller: zapcore.ShortCallerEncoder, }, OutputPaths: []string{"stdout", "test.log"}, ErrorOutputPaths: []string{"error.log"}, } return cfg.Build()}
func main() { logger, _ := newCustomLogger() defer logger.Sync()
// 增加一个 skip 选项，触发 zap 内部 error，将错误输出到 error.log logger = logger.WithOptions(zap.AddCallerSkip(100))
logger.Info("Info msg") logger.Error("Error msg")}
复制代码
以上代码通过 newCustomLogger 函数创建了一个自定义的 Logger，同样通过先定义一个 zap.Config 然后再调用其 Build 方法来实现。
配置日志分别输出到标准输出和 test.log 文件，执行以上代码，控制台和 test.log 都会得到如下输出：
{"level":"info","time":"2023-03-19T19:19:18+08:00","message":"Info msg"}{"level":"error","time":"2023-03-19T19:19:18+08:00","message":"Error msg"}
复制代码
另外，我们还通过 logger.WithOptions() 为 Logger 对象增加了一个选项 zap.AddCallerSkip(100)，这个选项的作用是指定在通过调用栈获得行号时跳过的调用深度，因为我们的函数调用栈并不是 100 层，所以会触发 zap 内部错误，zap 会将错误日志输出到 ErrorOutputPaths 配置指定的位置中，即 error.log。
error.log 得到的错误日志如下：
2023-03-19 11:19:18.438824 +0000 UTC Logger.check error: failed to get caller2023-03-19 11:19:18.44921 +0000 UTC Logger.check error: failed to get caller
复制代码
logger.WithOptions() 支持的选项如下：
WrapCore(f func(zapcore.Core) zapcore.Core): 使用一个新的 zapcore.Core 替换掉 Logger 内部原有的的 zapcore.Core 属性。
Hooks(hooks ...func(zapcore.Entry) error): 注册钩子函数，用来在日志打印时同时调用注册的钩子函数。
Fields(fs ...Field): 添加公共字段。
ErrorOutput(w zapcore.WriteSyncer): 指定日志组件内部出现异常时的输出位置。
Development(): 将日志记录器设为开发模式，这将使 DPanic 级别日志记录错误后执行 panic()。
AddCaller(): 与 WithCaller(true) 等价。
WithCaller(enabled bool): 指定是否在日志输出内容中增加调用信息，即文件名和行号。
AddCallerSkip(skip int): 指定在通过调用栈获取文件名和行号时跳过的调用深度。
AddStacktrace(lvl zapcore.LevelEnabler): 用来指定某个日志级别及以上级别输出调用堆栈。
IncreaseLevel(lvl zapcore.LevelEnabler): 提高日志级别，如果传入的 lvl 比现有级别低，则不会改变日志级别。
WithFatalHook(hook zapcore.CheckWriteHook): 当出现 Fatal 级别日志时调用的钩子函数。
WithClock(clock zapcore.Clock): 指定日志记录器用来确定当前时间的 zapcore.Clock 对象，默认为 time.Now 的系统时钟。
创建自定义的配置对象，除了在代码中指定配置参数，也可以将这些配置项写入到 JSON 文件中，然后通过 json.Unmarshal 的方式将配置绑定到 zap.Config，可以参考官方示例。
二次开发
封装自己的 zap 包
通过前文对 zap 的介绍，相信你对 zap 的特点和用法都已了然于心。如果你用惯了 Go log 标准库，或者是 Logrus 第三方库，那么对于 zap 所提供的 API 一定不会感到满意。因此，我基于 zap 包定制开发了自己的日志包，项目地址在这里，你可以点进去查看源码。
基于 zap 定制的日志包并没有太多的逻辑，只在 zap/zapcore （zapcore 故名思义，是 zap 的核心，zap 是对 zapcore 的封装）基础上进行了很薄的一层封装，所以性能上无需担心。
提示：关于定制开发的日志包设计思路这里就不讲解了，之后我会单独写一篇文章来进行解读，敬请期待（先挖个坑）。
日志包对外提供了类似 Go log 标准库风格的 API，几种常见使用方式如下：
像 Go log 标准库一样开箱即用
package main
import ( "os" "time"
log "github.com/jianghushinian/gokit/log/zap")
func main() { defer log.Sync() log.Info("failed to fetch URL", log.String("url", "https://jianghushinian.cn/")) log.Warn("Warn msg", log.Int("attempt", 3)) log.Error("Error msg", log.Duration("backoff", time.Second))
log.SetLevel(log.ErrorLevel) log.Info("Info msg") log.Warn("Warn msg") log.Error("Error msg")
// 替换默认 Logger file, _ := os.OpenFile("custom.log", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644) logger := log.New(file, log.InfoLevel) log.ReplaceDefault(logger) log.Info("Info msg in replace default logger after")}
复制代码
自定义日志包提供了默认的 std Logger 对象和 Info、Warn 等包级别的开放函数，以此实现开箱即用的效果。日志包还提供了 SetLevel 函数来支持运行时修改日志级别。
另外，如果你对默认的 Logger 不满意，可以使用 log.New 来创建新的 Logger，接下来只需要通过 log.ReplaceDefault(logger) 一行代码，就可以将默认的 Logger 替换成新创建的 Logger 对象。之后通过 log.Info 来输出日志底层使用的已经是替换后的 Logger 对象了。
执行以上代码，控制台输出:
{"level":"info","ts":"2023-03-19T21:57:59+08:00","msg":"failed to fetch URL","url":"https://jianghushinian.cn/"}{"level":"warn","ts":"2023-03-19T21:57:59+08:00","msg":"Warn msg","attempt":3}{"level":"error","ts":"2023-03-19T21:57:59+08:00","msg":"Error msg","backoff":1}{"level":"error","ts":"2023-03-19T21:57:59+08:00","msg":"Error msg"}
复制代码
custom.log 输出:
{"level":"info","ts":"2023-03-19T21:57:59+08:00","msg":"Info msg in replace default logger after"}
复制代码
将日志输出到多个位置
package main
import ( "os"
log "github.com/jianghushinian/gokit/log/zap")
func main() { file, _ := os.OpenFile("test-warn.log", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644) tees := []log.TeeOption{ { Out: os.Stdout, LevelEnablerFunc: func(level log.Level) bool { return level == log.InfoLevel }, }, { Out: file, LevelEnablerFunc: func(level log.Level) bool { return level == log.WarnLevel }, }, } logger := log.NewTee(tees) defer logger.Sync()
logger.Info("Info tee msg") logger.Warn("Warn tee msg") logger.Error("Error tee msg") // 不会输出}
复制代码
自定义日志包通过 log.NewTee 构造函数提供了将日志输出到多个位置的能力，log.NewTee 接收一个 log.TeeOption 列表，用来定义不同级别的日志输出方式，其本质上是定义了多个 zap.Core 对象。
其中 Out 字段为日志输出目标地址，LevelEnablerFunc 用来指定日志级别。这有别于使用 log.InfoLevel 这种常量日志级别的设定，使用 LevelEnablerFunc 只需要定义一个接收 log.Level 作为参数并返回 bool 类型值的函数即可。
这样如果函数内部写为 return level == log.InfoLevel 表示 Info 级别使用此配置日志对象输出，日过函数内部实现为 return level >= log.WarnLevel 则表示 Warn 及以上级别即 Warn、Error、DPanic、Panic、Fatal 级别都使用此配置对应的日志对象作为输出，更为灵活。
执行以上代码，控制台输出:
{"level":"info","ts":"2023-03-19T22:06:25+08:00","msg":"Info tee msg"}
复制代码
test-warn.log 输出:
{"level":"warn","ts":"2023-03-19T22:06:25+08:00","msg":"Warn tee msg"}
复制代码
选项模式、Hooks、日志轮转等更多使用场景可以参考项目的使用示例。在 Gin 框架中的使用示例，可以参考这里。
总结
本文讲解了 Go 第三方日志库 zap 的特点及使用。
zap 作为以快著称的日志库，在使用上不如 Logrus 来的方便，于是我基于 zap 定制开发了自己的日志包，并简单介绍了如何使用。
关于 zap 的更多使用方式可以参考官方文档，如果你对我封装日志包感兴趣，可以查看源码。
参考
zap 源码: https://github.com/uber-go/zap
zap 文档: https://pkg.go.dev/go.uber.org/zap
基于 zap 开发的日志包: https://github.com/jianghushinian/gokit/tree/main/log
评论