Vestmore_GO/utils/log/readme.md

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. 源码定位：已启用报告调用者位置的功能，每条日志都会附带其产生的源代码文件名及行号。

使用示例

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