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.
103 lines
3.7 KiB
Markdown
103 lines
3.7 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` 模块包含日志处理的代码, 由 4 个包组成:
|
|
|
|
1. [logsdk](./logsdk): 日志实现;
|
|
2. [logjson](./logsdk/logjson): 控制台 JSON 日志处理器(`Processor`);
|
|
3. [logtext](./logsdk/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` 方法)
|
|
|
|
```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` 需要是附加调用栈的等级(例如: `Error`);
|
|
|
|
mock, 实现 mock 日志处理器对生成的日志进行处理;
|
|
|
|
---
|
|
|
|
## 日志处理器
|
|
|
|
- [logsdk/logjson](logsdk/logjson) 控制台 JSON 日志.
|
|
- [logtext](./logsdk/logtext): 控制台文本日志.
|
|
- [go get git.blauwelle.com/go/crate/logotel](../logotel) OpenTelemetry 日志.
|