74 lines
3.2 KiB
Markdown
74 lines
3.2 KiB
Markdown
# Log Package README
|
||
|
||
## 概述
|
||
此`log`包提供了一套全面的日志记录功能，基于`github.com/sirupsen/logrus`库进行了深度定制和扩展。通过本包，您可以实现多级别的日志输出，并能灵活控制日志格式、时间戳显示以及调用栈信息等。
|
||
用于fusen的全部服务的统一格式化, 便于运维统一处理。
|
||
|
||
### 功能特性
|
||
1. **多级别日志**：支持`Trace`、`Debug`、`Info`、`Warn`、`Error`、`Fatal`和`Panic`等多种日志级别。
|
||
|
||
2. **追踪时间**：包含`DebuglnTrackTime`与`InfolnTrackTime`函数，用于执行指定函数并在输出时附加执行耗时（毫秒）。
|
||
|
||
3. **UTC时间**：使用了自定义的`UTCTimeHook`钩子，确保所有日志的时间戳采用协调世界时（UTC）格式。
|
||
|
||
4. **JSON格式化**：实现了`JSONFormatter`结构体，将日志条目格式化为可解析的JSON字符串。它自动跳过与logrus库自身相关的调用层级，以便更准确地显示应用代码中的文件和行号信息。
|
||
|
||
5. **上下文关联**：提供了`WithContext`方法，允许在日志条目中携带Go context.Context，便于进行请求级或事务级的跟踪。
|
||
|
||
6. **错误处理**：通过`WithError`方法可以在日志条目中便捷地添加错误对象。
|
||
|
||
7. **时间戳覆盖**：`WithTime`方法允许开发者为日志条目设置特定的时间戳。
|
||
|
||
8. **灵活格式化**：除了基本的日志输出外，还支持带有格式字符串的函数如`Printf`、`Debugf`等，以适应不同的消息格式需求。
|
||
|
||
9. **源码定位**：已启用报告调用者位置的功能，每条日志都会附带其产生的源代码文件名及行号。
|
||
|
||
### 使用示例
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"github.com/yourorg/log" // 替换为实际导入路径
|
||
"time"
|
||
)
|
||
|
||
func main() {
|
||
log.Debugln("This is a debug message.")
|
||
log.Infoln("Normal info message.")
|
||
|
||
// 添加自定义字段并格式化输出
|
||
entry := log.WithField("user_id", "123")
|
||
entry.Info("User logged in.")
|
||
|
||
// 记录并追踪函数执行时间
|
||
log.DebuglnTrackTime(func() {
|
||
time.Sleep(200 * time.Millisecond)
|
||
}, "Function execution")
|
||
|
||
// 设置日志上下文
|
||
ctx := context.Background()
|
||
ctx = log.WithContext(ctx, "request_id", "abc123")
|
||
log.Infof(ctx, "Received request with ID: %s", "abc123")
|
||
|
||
// 输出JSON格式化的日志
|
||
log.SetFormatter(&log.JSONFormatter{})
|
||
log.Warn("JSON-formatted warning.")
|
||
}
|
||
```
|
||
|
||
### 配置选项
|
||
- 在初始化阶段，已经配置了Logstash作为日志输出的目标。
|
||
- 可通过修改`l.Formatter`属性来更换或自定义日志格式器。
|
||
- 通过`AddHook`方法可以添加自定义的钩子，比如这里有一个未使用的`SkipHook`，它可以用来过滤调用栈。
|
||
|
||
### 注意事项
|
||
- 当需要同时记录多个字段时，请使用`WithFields`方法而不是多次调用`WithField`。
|
||
- 若要调整日志输出级别，请直接操作全局logger实例的level设置。
|
||
|
||
### 结构体与方法详解
|
||
- `levelSkip` 结构体用于在堆栈跟踪过程中计算需要跳过的层级数。
|
||
- `UTCTimeHook` 是一个自定义钩子，当触发时会将日志条目的时间戳设置为当前UTC时间。
|
||
- `JSONFormatter` 实现了`Format`方法，将日志条目转化为JSON格式。
|
||
|
||
|