You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
crate/log/README.md

101 lines
3.6 KiB
Markdown

# log 日志
安装: `go get git.blauwelle.com/go/crate/log`
简单使用方式
```go
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` 模块包含日志处理的代码, 由 3 个包组成:
1. [logsdk](./logsdk): 日志实现;
2. [logjson](./logsdk/logjson): 控制台 JSON 日志处理器(`Processor`);
3. [log](.): 根目录, 提供全局 `Logger`, 把 `Logger` / `Entry` 相关的方法封装成函数.
## 基本概念
`logsdk``Logger`, `Entry`, `Processor` 3 部分组成, 其中只有 `Processor` 是接口类型.
`Logger` 主要负责全局的日志配置, `Logger` 可以通过内嵌的 `Entry` 值对象实现日志处理.
`Entry` 负责保存局部的的日志配置, 比如覆盖 `Logger``Caller` 开关或设置日志的时间属性; `Entry` 生成单条日志(`ReadonlyEntry`), 并调用 `Processor` 输出日志.
## 使用方式
### 获取全局 `Logger` 对象
一般只用来配置全局 `Logger` 对象(通过 `Set*``AddProcessor` 方法)
```go
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` 需要是附加调用栈的等级;
mock, 实现 mock 日志处理器对生成的日志进行处理;
---
## 日志处理器
- [logsdk/logjson](logsdk/logjson) 控制台 JSON 日志
- [go get git.blauwelle.com/go/crate/logotel](../logotel) OpenTelemetry 日志