Go 语言日志框架 zap

2023-12-08后端10 分钟164 次阅读
AI 摘要salmon-ai

本文详细解析了 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
image.png

三、配置

zap 提供了两种类型的日志记录器—和 Logger 和 Sugared Logger 。两者之间的区别是:

  • 在每一微秒和每一次内存分配都很重要的上下文中,使用 Logger 。它甚至比 SugaredLogger 更快,内存分配次数也更少,但它只支持强类型的结构化日志记录。
  • 在性能很好但不是很关键的上下文中,使用 SugaredLogger 。它比其他结构化日志记录包快 4-10 倍,并且支持结构化和 printf 风格的日志记录。

所以一般场景下我们使用 Sugared Logger 就足够了。

1、Logger

创建 Logger 的方式:

  1. zap.NewExample()
  2. zap.NewDevelopment()
  3. 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")
}

结果
image.png

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")
}

结果
image.png

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")
}

结果
image.png

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)
}

结果
image.png
如果需要切换到标准记录器,可以使用记录器上的 .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()。
    go 复制代码
    zapcore.NewConsoleEncoder(zap.NewProductionEncoderConfig())
  • WriterSyncer:指定日志将写到哪里去。我们使用 zapcore.AddSync() 函数并且将打开的文件句柄传进去。
    go 复制代码
    file, _ := 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")
}

结果
image.png

五、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")
}

结果
image.png

六、整体使用

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) 配置
    image.png
  • zapcore.NewJSONEncoder(encoderConfig) 配置
    image.png
  • zapcore.NewMultiWriteSyncer(zapcore.AddSync(os.Stdout), zapcore.AddSync(write)) 配置
    go 复制代码
    core := zapcore.NewCore(
    	//zapcore.NewConsoleEncoder(encoderConfig),
    	zapcore.NewJSONEncoder(encoderConfig),
    	// 打印到控制台和文件
    	zapcore.NewMultiWriteSyncer(zapcore.AddSync(os.Stdout), zapcore.AddSync(write)),
    	//write,
    	level,
    )	
    image.png
    image.png

七、何处打印日志

我们一般分以下几种情况:

  • 在分支语句处打印日志。在分支语句处打印日志,可以判断出代码走了哪个分支,有助于判断请求的下一跳,继而继续排查问题。
  • 写操作必须打印日志。写操作最可能会引起比较严重的业务故障,写操作打印日志,可以在出问题时找到关键信息。
  • 在循环中打印日志要慎重。如果循环次数过多,会导致打印大量的日志,严重拖累代码的性能,建议的办法是在循环中记录要点,在循环外面总结打印出来。
  • 在错误产生的最原始位置打印日志。对于嵌套的 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()
	}
}
觉得有用就点个赞,不用登录也能读

评论

0 条
登录 之后才能评论
—
还没有评论,来说第一句