crate/log/README.md

log 日志

安装: go get git.blauwelle.com/go/crate/log

简单使用方式

package main

import (
	"context"

	"git.blauwelle.com/go/crate/log"
	"git.blauwelle.com/go/crate/log/logsdk"
	"git.blauwelle.com/go/crate/log/logsdk/logjson"
)

func main() {
	log.Logger().AddProcessor(logsdk.AllLevels, logjson.New()) // 添加日志处理器, 默认没有处理器(日志生成后会被忽略)
	log.Info(context.Background(), "hello world")              // 打印日志, Context 会被传递给日志处理器
}

log 模块包含日志处理的代码, 由 4 个包组成:

1. logsdk: 日志实现;
2. logjson: 控制台 JSON 日志处理器(Processor);
3. logtext: 控制台文本日志处理器(Processor);
4. log: 根目录, 提供全局 Logger, 把 Logger / Entry 相关的方法封装成函数.

基本概念

logsdk 由 Logger, Entry, Processor 3 部分组成, 其中只有 Processor 是接口类型. Logger 主要负责全局的日志配置, Logger 可以通过内嵌的 Entry 值对象实现日志处理. Entry 负责保存局部的的日志配置, 比如覆盖 Logger 的 Caller 开关或设置日志的时间属性; Entry 生成单条日志(ReadonlyEntry), 并调用 Processor 输出日志.

使用方式

获取全局 Logger 对象

一般只用来配置全局 Logger 对象(通过 Set* 或 AddProcessor 方法)

log.Logger()

修改 Logger 配置

Logger 提供以下方法用来修改全局配置

• AddProcessor 新增处理器;
• SetLevel 设置全局日志等级, 只有小于 Logger 上设置的日志等级的日志才会被生成;
• SetCallerSkip 设置从 runtime 包获取调用信息时的 skip 参数, 为了方便使用, 0 表示调用 Logger / Entry 的日志方法处;
• SetReportCaller 设置生成调用信息;
• SetReportStack 设置生成调用栈;
• SetReportStackLevel 当日志等级小于设定值时强制生成调用栈;
• Reset 把 Logger 恢复到初始状态;
• AddBeforeExit 增加 Exit 在调用 [os.Exit] 前执行的函数, 先增加的后执行;

日志生成

Entry 负责生成日志, Logger 通过内嵌 Entry 值对象的方式获得 Entry 的方法. Entry 提供以下方法来修改局部配置, log 包提供了对应的函数调用

• AddCallerSkip 增加通过 runtime 获取调用信息时的 skip 值, skip 可以是负值;
• WithField 添加1组键值对;
• WithFields 添加键值对;
• WithTime 设置生成的日志的时间;
• WithReportCaller 覆盖 Logger 上的生成调用信息的设置;
• WithReportStack 覆盖 Logger 上的生成调用栈的设置;

Entry 提供以下方法来生成日志, 所有方法的第 1 个参数都是 context.Context, Log 方法的参数包含日志等级和日志消息, 其他方法的参数是日志消息. 所有方法除了 Log 外日志等级从高到底(严重程度从低到高), 这些方法有对应的格式化方法(如 Info 和 Infof). log 包提供了对应的函数调用

• Log
• Trace
• Debug
• Info
• Warn
• Error
• Fatal
• Panic

其他用法

关闭日志生成, log.Logger().SetLevel(logsdk.LevelDisabled);

关闭强制生成调用栈, log.Logger().SetReportStackLevel(logsdk.LevelDisabled);

记录 panic, 在 defer v = recover() 后执行 log.Z(context.Background(), v), 其中 Z 需要是附加调用栈的等级(例如: Error);

mock, 实现 mock 日志处理器对生成的日志进行处理;

---

日志处理器

• logsdk/logjson 控制台 JSON 日志.
• logtext: 控制台文本日志.
• go get git.blauwelle.com/go/crate/logotel OpenTelemetry 日志.