一文告诉你如何用好uber开源的zap日志库

本文永久链接 – https://tonybai.com/2021/07/14/uber-zap-advanced-usage

1. 引子

日志在后端系统中有着重要的地位,通过日志不仅可以直观看到程序的当前运行状态,更重要的是日志可以在程序发生问题时为开发人员提供线索。

在Go生态中,logrus可能是使用最多的Go日志库,它不仅提供结构化的日志,更重要的是与标准库log包在api层面兼容。在性能不敏感的领域,logrus确实是不二之选。

但在性能敏感的领域和场景下,logrus便不那么香了,出镜更多的是大厂uber开源的名为zap的日志库。之所以在这些场景下zap更香,虽与其以高性能著称不无关系,但其背后的大厂uber背书也是极其重要的。uber大厂有着太多性能和延迟敏感的场景,其生产环境现存数千个Go语言开发的微服务,这些微服务估计大多使用的都是zap,经历过大厂性能敏感场景考验的log库信誉有保障,后续有人持续维护,自然被大家青睐。

关于zap高性能的原理,在网络上已经有不少高质量的资料(参见本文末的参考资料)做过详尽的分析了。zap的主要优化点包括:

  • 避免使用interface{}带来的开销(拆装箱、对象逃逸到堆上
  • 坚决不用反射,每个要输出的字段(field)在传入时都携带类型信息(这虽然降低了开发者使用zap的体验,但相对于其获得的性能提升,这点体验下降似乎也算不得什么):
logger.Info("failed to fetch URL",
    // Structured context as strongly typed Field values.
    zap.String("url", `http://foo.com`),
    zap.Int("attempt", 3),
    zap.Duration("backoff", time.Second),
)
  • 使用sync.Pool减少堆内存分配(针对代表一条完整日志消息的zapcore.Entry),降低对GC压力。

下面是一个简单zap与logrus的性能基准benchmark对比:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/benchmark/log_lib_test.go
package main

import (
    "io"
    "testing"
    "time"

    "github.com/sirupsen/logrus"
    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"
)

func BenchmarkLogrus(b *testing.B) {
    b.ReportAllocs()
    b.StopTimer()
    logger := logrus.New()
    logger.SetOutput(io.Discard)
    b.StartTimer()
    for i := 0; i < b.N; i++ {
        logger.WithFields(logrus.Fields{
            "url":     "http://foo.com",
            "attempt": 3,
            "backoff": time.Second,
        }).Info("failed to fetch URL")
    }
}

func BenchmarkZap(b *testing.B) {
    b.ReportAllocs()
    b.StopTimer()
    cfg := zap.NewProductionConfig()
    core := zapcore.NewCore(
        zapcore.NewJSONEncoder(cfg.EncoderConfig),
        zapcore.AddSync(io.Discard),
        zapcore.InfoLevel,
    )
    logger := zap.New(core)
    b.StartTimer()
    for i := 0; i < b.N; i++ {
        logger.Info("failed to fetch URL",
            zap.String("url", `http://foo.com`),
            zap.Int("attempt", 3),
            zap.Duration("backoff", time.Second),
        )
    }
}

在上面的基准测试中,我们使用logrus和zap分别向io.Discard写入相同内容的日志,基准测试的运行结果如下:

$go test -bench .
goos: darwin
goarch: amd64
pkg: github.com/bigwhite/zap-usage
cpu: Intel(R) Core(TM) i5-8257U CPU @ 1.40GHz
BenchmarkLogrus-8         281667          4001 ns/op        1365 B/op         25 allocs/op
BenchmarkZap-8           1319922           901.1 ns/op       192 B/op          1 allocs/op
PASS
ok      github.com/bigwhite/zap-usage   3.296s

我们看到zap的写日志性能是logrus的4倍,且每op仅一次内存分配,相比之下,logrus在性能和内存分配方面的确逊色不少。

有优点,就有不足。前面也说过,虽然zap在性能方面一骑绝尘,但是在使用体验方面却给开发者留下“阴影”。就比如在上面的性能基准测试中,考虑测试过程中的日志输出,我们没有采用默认的向stdout或stderr写入,而是将output设置为io.Discard。这样的改变在logrus中仅需一行:

logger.SetOutput(io.Discard)

而在zap项目的官方首页中,我居然没有找到进行这一变更的操作方法,在一阵查询和阅读后,才找到正确的方法(注:方法不唯一):

cfg := zap.NewProductionConfig()
core := zapcore.NewCore(
        zapcore.NewJSONEncoder(cfg.EncoderConfig),
        zapcore.AddSync(io.Discard),
        zapcore.InfoLevel,
)
logger := zap.New(core)

上面的logrus和zap在创建写向io.Discard的logger时的方法对比很直观地反映出两者在使用体验上的差异。

那么选择了zap后,我们如何能更好地使用zap以尽量弥合与logrus等log库在体验方面的差距呢?这就是本文想要和大家分享的内容。

2. 对zap进行封装,让其更好用

进入Go世界后,大家使用的第一个log库想必是Go标准库自带的log包,log包可谓是“开箱即用”:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/stdlog/demo1.go 

import "log"

func main() {
    log.Println("this is go standard log package")
}

上面的示例代码直接向标准错误(stderr)输出一行日志内容,而我们居然连一个logger变量都没有创建。即便是将日志写入文件,在log包看来也是十分easy的事情,看下面代码段:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/stdlog/demo2.go 

package main

import (
    "log"
    "os"
)

func main() {
    file, err := os.OpenFile("./demo2.log", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
    if err != nil {
        panic(err)
    }
    log.SetOutput(file)
    log.Println("this is go standard log package")
}

我们仅需要将实现了io.Writer的os.File传给log包的SetOutput函数即可。这种无需创建logger变量而是直接使用包名+函数的方式写日志的方式减少了传递和管理logger变量的复杂性,这种使用者体验是我们对zap进行封装的目标。不过,我们也要做到心里有数:zap是一个通用的log库,我们封装后,只需提供我们所需的特性即可,没有必要再封装成一个像zap一样通用的库。另外用户只需依赖我们封装后的log包,而无需显式依赖zap/zapcore。

下面我们就来建立demo1:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo1
$tree demo1
demo1
├── go.mod
├── go.sum
├── main.go
└── pkg
    ├── log
    │   └── log.go
    └── pkg1
        └── pkg1.go

我们对zap的封装在pkg/log/log.go中:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo1/pkg/log/log.go
package log

import (
    "io"
    "os"

    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"
)

type Level = zapcore.Level

const (
    InfoLevel   Level = zap.InfoLevel   // 0, default level
    WarnLevel   Level = zap.WarnLevel   // 1
    ErrorLevel  Level = zap.ErrorLevel  // 2
    DPanicLevel Level = zap.DPanicLevel // 3, used in development log
    // PanicLevel logs a message, then panics
    PanicLevel Level = zap.PanicLevel // 4
    // FatalLevel logs a message, then calls os.Exit(1).
    FatalLevel Level = zap.FatalLevel // 5
    DebugLevel Level = zap.DebugLevel // -1
)

type Field = zap.Field

func (l *Logger) Debug(msg string, fields ...Field) {
    l.l.Debug(msg, fields...)
}

func (l *Logger) Info(msg string, fields ...Field) {
    l.l.Info(msg, fields...)
}

func (l *Logger) Warn(msg string, fields ...Field) {
    l.l.Warn(msg, fields...)
}

func (l *Logger) Error(msg string, fields ...Field) {
    l.l.Error(msg, fields...)
}
func (l *Logger) DPanic(msg string, fields ...Field) {
    l.l.DPanic(msg, fields...)
}
func (l *Logger) Panic(msg string, fields ...Field) {
    l.l.Panic(msg, fields...)
}
func (l *Logger) Fatal(msg string, fields ...Field) {
    l.l.Fatal(msg, fields...)
}

// function variables for all field types
// in github.com/uber-go/zap/field.go

var (
    Skip        = zap.Skip
    Binary      = zap.Binary
    Bool        = zap.Bool
    Boolp       = zap.Boolp
    ByteString  = zap.ByteString
    ... ...
    Float64     = zap.Float64
    Float64p    = zap.Float64p
    Float32     = zap.Float32
    Float32p    = zap.Float32p
    Durationp   = zap.Durationp
    ... ...
    Any         = zap.Any

    Info   = std.Info
    Warn   = std.Warn
    Error  = std.Error
    DPanic = std.DPanic
    Panic  = std.Panic
    Fatal  = std.Fatal
    Debug  = std.Debug
)

// not safe for concurrent use
func ResetDefault(l *Logger) {
    std = l
    Info = std.Info
    Warn = std.Warn
    Error = std.Error
    DPanic = std.DPanic
    Panic = std.Panic
    Fatal = std.Fatal
    Debug = std.Debug
}

type Logger struct {
    l     *zap.Logger // zap ensure that zap.Logger is safe for concurrent use
    level Level
}

var std = New(os.Stderr, int8(InfoLevel))

func Default() *Logger {
    return std
}

// New create a new logger (not support log rotating).
func New(writer io.Writer, level Level) *Logger {
    if writer == nil {
        panic("the writer is nil")
    }
    cfg := zap.NewProductionConfig()
    core := zapcore.NewCore(
        zapcore.NewJSONEncoder(cfg.EncoderConfig),
        zapcore.AddSync(writer),
        zapcore.Level(level),
    )
    logger := &Logger{
        l:     zap.New(core),
        level: level,
    }
    return logger
}

func (l *Logger) Sync() error {
    return l.l.Sync()
}

func Sync() error {
    if std != nil {
        return std.Sync()
    }
    return nil
}

在这个封装中,我们有如下几点说明:

  • 参考标准库log包,我们提供包级函数接口,底层是创建的默认Logger: std;
  • 你可以使用New函数创建了自己的Logger变量,但此时只能使用该实例的方法实现log输出,如果期望使用包级函数接口输出log,需要调用ResetDefault替换更新std实例的值,这样后续调用包级函数(Info、Debug)等就会输出到新实例的目标io.Writer中了。不过最好在输出任何日志前调用ResetDefault换掉std;
  • 由于zap在输出log时要告知具体类型,zap封装出了Field以及一些sugar函数(Int、String等),这里为了不暴露zap给用户,我们使用type alias语法定义了我们自己的等价于zap.Field的类型log.Field:
type Field = zap.Field

var (
    Skip        = zap.Skip
    Binary      = zap.Binary
    Bool        = zap.Bool
    Boolp       = zap.Boolp
    ByteString  = zap.ByteString
    ... ...
)
  • 我们使用method value语法将std实例的各个方法以包级函数的形式暴露给用户,简化用户对logger实例的获取:
var (
    Info   = std.Info
    Warn   = std.Warn
    Error  = std.Error
    DPanic = std.DPanic
    Panic  = std.Panic
    Fatal  = std.Fatal
    Debug  = std.Debug
)

下面是我们利用默认std使用包级函数直接输出日志到stderr的示例:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo1/main.go
package main

import (
    "github.com/bigwhite/zap-usage/pkg/log"
    "github.com/bigwhite/zap-usage/pkg/pkg1"
)

func main() {
    defer log.Sync()
    log.Info("demo1:", log.String("app", "start ok"),
        log.Int("major version", 2))
    pkg1.Foo()
}

在这个main.go中,我们像标准库log包那样直接使用包级函数实现日志输出,同时我们无需创建logger实例,也无需管理和传递logger实例,在log包的另外一个用户pkg1包中,我们同样可以直接使用包级函数输出log:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo1/pkg/pkg1/pkg1.go

package pkg1

import "github.com/bigwhite/zap-usage/pkg/log"

func Foo() {
    log.Info("call foo", log.String("url", "https://tonybai.com"),
        log.Int("attempt", 3))
}

如果你不想使用默认的std,而是要创建一个写入文件系统文件的logger,我们可以这样处理:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo1/main_new_logger.go
package main

import (
    "os"

    "github.com/bigwhite/zap-usage/pkg/log"
    "github.com/bigwhite/zap-usage/pkg/pkg1"
)

func main() {
    file, err := os.OpenFile("./demo1.log", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
    if err != nil {
        panic(err)
    }
    logger := log.New(file, log.InfoLevel)
    log.ResetDefault(logger)
    defer log.Sync()
    log.Info("demo1:", log.String("app", "start ok"),
        log.Int("major version", 2))
    pkg1.Foo()
}

我们使用log.New创建一个新的Logger实例,然后通过log.ResetDefault用其替换掉std,这样后续的包级函数调用(log.Info)就会使用新创建的Logger实例了。

3. 自定义encoder

运行上面的demo1,我们会得到类似于下面格式的日志内容:

{"level":"info","ts":1625954037.630399,"msg":"demo1:","app":"start ok","major version":2}
{"level":"info","ts":1625954037.630462,"msg":"call foo","url":"https://tonybai.com","attempt":3}

我们可以定制zap的输出内容格式。

在定制之前,我们先来看看zap的内部结构:


图来自Go: How Zap Package is Optimized(见参考资料)

和其他log库相似,zap也是由创建logger与写log两个关键过程组成。其中zap的核心是名为zapcore.Core抽象,Core是zap定义的一个log接口,正如其名,围绕着这个Core,zap提供上层log对象以及相应的方法(zap.Logger就组合了zapcore.Core),开发者同样可以基于该接口定制自己的log包(比如:前面我们在New函数的实现)。

我们一般通过zapcore.NewCore函数创建一个实现了zapcore.Core的实例,NewCore接收三个参数,也是Core的主要组成部分,它们如下图:

                                 ┌───────────────┐
                                 │               │
                                 │               │
                      ┌─────────►│     Encoder   │
                      │          │               │
                      │          │               │
                      │          └───────────────┘
┌────────────────┐    │
│                ├────┘
│                │               ┌───────────────┐
│                │               │               │
│      Core      ├──────────────►│  WriteSyncer  │
│                │               │               │
│                ├─────┐         │               │
└────────────────┘     │         └───────────────┘
                       │
                       │
                       │         ┌───────────────┐
                       │         │               │
                       └────────►│  LevelEnabler │
                                 │               │
                                 │               │
                                 └───────────────┘
  • Encoder是日志消息的编码器;
  • WriteSyncer是支持Sync方法的io.Writer,含义是日志输出的地方,我们可以很方便的通过zap.AddSync将一个io.Writer转换为支持Sync方法的WriteSyncer;
  • LevelEnabler则是日志级别相关的参数。

由此我们看到要定制日志的输出格式,我们的重点是Encoder。

从大类别上分,zap内置了两类编码器,一个是ConsoleEncoder,另一个是JSONEncoder。ConsoleEncoder更适合人类阅读,而JSONEncoder更适合机器处理。zap提供的两个最常用创建Logger的函数:NewProduction和NewDevelopment则分别使用了JSONEncoder和ConsoleEncoder。两个编码器默认输出的内容对比如下:

// ConsoleEncoder(NewDevelopment创建)
2021-07-11T09:39:04.418+0800    INFO    zap/testzap2.go:12  failed to fetch URL {"url": "localhost:8080", "attempt": 3, "backoff": "1s"}

// JSONEncoder (NewProduction创建)
{"level":"info","ts":1625968332.269727,"caller":"zap/testzap1.go:12","msg":"failed to fetch URL","url":"localhost:8080","attempt":3,"backoff":1}

我们可以看到两者差异巨大!ConsoleEncoder输出的内容跟适合我们阅读,而JSONEncoder输出的结构化日志更适合机器/程序处理。前面我们说了,我们封装的log包不是要做通用log包,我们无需同时支持这两大类Encoder,于是我们在上面的示例选择采用的JSONEncoder:

    core := zapcore.NewCore(
        zapcore.NewJSONEncoder(cfg.EncoderConfig),
        zapcore.AddSync(writer),
        zapcore.Level(level),
    )

基于Encoder,我们可以定制的内容有很多,多数开发人员可能都会对日期格式、是否显示此条日志的caller信息等定制感兴趣。

zap库自身也提供了基于功能选项模式的Option接口:

// zap options.go
type Option interface {
    apply(*Logger)
}

func WithCaller(enabled bool) Option {
    return optionFunc(func(log *Logger) {
        log.addCaller = enabled
    })
}

我们的log库如果要提供一定的Encoder定制能力,我们也需要像Field那样通过type alias语法将zap.Option暴露给用户,同时以函数类型变量的形式将zap的部分option导出给用户。至于时间戳,我们选择一种适合我们的格式后可固定下来。下面是demo1的log的基础上增加了一些对encoder的定制功能而形成的demo2 log包:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo2/pkg/log/log.go

var std = New(os.Stderr, InfoLevel, WithCaller(true))

type Option = zap.Option

var (
    WithCaller    = zap.WithCaller
    AddStacktrace = zap.AddStacktrace
)

// New create a new logger (not support log rotating).
func New(writer io.Writer, level Level, opts ...Option) *Logger {
    if writer == nil {
        panic("the writer is nil")
    }
    cfg := zap.NewProductionConfig()
    cfg.EncoderConfig.EncodeTime = func(t time.Time, enc zapcore.PrimitiveArrayEncoder) {
        enc.AppendString(t.Format("2006-01-02T15:04:05.000Z0700"))
    }

    core := zapcore.NewCore(
        zapcore.NewJSONEncoder(cfg.EncoderConfig),
        zapcore.AddSync(writer),
        zapcore.Level(level),
    )
    logger := &Logger{
        l:     zap.New(core, opts...),
        level: level,
    }
    return logger
}

定制后,我们的log包输出的内容就变成了如下这样了:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo2/
$go run main.go
{"level":"info","ts":"2021-07-11T10:45:38.858+0800","caller":"log/log.go:33","msg":"demo1:","app":"start ok"}

4. 写入多log文件

定制完encoder,我们再来看看writeSyncer。nginx想必没人没用过,nginx有两个重要的日志文件:access.log和error.log,前者是正常的访问日志,后者则是报错日志。如果我们也要学习nginx,为业务系统建立两类日志文件,一类类似于access.log,记录正常业务吹的日志,另外一类则类似error.log,记录系统的出错日志,我们该如何设计和实现?有人可能会说,那就建立两个logger呗。没错,这的确是一个方案。但如果我就想使用包级函数来写多个log文件,并且无需传递logger实例呢?zap提供了NewTee这个导出函数就是用来写多个日志文件的。

下面我们就来用demo3来实现这个功能,我们也对外提供一个NewTee的函数,用于创建写多个log文件的logger:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo3/pkg/log/log.go
type LevelEnablerFunc func(lvl Level) bool

type TeeOption struct {
    W   io.Writer
    Lef LevelEnablerFunc
}

func NewTee(tops []TeeOption, opts ...Option) *Logger {
    var cores []zapcore.Core
    cfg := zap.NewProductionConfig()
    cfg.EncoderConfig.EncodeTime = func(t time.Time, enc zapcore.PrimitiveArrayEncoder) {
        enc.AppendString(t.Format("2006-01-02T15:04:05.000Z0700"))
    }
    for _, top := range tops {
        top := top
        if top.W == nil {
            panic("the writer is nil")
        }         

        lv := zap.LevelEnablerFunc(func(lvl zapcore.Level) bool {
            return top.Lef(Level(lvl))
        })        

        core := zapcore.NewCore(
            zapcore.NewJSONEncoder(cfg.EncoderConfig),
            zapcore.AddSync(top.W),
            lv,
        )
        cores = append(cores, core)
    }

    logger := &Logger{
        l: zap.New(zapcore.NewTee(cores...), opts...),
    }
    return logger
}

我们看到由于多个日志文件可能会根据写入的日志级别选择是否落入文件,于是我们提供了一个TeeOption类型,类型定义中包含一个io.Writer以及一个level enabler func,我们来看一下如何使用这个NewTee函数:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo3/main.go
package main

import (
    "os"

    "github.com/bigwhite/zap-usage/pkg/log"
)

func main() {
    file1, err := os.OpenFile("./access.log", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
    if err != nil {
        panic(err)
    }
    file2, err := os.OpenFile("./error.log", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
    if err != nil {
        panic(err)
    }

    var tops = []log.TeeOption{
        {
            W: file1,
            Lef: func(lvl log.Level) bool {
                return lvl <= log.InfoLevel
            },
        },
        {
            W: file2,
            Lef: func(lvl log.Level) bool {
                return lvl > log.InfoLevel
            },
        },
    }

    logger := log.NewTee(tops)
    log.ResetDefault(logger)

    log.Info("demo3:", log.String("app", "start ok"),
        log.Int("major version", 3))
    log.Error("demo3:", log.String("app", "crash"),
        log.Int("reason", -1))

}

我们建立两个TeeOption,分别对应access.log和error.log,前者接受level<=info级别的日志,后者接受level>error级别的日志。我们运行一下该程序:

$go run main.go
$cat access.log
{"level":"info","ts":"2021-07-11T12:09:47.736+0800","msg":"demo3:","app":"start ok","major version":3}
$cat error.log
{"level":"error","ts":"2021-07-11T12:09:47.737+0800","msg":"demo3:","app":"crash","reason":-1}

如我们预期,不同level的日志写入到不同文件中了,而我们只需调用包级函数即可,无需管理和传递不同logger。

5. 让日志文件支持自动rotate(轮转)

如果log写入文件,那么文件迟早会被写满!我们不能坐视不管!业内通用的方案是log rotate(轮转),即当log文件size到达一定大小时,会归档该文件,并重新创建一个新文件继续写入,这个过程对应用是透明无感知的。

而log rotate方案通常有两种,一种是基于logrotate工具的外部方案,一种是log库自身支持轮转。zap库与logrotate工具的兼容性似乎有些问题,zap官方FAQ也推荐第二种方案

不过zap并不是原生支持rotate,而是通过外部包来支持,zap提供了WriteSyncer接口可以方便我们为zap加入rotate功能。目前在支持logrotate方面,natefinch的lumberjack是应用最为官方的包,下面我们来看看如何为demo3的多日志文件增加logrotate:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/demo4/pkg/log/log.go

type RotateOptions struct {
    MaxSize    int
    MaxAge     int
    MaxBackups int
    Compress   bool
}

type TeeOption struct {
    Filename string
    Ropt     RotateOptions
    Lef      LevelEnablerFunc
}

func NewTeeWithRotate(tops []TeeOption, opts ...Option) *Logger {
    var cores []zapcore.Core
    cfg := zap.NewProductionConfig()
    cfg.EncoderConfig.EncodeTime = func(t time.Time, enc zapcore.PrimitiveArrayEncoder) {
        enc.AppendString(t.Format("2006-01-02T15:04:05.000Z0700"))
    }

    for _, top := range tops {
        top := top

        lv := zap.LevelEnablerFunc(func(lvl zapcore.Level) bool {
            return top.Lef(Level(lvl))
        })

        w := zapcore.AddSync(&lumberjack.Logger{
            Filename:   top.Filename,
            MaxSize:    top.Ropt.MaxSize,
            MaxBackups: top.Ropt.MaxBackups,
            MaxAge:     top.Ropt.MaxAge,
            Compress:   top.Ropt.Compress,
        })

        core := zapcore.NewCore(
            zapcore.NewJSONEncoder(cfg.EncoderConfig),
            zapcore.AddSync(w),
            lv,
        )
        cores = append(cores, core)
    }

    logger := &Logger{
        l: zap.New(zapcore.NewTee(cores...), opts...),
    }
    return logger
}

我们在TeeOption中加入了RotateOptions(当然这种绑定并非必须),并使用lumberjack.Logger作为io.Writer传给zapcore.AddSync,这样创建出来的logger既有写多日志文件的能力,又让每种日志文件具备了自动rotate的功能。

我们在main中使用该log:

// github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage/main.go
package main

import (
    "github.com/bigwhite/zap-usage/pkg/log"
)

func main() {
    var tops = []log.TeeOption{
        {
            Filename: "access.log",
            Ropt: log.RotateOptions{
                MaxSize:    1,
                MaxAge:     1,
                MaxBackups: 3,
                Compress:   true,
            },
            Lef: func(lvl log.Level) bool {
                return lvl <= log.InfoLevel
            },
        },
        {
            Filename: "error.log",
            Ropt: log.RotateOptions{
                MaxSize:    1,
                MaxAge:     1,
                MaxBackups: 3,
                Compress:   true,
            },
            Lef: func(lvl log.Level) bool {
                return lvl > log.InfoLevel
            },
        },
    }

    logger := log.NewTeeWithRotate(tops)
    log.ResetDefault(logger)

    // 为了演示自动rotate效果,这里多次调用log输出
    for i := 0; i < 20000; i++ {
        log.Info("demo3:", log.String("app", "start ok"),
            log.Int("major version", 3))
        log.Error("demo3:", log.String("app", "crash"),
            log.Int("reason", -1))
    }
}

运行上述main包,我们将看到如下输出:

// demo4

$go run main.go
$ls -l
total 3680
drwxr-xr-x  10 tonybai  staff      320  7 11 12:54 ./
drwxr-xr-x   8 tonybai  staff      256  7 11 12:23 ../
-rw-r--r--   1 tonybai  staff     3938  7 11 12:54 access-2021-07-11T04-54-04.697.log.gz
-rw-r--r--   1 tonybai  staff  1011563  7 11 12:54 access.log
-rw-r--r--   1 tonybai  staff     3963  7 11 12:54 error-2021-07-11T04-54-04.708.log.gz
-rw-r--r--   1 tonybai  staff   851580  7 11 12:54 error.log

我们看到access.log和error.log都在size超过1M后完成了一次自动轮转,归档的日志也按照之前的配置(compress)进行了压缩。

6. 小结

本文对zap日志库的使用方法做了深度说明,包括对zap进行封装的一种方法,使得我们可以像标准库log包那样通过包级函数直接输出log而无需管理和传递logger变量;我们可以自定义zap encoder(时间、是否输出caller等);通过NewTee可以创建一次性写入多个日志文件的logger,并且可以通过log level判断是否接受写入;最后,我们让zap日志支持了自动轮转。

如果说有不足,那就是zap不支持动态设置全局logger的日志级别,不过似乎有第三方方案,这里就不深入了,作为遗留问题留给大家了。

本文涉及到的代码可以在这里下载: https://github.com/bigwhite/experiments/tree/master/uber-zap-advanced-usage

7. 参考资料

  • Go: How Zap Package is Optimized – https://medium.com/@blanchon.vincent/go-how-zap-package-is-optimized-dbf72ef48f2d
  • 深度 | 从Go高性能日志库zap看如何实现高性能Go组件 – https://mp.weixin.qq.com/s/i0bMh_gLLrdnhAEWlF-xDw

“Gopher部落”知识星球正式转正(从试运营星球变成了正式星球)!“gopher部落”旨在打造一个精品Go学习和进阶社群!高品质首发Go技术文章,“三天”首发阅读权,每年两期Go语言发展现状分析,每天提前1小时阅读到新鲜的Gopher日报,网课、技术专栏、图书内容前瞻,六小时内必答保证等满足你关于Go语言生态的所有需求!部落目前虽小,但持续力很强。在2021年上半年,部落将策划两个专题系列分享,并且是部落独享哦:

  • Go技术书籍的书摘和读书体会系列
  • Go与eBPF系列

欢迎大家加入!

Go技术专栏“改善Go语⾔编程质量的50个有效实践”正在慕课网火热热销中!本专栏主要满足广大gopher关于Go语言进阶的需求,围绕如何写出地道且高质量Go代码给出50条有效实践建议,上线后收到一致好评!欢迎大家订
阅!

img{512x368}

我的网课“Kubernetes实战:高可用集群搭建、配置、运维与应用”在慕课网热卖中,欢迎小伙伴们订阅学习!

img{512x368}

我爱发短信:企业级短信平台定制开发专家 https://51smspush.com/。smspush : 可部署在企业内部的定制化短信平台,三网覆盖,不惧大并发接入,可定制扩展; 短信内容你来定,不再受约束, 接口丰富,支持长短信,签名可选。2020年4月8日,中国三大电信运营商联合发布《5G消息白皮书》,51短信平台也会全新升级到“51商用消息平台”,全面支持5G RCS消息。

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式:

  • 微博:https://weibo.com/bigwhite20xx
  • 微信公众号:iamtonybai
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • “Gopher部落”知识星球:https://public.zsxq.com/groups/51284458844544

微信赞赏:
img{512x368}

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

使用section.key的形式读取ini配置项

本文永久链接 – https://tonybai.com/2021/07/10/read-ini-config-item-by-passing-section-key

配置文件读取是很多Go项目必备的功能,这方面社区提供的方案也相对成熟稳定。但之前写这部分代码时除了使用了针对不同配置文件格式(比如:ini、toml等)的驱动包之外,很少直接使用第三方包对读取出的配置项的值进行管理。于是我们就面对这样一个问题:其他包如果要使用这些被读取出的配置项的值该如何做呢?我们以读取ini格式承载的配置文件为例,来简单说说。

1. 全局变量法

这是最粗糙的方法,但却是最易理解的方法。我们建立一个config包,在main函数中读取配置文件并将读取到的配置项信息存放在config包的一个导出的全局变量中,这样其他包要想获取配置文件中配置项的信息,直接通过该全局变量读取即可。下面的demo1就是一个使用全局变量组织读取出的配置项信息的示例项目,其代码结构如下:

// github.com/bigwhite/experiments/tree/master/read-ini/demo1

demo1
├── conf
│   └── demo.ini
├── go.mod
├── go.sum
├── main.go
└── pkg
    ├── config
    │   └── config.go
    └── pkg1
        └── pkg1.go

demo1中的conf/demo.ini中存储了下面这些配置项信息:

$cat demo.ini
[server]
id = 100001
port = 23333
tls_port = 83333

[log]
level = 0; info:0, warn: 1, error: 2, dpanic:3, panic:4, fatal: 5, debug: -1
compress = true ; indicate whether the rotated log files should be compressed using gzip (default true)
path = "./log/demo.log" ; if it is empty, we use default logger(to stderr)
max_age = 3 ; the maximum number of days to retain old log files based on the timestamp encoded in their filename
maxbackups = 7 ; the maximum number of old log files to retain (default 7)
maxsize = 100 ; the maximum size in megabytes of the log file before it gets rotated (default 100)

[debug]
profile_on = true ;add profile web server for app to enable pprof through web
profile_port = 8091 ; profile web port

我们通过config包读取该配置文件(基于github.com/go-ini/ini包实现ini配置文件读取):

// github.com/bigwhite/experiments/tree/master/read-ini/demo1/pkg/config/config.go
package config

import (
    ini "github.com/go-ini/ini"
)

type Server struct {
    Id      string `ini:""`
    Port    int    `ini:"port"`
    TlsPort int    `ini:"tls_port"`
}

type Log struct {
    Compress   bool   `ini:"compress"`
    LogPath    string `ini:"path"`
    MaxAge     int    `ini:"max_age"`
    MaxBackups int    `ini:"maxbackups"`
    MaxSize    int    `ini:"maxsize"`
}

type Debug struct {
    ProfileOn   bool   `ini:"profile_on"`
    ProfilePort string `ini:"profile_port"`
}

type IniConfig struct {
    Server `ini:"server"`
    Log    `ini:"log"`
    Debug  `ini:"debug"`
}

var Config = &IniConfig{}

func InitFromFile(path string) error {
    cfg, err := ini.Load(path)
    if err != nil {
        return err
    }

    return cfg.MapTo(Config)
}

这是一种典型的Go通过struct field tag与ini配置文件中section和key绑定读取的示例,我们在main包中调用InitFromFile读取ini配置文件:

// github.com/bigwhite/experiments/tree/master/read-ini/demo1/main.go

package main

import (
    "github.com/bigwhite/readini/pkg/config"
    "github.com/bigwhite/readini/pkg/pkg1"
)

func main() {
    err := config.InitFromFile("conf/demo.ini")
    if err != nil {
        panic(err)
    }
    pkg1.Foo()
}

读取后的配置项信息存储在config.Config这个全局变量中。在其他包中(比如pkg/pkg1/pkg1.go),我们可直接访问该全局变量获取配置项信息:

// github.com/bigwhite/experiments/tree/master/read-ini/demo1/pkg/pkg1/pkg1.go
package pkg1

import (
    "fmt"

    "github.com/bigwhite/readini/pkg/config"
)

func Foo() {
    fmt.Printf("%#v\n", config.Config)
}

这种方式很简单、直观也易于理解,但以全局变量形式将配置项信息暴露给其他包,从代码设计层面,这总是会予人口实的。那么我们是否可以只暴露包函数,而不暴露具体实现呢?

2. 通过section.key形式读取配置项

由于是采用的tag与结构体字段的绑定方法,实际配置项名字与绑定的字段名字可能是不一致的,比如下面代码段中的结构体字段TlsPort与其tag tls_port:

type Server struct {
    Id      string `ini:"id"`
    Port    int    `ini:"port"`
    TlsPort int    `ini:"tls_port"`
}

这样使用config包的用户在要获取配置项值时就必须了解绑定的结构体字段的名字。如果我们不暴露这些绑定结构体的实现细节的话,config包的用户所掌握的信息仅仅就是配置文件(比如:demo.ini)本身了。

于是一个很自然的想法就会萌发出来!我们是否可以通过section.key的形式得到对应配置项的值,比如以下面配置项为例:

[server]
id = 100001
port = 23333
tls_port = 83333

我们需要通过server.id来获得id这个配置项的值,类似的其他配置项的获取方式是传入server.port、server.tls_port等。这样我们的config包仅需保留类似一个接收xx.yy.zz为参数的GetSectionKey函数即可,就像下面这样:

id, ok := config.GetSectionKey("server.id")

接下来,我们就沿着这个思路在demo1的基础上重构为新方案demo2。下面是修改后的demo2的config包代码:

// github.com/bigwhite/experiments/tree/master/read-ini/demo2/pkg/config/config.go
package config

import (
    "reflect"
    "strings"

    ini "github.com/go-ini/ini"
)

type server struct {
    Id      string `ini:"id"`
    Port    int    `ini:"port"`
    TlsPort int    `ini:"tls_port"`
}

type log struct {
    Compress   bool   `ini:"compress"`
    LogPath    string `ini:"path"`
    MaxAge     int    `ini:"max_age"`
    MaxBackups int    `ini:"maxbackups"`
    MaxSize    int    `ini:"maxsize"`
}

type debug struct {
    ProfileOn   bool   `ini:"profile_on"`
    ProfilePort string `ini:"profile_port"`
}

type iniConfig struct {
    Server server `ini:"server"`
    Log    log    `ini:"log"`
    Dbg    debug  `ini:"debug"`
}

var thisConfig = iniConfig{}

func InitFromFile(path string) error {
    cfg, err := ini.Load(path)
    if err != nil {
        return err
    }

    return cfg.MapTo(&thisConfig)
}

func GetSectionKey(name string) (interface{}, bool) {
    keys := strings.Split(name, ".")
    lastKey := keys[len(keys)-1]
    v := reflect.ValueOf(thisConfig)
    t := reflect.TypeOf(thisConfig)

    found := false
    for _, key := range keys {
        cnt := v.NumField()

        for i := 0; i < cnt; i++ {
            field := t.Field(i)
            if field.Tag.Get("ini") == key {
                t = field.Type
                v = v.Field(i)
                if key == lastKey {
                    found = true
                }
                break
            }
        }
    }

    if found {
        return v.Interface(), true
    }
    return nil, false
}

我们将原先暴露出去的全局变量改为了包内变量(thisConfig),几个绑定的结构体类型也都改为非导出的了。我们提供了一个对外的函数:GetSectionKey,这样通过该函数,我们就可以使用section.key的形式获取到对应配置项的值了。在GetSectionKey函数的实现中,我们使用了反射来获取结构体定义中各个字段的tag来和传入的section.key的各个部分做比对,一旦匹配,便将对应的值传出来。如果没有匹配到,则返回false,这里GetSectionKey的返回值列表设计也使用了经典的“comma, ok”模式。

这样,我们在pkg1包中便可以这样来获取对应的配置项的值了:

// github.com/bigwhite/experiments/tree/master/read-ini/demo2/pkg/pkg1/pkg1.go
package pkg1

import (
    "fmt"

    "github.com/bigwhite/readini/pkg/config"
)

func Foo() {
    id, ok := config.GetSectionKey("server.id")
    fmt.Printf("id = [%v], ok = [%t]\n", id, ok)
    tlsPort, ok := config.GetSectionKey("server.tls_port")
    fmt.Printf("tls_port = [%v], ok = [%t]\n", tlsPort, ok)
    logPath, ok := config.GetSectionKey("log.path")
    fmt.Printf("path = [%v], ok = [%t]\n", logPath, ok)
    logPath1, ok := config.GetSectionKey("log.path1")
    fmt.Printf("path1 = [%v], ok = [%t]\n", logPath1, ok)
}

运行demo2,我们将看到如下结果:

$go run main.go
id = [100001], ok = [true]
tls_port = [83333], ok = [true]
path = [./log/demo.log], ok = [true]
path1 = [<nil>], ok = [false]

现在还有一个问题,那就是config包暴露的函数GetSectionKey的第一个返回值类型为interface{},这样我们得到配置项的值后还得根据其类型通过类型断言方式进行转型,体验略差,我们可以在config包中提供常见类型的“语法糖”函数,比如下面这些:

// github.com/bigwhite/experiments/tree/master/read-ini/demo2/pkg/config/config.go
func GetInt(name string) (int, bool) {
    i, ok := GetSectionKey(name)
    if !ok {
        return 0, false
    }

    if v, ok := i.(int); ok {
        return v, true
    }

    // maybe it is a digital string
    s, ok := i.(string)
    if !ok {
        return 0, false
    }

    n, err := strconv.Atoi(s)
    if err != nil {
        return 0, false
    }
    return n, true
}

func GetString(name string) (string, bool) {
    i, ok := GetSectionKey(name)
    if !ok {
        return "", false
    }

    s, ok := i.(string)
    if !ok {
        return "", false
    }
    return s, true
}

func GetBool(name string) (bool, bool) {
    i, ok := GetSectionKey(name)
    if !ok {
        return false, false
    }

    b, ok := i.(bool)
    if !ok {
        return false, false
    }
    return b, true
}

这样我们在pkg1包中就可以直接使用这些语法糖函数获取对应类型的配置项值了:

// github.com/bigwhite/experiments/tree/master/read-ini/demo2/pkg/pkg1/pkg1.go
b, ok := config.GetBool("debug.profile_on")
fmt.Printf("profile_on = [%t], ok = [%t]\n", b, ok)

3. 优化

配置读取一般都是在系统初始化阶段,对其性能要求不高。后续系统运行过程中,也会偶有获取配置项的业务逻辑。一旦在关键路径上有获取配置项值的逻辑,上面的方案便值得商榷,因为每次通过GetSectionKey获取一个配置项的值都要通过反射进行一番操作,性能肯定不佳。

那么如何优化呢?我们可以通过为每个key建立索引来进行。我们在config包中创建一个除初始化时只读的map变量:

// github.com/bigwhite/experiments/tree/master/read-ini/demo3/pkg/config/config.go
var index = make(map[string]interface{}, 100)

在config包的InitFromFile中我们将配置项以section.key为key的形式索引到该index变量中:

// github.com/bigwhite/experiments/tree/master/read-ini/demo3/pkg/config/config.go

func InitFromFile(path string) error {
    cfg, err := ini.Load(path)
    if err != nil {
        return err
    }

    err = cfg.MapTo(&thisConfig)
    if err != nil {
        return err
    }

    createIndex()
    return nil
}

createIndex的实现如下:

// github.com/bigwhite/experiments/tree/master/read-ini/demo3/pkg/config/config.go
func createIndex() {
    v := reflect.ValueOf(thisConfig)
    t := reflect.TypeOf(thisConfig)
    cnt := v.NumField()
    for i := 0; i < cnt; i++ {
        fieldVal := v.Field(i)
        if fieldVal.Kind() != reflect.Struct {
            continue
        }

        // it is a struct kind field, go on to get tag
        fieldStructTyp := t.Field(i)
        tag := fieldStructTyp.Tag.Get("ini")
        if tag == "" {
            continue // no ini tag, ignore it
        }

        // append Field Recursively
        appendField(tag, fieldVal)
    }
}

func appendField(parentTag string, v reflect.Value) {
    cnt := v.NumField()
    for i := 0; i < cnt; i++ {
        fieldVal := v.Field(i)
        fieldTyp := v.Type()
        fieldStructTyp := fieldTyp.Field(i)
        tag := fieldStructTyp.Tag.Get("ini")
        if tag == "" {
            continue
        }
        if fieldVal.Kind() != reflect.Struct {
            // leaf field,  add to map
            index[parentTag+"."+tag] = fieldVal.Interface()
        } else {
            // recursive call appendField
            appendField(parentTag+"."+tag, fieldVal)
        }
    }
}

这样我们的GetSectionKey就会变得异常简单:

func GetSectionKey(name string) (interface{}, bool) {
    v, ok := index[name]
    return v, ok
}

我们看到:每次调用config.GetSectionKey将变成一次map的查询操作,这性能那是相当的高:)。

4. 第三方方案

其实前面那些仅仅是一个配置项读取思路的演进过程,你完全无需自行实现,因为我们有实现的更好的第三方包可以直接使用,比如viper。我们用viper来替换demo3中的config包,代码见demo4:

// github.com/bigwhite/experiments/tree/master/read-ini/demo4/main.go
package main

import (
    "github.com/bigwhite/readini/pkg/pkg1"
    "github.com/spf13/viper"
)

func main() {
    viper.SetConfigName("demo")
    viper.SetConfigType("ini")
    viper.AddConfigPath("./conf")
    err := viper.ReadInConfig()
    if err != nil {
        panic(err)
    }
    pkg1.Foo()
}

我们在main函数中利用viper的API读取demo.ini中的配置。然后在pkg1.Foo函数中向下面这样获取配置项的值即可:

// github.com/bigwhite/experiments/tree/master/read-ini/demo4/pkg/pkg1/pkg1.go
package pkg1

import (
    "fmt"

    "github.com/spf13/viper"
)

func Foo() {
    id := viper.GetString("server.id")
    fmt.Printf("id = [%s]\n", id)
    tlsPort := viper.GetInt("server.tls_port")
    fmt.Printf("tls_port = [%d]\n", tlsPort)

    logPath := viper.GetString("log.path")
    fmt.Printf("path = [%s]\n", logPath)
    if viper.IsSet("log.path1") {
        logPath1 := viper.GetString("log.path1")
        fmt.Printf("path1 = [%s]\n", logPath1)
    } else {
        fmt.Printf("log.path1 is not found\n")
    }
}

上面的实现基本等价于我们在demo3中所作的一切,viper没有使用“comma, ok”模式,我们需要自己调用viper.IsSet来判断是否有某个配置项,而不是通过像GetString这样的函数返回的空字符串来判断。

使用viper后,我们甚至无需创建与配置文件中配置项对应的结构体类型了。viper是一个强大的Go配置操作框架,它能实现的不仅限于上面这些,它还支持写配置文件、监视配置文件变化并热加载、支持多种配置文件类型(JSON, TOML, YAML, HCL, ini等)、支持从环境变量和命令行参数读取配置,并且命令行参数、环境变量、配置文件等究竟以哪个配置为准,viper是按一定优先级次序的,从高到低分别为:

  • 明确调用Set
  • flag
  • env
  • config
  • key/value store
  • default

有如此完善的配置操作第三方库,我们完全无需手动撸自己的实现了。

5. 小结

除了在本文中提供的使用包级API获取配置项值的方法外,我们还可以将读取出的配置项集合放入应用上下文,以参数的形式“传递”到应用的各个角落,但笔者更喜欢向viper这种通过公共函数获取配置项的方法。本文阐述的就是这种思路的演化过程,并给出一个“玩票”的实现(未经系统测试),以帮助大家了解其中原理,但不要将其用到你的项目中哦。

本文涉及的源码请到这里下载:https://github.com/bigwhite/experiments/tree/master/read-ini。


“Gopher部落”知识星球正式转正(从试运营星球变成了正式星球)!“gopher部落”旨在打造一个精品Go学习和进阶社群!高品质首发Go技术文章,“三天”首发阅读权,每年两期Go语言发展现状分析,每天提前1小时阅读到新鲜的Gopher日报,网课、技术专栏、图书内容前瞻,六小时内必答保证等满足你关于Go语言生态的所有需求!部落目前虽小,但持续力很强。在2021年上半年,部落将策划两个专题系列分享,并且是部落独享哦:

  • Go技术书籍的书摘和读书体会系列
  • Go与eBPF系列

欢迎大家加入!

Go技术专栏“改善Go语⾔编程质量的50个有效实践”正在慕课网火热热销中!本专栏主要满足广大gopher关于Go语言进阶的需求,围绕如何写出地道且高质量Go代码给出50条有效实践建议,上线后收到一致好评!欢迎大家订
阅!

img{512x368}

我的网课“Kubernetes实战:高可用集群搭建、配置、运维与应用”在慕课网热卖中,欢迎小伙伴们订阅学习!

img{512x368}

我爱发短信:企业级短信平台定制开发专家 https://51smspush.com/。smspush : 可部署在企业内部的定制化短信平台,三网覆盖,不惧大并发接入,可定制扩展; 短信内容你来定,不再受约束, 接口丰富,支持长短信,签名可选。2020年4月8日,中国三大电信运营商联合发布《5G消息白皮书》,51短信平台也会全新升级到“51商用消息平台”,全面支持5G RCS消息。

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式:

  • 微博:https://weibo.com/bigwhite20xx
  • 微信公众号:iamtonybai
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • “Gopher部落”知识星球:https://public.zsxq.com/groups/51284458844544

微信赞赏:
img{512x368}

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! 图片广告位1 图片广告位2 图片广告位3 商务合作请联系bigwhite.cn AT aliyun.com

欢迎使用邮件订阅我的博客

输入邮箱订阅本站,只要有新文章发布,就会第一时间发送邮件通知你哦!

这里是 Tony Bai的个人Blog,欢迎访问、订阅和留言! 订阅Feed请点击上面图片

如果您觉得这里的文章对您有帮助,请扫描上方二维码进行捐赠 ,加油后的Tony Bai将会为您呈现更多精彩的文章,谢谢!

如果您希望通过微信捐赠,请用微信客户端扫描下方赞赏码:

如果您希望通过比特币或以太币捐赠,可以扫描下方二维码:

比特币:

以太币:

如果您喜欢通过微信浏览本站内容,可以扫描下方二维码,订阅本站官方微信订阅号“iamtonybai”;点击二维码,可直达本人官方微博主页^_^:
本站Powered by Digital Ocean VPS。
选择Digital Ocean VPS主机,即可获得10美元现金充值,可 免费使用两个月哟! 著名主机提供商Linode 10$优惠码:linode10,在 这里注册即可免费获 得。阿里云推荐码: 1WFZ0V立享9折!


View Tony Bai's profile on LinkedIn

文章

评论

  • 正在加载...

分类

标签

归档



View My Stats