# 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格式。