Go 语言日志框架 zap
本文详细解析了 Go 高性能日志框架 zap 的安装、基础配置与常用用法,介绍了 Logger 和 SugaredLogger 的区别及适用场景,讲解了如何通过 zapcore 手动
一、简介
zap 是 uber 开源的 Go 高性能日志框架,这是它的官方地址:https://github.com/uber-go/zap,它支持不同的日志级别,能够打印基本信息等,但不支持日志的分割,这里我们可以使用 lumberjack 也是 zap 官方推荐用于日志分割,结合这两个库我们就可以实现以下功能的日志机制:
- 能够将事件记录到文件中,而不是应用程序控制台;
- 日志切割能够根据文件大小、时间或间隔等来切割日志文件;
- 支持不同的日志级别,例如
DEBUG,INFO,WARN,ERROR等; - 能够打印基本信息,如调用文件、函数名和行号,日志时间等;
二、安装
使用以下命令进行安装
sh
go get -u go.uber.org/zap

三、配置
zap 提供了两种类型的日志记录器—和 Logger 和 Sugared Logger 。两者之间的区别是:
- 在每一微秒和每一次内存分配都很重要的上下文中,使用
Logger。它甚至比SugaredLogger更快,内存分配次数也更少,但它只支持强类型的结构化日志记录。 - 在性能很好但不是很关键的上下文中,使用
SugaredLogger。它比其他结构化日志记录包快 4-10 倍,并且支持结构化和printf风格的日志记录。
所以一般场景下我们使用 Sugared Logger 就足够了。
1、Logger
创建 Logger 的方式:
zap.NewExample()zap.NewDevelopment()zap.NewProduction()
特点:
- 每一个函数都将创建一个
logger。唯一的区别在于它将记录的信息不同。例如production logger默认记录调用函数信息、日期和时间等。 - 通过
Logger调用INFO、ERROR等。 - 默认情况下日志都会打印到应用程序的
console界面。
1.1、NewExample
示例代码
go
package main
import "go.uber.org/zap"
func main() {
log := zap.NewExample()
log.Debug("this is debug message")
log.Info("this is info message")
log.Info("this is info message with fields", zap.Int("age", 24), zap.String("name", "Salmon"))
log.Warn("this is warn message")
log.Error("this is error message")
log.Panic("this is panic message")
}
结果

1.2、NewDevelopment
示例代码
go
package main
import "go.uber.org/zap"
func main() {
log, _ := zap.NewDevelopment()
log.Debug("this is debug message")
log.Info("this is info message")
log.Info("this is info message with fields", zap.Int("age", 24), zap.String("name", "Salmon"))
log.Warn("this is warn message")
log.Error("this is error message")
// log.DPanic("This is a DPanic message")
// log.Panic("this is panic message")
// log.Fatal("This is a FATAL message")
}
结果

1.3、NewProduction
示例代码
go
package main
import "go.uber.org/zap"
func main() {
log, _ := zap.NewProduction()
log.Debug("this is debug message")
log.Info("this is info message")
log.Info("this is info message with fields", zap.Int("age", 24), zap.String("name", "Salmon"))
log.Warn("this is warn message")
log.Error("this is error message")
// log.DPanic("This is a DPanic message")
// log.Panic("this is panic message")
// log.Fatal("This is a FATAL message")
}
结果

1.4、小结
Example和Production使用的是json格式输出,Development使用行的形式输出Development- 从警告级别向上打印到堆栈中来跟踪
- 始终打印包/文件/行(方法)
- 在行尾添加任何额外字段作为
json字符串 - 以大写形式打印级别名称
- 以毫秒为单位打印 ISO8601 格式的时间戳
Production- 调试级别消息(Debug)不记录
Error,Dpanic级别的记录,会在堆栈中跟踪文件,Warn不会- 始终将调用者添加到文件中
- 以时间戳格式打印日期
- 以小写形式打印级别名称
2、Sugared Logger
默认的 zap 记录器需要结构化标签,即对每个标签,需要使用特定值类型的函数。
go
log.Info("this is info message with fields", zap.Int("age", 24), zap.String("name", "Salmon"))
虽然会显的很长,但是对性能要求较高的话,这是最快的选择。我们也可以使用suger logger, 它基于 printf 分割的反射类型检测,提供更简单的语法来添加混合类型的标签。
我们使用 Sugared Logger 来实现相同的功能。
- 大部分的实现基本都相同;
- 惟一的区别是,我们通过调用主
logger的.Sugar()方法来获取一个SugaredLogger; - 然后使用
SugaredLogger以printf格式记录语句;
go
package main
import "go.uber.org/zap"
func main() {
logger, _ := zap.NewDevelopment()
sLogger := logger.Sugar()
sLogger.Debugf("debug message age is %d, sex is %s", 24, "boy")
sLogger.Info("Info() uses sprint")
sLogger.Infof("Infof() uses %s", "sprintf")
sLogger.Infow("Infow() allows tags", "name", "Salmon", "type", 1)
}
结果

如果需要切换到标准记录器,可以使用记录器上的 .Desugar() 方法从 sugar logger 切换到标准记录器。
go
log := sLogger.Desugar()
log.Info("this is info message")
四、写入日志
我们使用 zap.New(…) 方法来手动传递所有配置,而不是使用像 zap.NewProduction() 这样的预置方法来创建 logger 。
go
func New(core zapcore.Core, options ...Option) *Logger
zapcore.Core需要三个配置——Encoder,WriteSyncer,LogLevel。
Encoder:编码器(如何写入日志)。我们将使用开箱即用的NewConsoleEncoder(),并使用预先设置的ProductionEncoderConfig()。gozapcore.NewConsoleEncoder(zap.NewProductionEncoderConfig())WriterSyncer:指定日志将写到哪里去。我们使用zapcore.AddSync()函数并且将打开的文件句柄传进去。gofile, _ := os.Create("./test.log") writeSyncer := zapcore.AddSync(file)Log Level:哪种级别的日志将被写入。
示例
go
package main
import (
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
"os"
)
var sugarLogger *zap.SugaredLogger
// InitLogger 初始化logger
func InitLogger(name string) {
encoder := getEncoder()
writeSyncer := getLogWriter(name)
core := zapcore.NewCore(encoder, writeSyncer, zapcore.DebugLevel)
// zap.AddCaller() 添加将调用函数信息记录到日志中的功能。
logger := zap.New(core, zap.AddCaller())
sugarLogger = logger.Sugar()
}
// getEncoder 获取编码器
func getEncoder() zapcore.Encoder {
// 生成编码配置
encoderConfig := zap.NewProductionEncoderConfig()
// 修改时间编码器
encoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
// 在日志文件中使用大写字母记录日志级别
encoderConfig.EncodeLevel = zapcore.CapitalLevelEncoder
// NewConsoleEncoder 打印更符合人们观察的方式
return zapcore.NewConsoleEncoder(encoderConfig)
}
// getLogWriter 日志写入
func getLogWriter(name string) zapcore.WriteSyncer {
file, _ := os.Create(name)
return zapcore.AddSync(file)
}
func main() {
InitLogger("./test.log")
sugarLogger.Info("this is info message")
sugarLogger.Infof("this is %s, %d", "salmon'grade", 100)
sugarLogger.Error("this is error message")
sugarLogger.Info("this is info message")
}
结果

五、lumberjack
因为 zap 本身不支持切割归档日志文件,为了添加日志切割归档功能,我们将使用第三方库 lumberjack 来实现。
1、安装 lumberjack
执行以下命令进行安装
sh
go get -u github.com/natefinch/lumberjack
2、加入 lumberjack
要在 zap 中加入 lumberjack 支持,我们需要修改 WriteSyncer 代码。我们将按照下面的代码修改 getLogWriter() 函数:
go
// getLogWriter 日志写入
func getLogWriter(name string) zapcore.WriteSyncer {
lumberJackLogger := &lumberjack.Logger{
Filename: name,
MaxSize: 10,
MaxBackups: 5,
MaxAge: 30,
Compress: false,
}
return zapcore.AddSync(lumberJackLogger)
}
Lumberjack Logger 采用以下属性作为输入:
Filename: 日志文件的位置;MaxSize:在进行切割之前,日志文件的最大大小(以MB为单位);MaxBackups:保留旧文件的最大个数;MaxAges:保留旧文件的最大天数;Compress:是否压缩/归档旧文件;
完整示例代码
go
package main
import (
"github.com/natefinch/lumberjack"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
)
var sugarLogger *zap.SugaredLogger
// InitLogger 初始化logger
func InitLogger(name string) {
encoder := getEncoder()
writeSyncer := getLogWriter(name)
core := zapcore.NewCore(encoder, writeSyncer, zapcore.DebugLevel)
// zap.AddCaller() 添加将调用函数信息记录到日志中的功能。
logger := zap.New(core, zap.AddCaller())
sugarLogger = logger.Sugar()
}
// getEncoder 获取编码器
func getEncoder() zapcore.Encoder {
// 生成编码配置
encoderConfig := zap.NewProductionEncoderConfig()
// 修改时间编码器
encoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
// 在日志文件中使用大写字母记录日志级别
encoderConfig.EncodeLevel = zapcore.CapitalLevelEncoder
// NewConsoleEncoder 打印更符合人们观察的方式
return zapcore.NewConsoleEncoder(encoderConfig)
}
// getLogWriter 日志写入
func getLogWriter(name string) zapcore.WriteSyncer {
lumberJackLogger := &lumberjack.Logger{
Filename: name,
MaxSize: 10,
MaxBackups: 5,
MaxAge: 30,
Compress: false,
}
return zapcore.AddSync(lumberJackLogger)
}
func main() {
InitLogger("./test.log")
sugarLogger.Info("this is info message")
sugarLogger.Infof("this is %s, %d", "salmon'grade", 100)
sugarLogger.Error("this is error message")
sugarLogger.Info("this is info message")
}
结果

六、整体使用
go
package main
import (
"github.com/natefinch/lumberjack"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
"time"
)
var logger *zap.Logger
// InitLogger 初始化 logger
// logPath 日志文件路径 loglevel 日志级别
func InitLogger(logPath string, logLevel string) {
// 日志分割
hook := lumberjack.Logger{
Filename: logPath, // 日志文件路径,默认 os.TempDir()
MaxSize: 10, // 每个日志文件保存10M,默认 100M
MaxBackups: 30, // 保留30个备份,默认不限
MaxAge: 7, // 保留7天,默认不限
Compress: true, // 是否压缩,默认不压缩
}
write := zapcore.AddSync(&hook)
// 设置日志级别
// debug 可以打印出 info debug warn
// info 级别可以打印 warn info
// warn 只能打印 warn
// debug->info->warn->error
var level zapcore.Level
switch logLevel {
case "debug":
level = zap.DebugLevel
case "info":
level = zap.InfoLevel
case "error":
level = zap.ErrorLevel
default:
level = zap.InfoLevel
}
encoderConfig := zapcore.EncoderConfig{
TimeKey: "time",
LevelKey: "level",
NameKey: "logger",
CallerKey: "linenum",
MessageKey: "msg",
StacktraceKey: "stacktrace",
LineEnding: zapcore.DefaultLineEnding,
EncodeLevel: zapcore.LowercaseLevelEncoder, // 小写编码器
EncodeTime: zapcore.ISO8601TimeEncoder, // ISO8601 UTC 时间格式
EncodeDuration: zapcore.SecondsDurationEncoder, //
EncodeCaller: zapcore.FullCallerEncoder, // 全路径编码器
EncodeName: zapcore.FullNameEncoder,
}
// 设置日志级别
atomicLevel := zap.NewAtomicLevel()
atomicLevel.SetLevel(level)
core := zapcore.NewCore(
//zapcore.NewConsoleEncoder(encoderConfig),
zapcore.NewJSONEncoder(encoderConfig),
//zapcore.NewMultiWriteSyncer(zapcore.AddSync(os.Stdout), zapcore.AddSync(write)), // 打印到控制台和文件
write,
level,
)
// 开启开发模式,堆栈跟踪
caller := zap.AddCaller()
// 开启文件及行号
development := zap.Development()
// 设置初始化字段,如:添加一个服务器名称
filed := zap.Fields(zap.String("serviceName", "serviceName"))
// 构造日志
logger = zap.New(core, caller, development, filed)
logger.Info("DefaultLogger init success")
}
func main() {
// 历史记录日志名字为:all.log,服务重新启动,日志会追加,不会删除
InitLogger("./all.log", "debug")
// 强结构形式
logger.Info("test",
zap.String("string", "salmon"),
zap.Int("int", 3),
zap.Duration("time", time.Second),
)
// 必须 key-value 结构形式 性能下降一点
logger.Sugar().Infow("test1",
"string", "salmon",
"int", 1,
"time", time.Second,
)
}
zapcore.NewConsoleEncoder(encoderConfig)配置

zapcore.NewJSONEncoder(encoderConfig)配置

zapcore.NewMultiWriteSyncer(zapcore.AddSync(os.Stdout), zapcore.AddSync(write))配置gocore := zapcore.NewCore( //zapcore.NewConsoleEncoder(encoderConfig), zapcore.NewJSONEncoder(encoderConfig), // 打印到控制台和文件 zapcore.NewMultiWriteSyncer(zapcore.AddSync(os.Stdout), zapcore.AddSync(write)), //write, level, )

七、何处打印日志
我们一般分以下几种情况:
- 在分支语句处打印日志。在分支语句处打印日志,可以判断出代码走了哪个分支,有助于判断请求的下一跳,继而继续排查问题。
- 写操作必须打印日志。写操作最可能会引起比较严重的业务故障,写操作打印日志,可以在出问题时找到关键信息。
- 在循环中打印日志要慎重。如果循环次数过多,会导致打印大量的日志,严重拖累代码的性能,建议的办法是在循环中记录要点,在循环外面总结打印出来。
- 在错误产生的最原始位置打印日志。对于嵌套的 Error,可在 Error 产生的最初位置打印 Error 日志,上层如果不需要添加必要的信息,可以直接返回下层的 Error。
八、zap封装
这里代码来自 gitee 上开源项目:https://gitee.com/Madou-Shinni/go-logger/tree/master
go
package utils
import (
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
"gopkg.in/natefinch/lumberjack.v2"
"io"
"os"
"path/filepath"
"time"
)
const (
// DefaultLevel the default log level
DefaultLevel = zapcore.InfoLevel
// DefaultTimeLayout the default time layout;
DefaultTimeLayout = time.RFC3339
)
var logger *zap.Logger
// Option custom setup config
type Option func(*option)
type option struct {
level zapcore.Level
fields map[string]string
file io.Writer
timeLayout string
disableConsole bool
}
// WithDebugLevel only greater than 'level' will output
func WithDebugLevel() Option {
return func(opt *option) {
opt.level = zapcore.DebugLevel
}
}
// WithInfoLevel only greater than 'level' will output
func WithInfoLevel() Option {
return func(opt *option) {
opt.level = zapcore.InfoLevel
}
}
// WithWarnLevel only greater than 'level' will output
func WithWarnLevel() Option {
return func(opt *option) {
opt.level = zapcore.WarnLevel
}
}
// WithErrorLevel only greater than 'level' will output
func WithErrorLevel() Option {
return func(opt *option) {
opt.level = zapcore.ErrorLevel
}
}
// WithField add some field(s) to log
func WithField(key, value string) Option {
return func(opt *option) {
opt.fields[key] = value
}
}
// WithFileP write log to some file
func WithFileP(file string) Option {
dir := filepath.Dir(file)
if err := os.MkdirAll(dir, 0766); err != nil {
panic(err)
}
f, err := os.OpenFile(file, os.O_CREATE|os.O_APPEND|os.O_RDWR, 0766)
if err != nil {
panic(err)
}
return func(opt *option) {
opt.file = zapcore.Lock(f)
}
}
// WithFileRotationP write log to some file with rotation
func WithFileRotationP(file string) Option {
dir := filepath.Dir(file)
if err := os.MkdirAll(dir, 0766); err != nil {
panic(err)
}
return func(opt *option) {
opt.file = &lumberjack.Logger{ // concurrent-safed
Filename: file, // 文件路径
MaxSize: 128, // 单个文件最大尺寸,默认单位 M
MaxBackups: 300, // 最多保留 300 个备份
MaxAge: 30, // 最大时间,默认单位 day
LocalTime: true, // 使用本地时间
Compress: true, // 是否压缩 disabled by default
}
}
}
// WithTimeLayout custom time format
func WithTimeLayout(timeLayout string) Option {
return func(opt *option) {
opt.timeLayout = timeLayout
}
}
// WithDisableConsole WithEnableConsole write log to os.Stdout or os.Stderr
func WithDisableConsole() Option {
return func(opt *option) {
opt.disableConsole = true
}
}
// NewJSONLogger return a json-encoder zap logger,
func NewJSONLogger(opts ...Option) (*zap.Logger, error) {
opt := &option{level: DefaultLevel, fields: make(map[string]string)}
for _, f := range opts {
f(opt)
}
timeLayout := DefaultTimeLayout
if opt.timeLayout != "" {
timeLayout = opt.timeLayout
}
// similar to zap.NewProductionEncoderConfig()
encoderConfig := zapcore.EncoderConfig{
TimeKey: "time",
LevelKey: "level",
NameKey: "logger", // used by logger.Named(key); optional; useless
CallerKey: "caller",
MessageKey: "msg",
StacktraceKey: "stacktrace", // use by zap.AddStacktrace; optional; useless
LineEnding: zapcore.DefaultLineEnding,
EncodeLevel: zapcore.LowercaseLevelEncoder, // 小写编码器
EncodeTime: func(t time.Time, enc zapcore.PrimitiveArrayEncoder) {
enc.AppendString(t.Format(timeLayout))
},
EncodeDuration: zapcore.MillisDurationEncoder,
EncodeCaller: zapcore.ShortCallerEncoder, // 全路径编码器
}
jsonEncoder := zapcore.NewJSONEncoder(encoderConfig)
// lowPriority usd by info\debug\warn
lowPriority := zap.LevelEnablerFunc(func(lvl zapcore.Level) bool {
return lvl >= opt.level && lvl < zapcore.ErrorLevel
})
// highPriority usd by error\panic\fatal
highPriority := zap.LevelEnablerFunc(func(lvl zapcore.Level) bool {
return lvl >= opt.level && lvl >= zapcore.ErrorLevel
})
stdout := zapcore.Lock(os.Stdout) // lock for concurrent safe
stderr := zapcore.Lock(os.Stderr) // lock for concurrent safe
core := zapcore.NewTee()
if !opt.disableConsole {
core = zapcore.NewTee(
zapcore.NewCore(jsonEncoder,
zapcore.NewMultiWriteSyncer(stdout),
lowPriority,
),
zapcore.NewCore(jsonEncoder,
zapcore.NewMultiWriteSyncer(stderr),
highPriority,
),
)
}
if opt.file != nil {
core = zapcore.NewTee(core,
zapcore.NewCore(jsonEncoder,
zapcore.AddSync(opt.file),
zap.LevelEnablerFunc(func(lvl zapcore.Level) bool {
return lvl >= opt.level
}),
),
)
}
log := zap.New(core,
zap.AddCaller(),
zap.ErrorOutput(stderr),
)
for key, value := range opt.fields {
log = log.WithOptions(zap.Fields(zapcore.Field{Key: key, Type: zapcore.StringType, String: value}))
}
// 给全局logger对象
logger = log
return log, nil
}
var _ Meta = (*meta)(nil)
// Meta key-value
type Meta interface {
Key() string
Value() interface{}
meta()
}
type meta struct {
key string
value interface{}
}
func (m *meta) Key() string {
return m.key
}
func (m *meta) Value() interface{} {
return m.value
}
func (m *meta) meta() {}
// NewMeta create meat
func NewMeta(key string, value interface{}) Meta {
return &meta{key: key, value: value}
}
// WrapMeta wrap meta to zap fields
func WrapMeta(err error, metas ...Meta) (fields []zap.Field) {
capacity := len(metas) + 1 // namespace meta
if err != nil {
capacity++
}
fields = make([]zap.Field, 0, capacity)
if err != nil {
fields = append(fields, zap.Error(err))
}
fields = append(fields, zap.Namespace("meta"))
for _, meta := range metas {
fields = append(fields, zap.Any(meta.Key(), meta.Value()))
}
return
}
func setLogger() {
if logger == nil {
logger, _ = NewJSONLogger()
}
}
func Info(msg string, fields ...zap.Field) {
setLogger()
logger.Info(msg, fields...)
}
func Debug(msg string, fields ...zap.Field) {
setLogger()
logger.Debug(msg, fields...)
}
func Warn(msg string, fields ...zap.Field) {
setLogger()
logger.Warn(msg, fields...)
}
func Error(msg string, fields ...zap.Field) {
setLogger()
logger.Error(msg, fields...)
}
// Sync calls the underlying Core's Sync method, flushing any buffered log
// entries. Applications should take care to call Sync before exiting.
func Sync() {
if logger != nil {
logger.Sync()
}
}