日志 - zap - 《golang生态》

为什么选择Uber-go zap
Constants
Func
Logger">type Logger
SugaredLogger">type SugaredLogger
Option">type Option
Field">type Field
LevelEnablerFunc">type LevelEnablerFunc
Config">type Config
AtomicLevel">type AtomicLevel
SamplingConfig">type SamplingConfig
例子：

文档：https://godoc.org/go.uber.org/zap

Zap是非常快的、结构化的，分日志级别的Go日志库。

为什么选择Uber-go zap

它同时提供了结构化日志记录和printf风格的日志记录
它非常的快

根据Uber-go Zap的文档，它的性能比类似的结构化日志包更好——也比标准库更快。以下是Zap发布的基准测试信息
记录一条消息和10个字段:

记录一个静态字符串，没有任何上下文或printf风格的模板：

Constants

const (
    DebugLevel = zapcore.DebugLevel
    InfoLevel = zapcore.InfoLevel
    WarnLevel = zapcore.WarnLevel
    ErrorLevel = zapcore.ErrorLevel
    DPanicLevel = zapcore.DPanicLevel
    PanicLevel = zapcore.PanicLevel
    FatalLevel = zapcore.FatalLevel
)

Func

func NewProductionEncoderConfig() zapcore.EncoderConfig
func NewDevelopmentEncoderConfig() zapcore.EncoderConfig

type Logger

type Logger struct {
    // contains filtered or unexported fields
}

日志记录器提供快速、分层、结构化的日志记录。所有方法对于并发使用都是安全的。
Logger是为每一微秒和每一次分配都很重要的上下文设计的，因此它的API有意地倾向于性能和类型安全而不是简洁。对于大多数应用程序，SugaredLogger在性能和易用之间实现了更好的平衡。

func L() Logger
func New(core zapcore.Core, options …Option) Logger
func NewDevelopment(options …Option) (*Logger, error)

级别是DebugLevel，标准格式化输出，使用的是NewDevelopmentConfig

func NewProduction(options …Option) (*Logger, error)

级别是InfoLevel，json格式输出，使用的是NewProductionConfig

func (log Logger) Core() zapcore.Core 回日志程序的底层zapcore.Core
func (log Logger) Debug(msg string, fields …Field)
func (log Logger) Info(msg string, fields …Field)
func (log Logger) Warn(msg string, fields …Field)
func (log Logger) Error(msg string, fields …Field)
func (log Logger) DPanic(msg string, fields …Field)
func (log Logger) Panic(msg string, fields …Field)
func (log Logger) Fatal(msg string, fields …Field)
func (log Logger) Sugar() SugaredLogger
func (log Logger) Sync() error 调用底层核心的Sync方法，刷新缓冲的日志条目
func (log Logger) With(fields …Field) Logger 添加字段，不会产生打印效果
func (log Logger) WithOptions(opts …Option) Logger WithOptions克隆当前日志程序
func (log Logger) Named(s string) *Logger Named将一个新的路径段添加到记录器的名称中

logger := zap.NewExample()
defer logger.Sync()
// By default, Loggers are unnamed.
logger.Info("no name")
// The first call to Named sets the Logger name.
main := logger.Named("main")
main.Info("main logger")
// Additional calls to Named create a period-separated path.
main.Named("subpackage").Info("sub-logger")
{"level":"info","msg":"no name"}
{"level":"info","logger":"main","msg":"main logger"}
{"level":"info","logger":"main.subpackage","msg":"sub-logger"}

type SugaredLogger

type SugaredLogger struct {
    // contains filtered or unexported fields
}

SugaredLogger不坚持结构化日志，使用起来会Logger简单，单性能不如Logger，可以理解位Logger的语法糖

type Option

配置选项

type Option interface {
    // contains filtered or unexported methods
}

func AddCaller() Option 记录调用者信息，同WithCaller
func AddCallerSkip(skip int) Option 对AddCaller进行过滤

package main
import (
    "go.uber.org/zap"
)
func run(skip int) {
    logger, _ := zap.NewDevelopment(zap.AddCaller(), zap.AddCallerSkip(skip))
    defer logger.Sync()
    logger.Info("hello")
}
func main() {
    run(0)
    run(1)
  run(2)
  run(1000) //找不到caller的case
}
2021-12-29T18:10:21.074+0800    INFO    afterShip/params_check.go:10    hello
2021-12-29T18:10:21.075+0800    INFO    afterShip/params_check.go:15    hello
2021-12-29T18:10:21.075+0800    INFO    runtime/proc.go:225     hello
2021-12-29 10:10:21.075128 +0000 UTC Logger.check error: failed to get caller
2021-12-29T18:10:21.075+0800    INFO    hello

func AddStacktrace(lvl zapcore.LevelEnabler) Option 达到指定等级，记录堆栈信息
func Development() Option 开发模式的参数
func ErrorOutput(w zapcore.WriteSyncer) Option 设置日志记录器生成的错误的目标
func Hooks(hooks …func(zapcore.Entry) error) Option 新增勾子
func IncreaseLevel(lvl zapcore.LevelEnabler) Option 增加当前日志等级，如果降低会不起作用
func OnFatal(action zapcore.CheckWriteAction) Option 发生Fatal时需进行的操作
func WithCaller(enabled bool) Option 记录调用者信息
func Fields(fs …Field) Option 设置日志的默认字段

type Field

type Field = zapcore.Field

func Any(key string, value interface{}) Field 一个键，任意值
其它不做介绍，常见的一些类型

type LevelEnablerFunc

LevelEnablerFunc是实现zapcore的一种方便方式。带有匿名函数的LevelEnabler。
当在不同的输出(例如，标准错误和标准输出)之间分割日志输出时，它特别有用。有关示例代码，请参见包级别的AdvancedConfiguration示例。

type LevelEnablerFunc func(zapcore.Level) bool

func (f LevelEnablerFunc) Enabled(lvl zapcore.Level) bool

type 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"`
    // 采样策略，nil禁用采样
    Sampling *SamplingConfig `json:"sampling" yaml:"sampling"`
    // 输出格式 console 或 json
    Encoding string `json:"encoding" yaml:"encoding"`
    // 编码器配置
    EncoderConfig zapcore.EncoderConfig `json:"encoderConfig" yaml:"encoderConfig"`
    // 标准输出的指定文件 "stdout"为标准输出
    OutputPaths []string `json:"outputPaths" yaml:"outputPaths"`
    // 标准错误的指定文件 "stderr"为标准错误，注意此设置只影响内部错误;
    ErrorOutputPaths []string `json:"errorOutputPaths" yaml:"errorOutputPaths"`
    // 初始化字段,这个字段会被用到每条日志上
    InitialFields map[string]interface{} `json:"initialFields" yaml:"initialFields"`
}

func NewDevelopmentConfig() Config
func NewProductionConfig() Config
func (cfg Config) Build(opts …Option) (*Logger, error)

type AtomicLevel

可以在运行时，动态的安全的更改日志级别

type AtomicLevel struct {
    // contains filtered or unexported fields
}

func NewAtomicLevel() AtomicLevel info级别
func NewAtomicLevelAt(l zapcore.Level) AtomicLevel 指定级别
func (lvl AtomicLevel) Enabled(l zapcore.Level) bool 实现了zapcore.LevelEnabler
func (lvl AtomicLevel) SetLevel(l zapcore.Level) 更改级别
func (lvl AtomicLevel) String() string

type SamplingConfig

SamplingConfig为日志记录器设置一个采样策略。在试图保留日志的一个代表性子集时，采样会限制日志对进程施加的全局CPU和I/O负载。
如果指定，采样器将在每次决策后调用钩子。
这里配置的值为每秒。详情：zapcore.NewSamplerWithOptions

type SamplingConfig struct {
    Initial    int                                           `json:"initial" yaml:"initial"`
    Thereafter int                                           `json:"thereafter" yaml:"thereafter"`
    Hook       func(zapcore.Entry, zapcore.SamplingDecision) `json:"-" yaml:"-"`
}

例子：

Development

import (
    "go.uber.org/zap"
    "time"
)
func main() {
    logger, _ := zap.NewDevelopment()
    defer logger.Sync()
    logger.Info("无法获取网址",
        zap.String("url", "http://www.baidu.com"),
        zap.Int("attempt", 3),
        zap.Duration("backoff", time.Second),
    )
}

Production

import (
    "go.uber.org/zap"
    "time"
)
func main() {
   // zap.NewProduction json序列化输出
    logger, _ := zap.NewProduction()
    defer logger.Sync()
    logger.Info("无法获取网址",
        zap.String("url", "http://www.baidu.com"),
        zap.Int("attempt", 3),
        zap.Duration("backoff", time.Second),
    )
}

自定义

选择一个日志库除了高性能是考量的一个标准，高扩展也非常重要，例如：json key 自定义、时间格式化、日志级别等

package main
import (
    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"
    "fmt"
    "time"
)
func main() {
    encoderConfig := zapcore.EncoderConfig{
        TimeKey:        "time",
        LevelKey:       "level",
        NameKey:        "logger",
        CallerKey:      "caller",
        MessageKey:     "msg",
        StacktraceKey:  "stacktrace",
        LineEnding:     zapcore.DefaultLineEnding,
        EncodeLevel:    zapcore.LowercaseLevelEncoder,  // 小写编码器
        EncodeTime:     zapcore.ISO8601TimeEncoder,     // ISO8601 UTC 时间格式
        EncodeDuration: zapcore.SecondsDurationEncoder,
        EncodeCaller:   zapcore.FullCallerEncoder,      // 全路径编码器
    }
    // 设置日志级别
    atom := zap.NewAtomicLevelAt(zap.DebugLevel)
    config := zap.Config{
        Level:            atom,                                                // 日志级别
        Development:      true,                                                // 开发模式，堆栈跟踪
        Encoding:         "json",                                              // 输出格式 console 或 json
        EncoderConfig:    encoderConfig,                                       // 编码器配置
        InitialFields:    map[string]interface{}{"serviceName": "spikeProxy"}, // 初始化字段，如：添加一个服务器名称
        OutputPaths:         []string{"stdout"},
    }
    // 构建日志
    logger, err := config.Build()
    if err != nil {
        panic(fmt.Sprintf("log 初始化失败: %v", err))
    }
    logger.Info("log 初始化成功")
    logger.Info("无法获取网址",
        zap.String("url", "http://www.baidu.com"),
        zap.Int("attempt", 3),
        zap.Duration("backoff", time.Second),
    )
}