XLog

package
v0.0.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 25, 2025 License: MIT Imports: 21 Imported by: 1

README

XLog

Reference Release Report DeepWiki

XLog 提供了一个遵循 RFC5424 标准的日志系统，支持多级别日志输出、多适配器管理、日志轮转和结构化标签等特性。

功能特性

  • 支持 RFC5424 标准的 8 个日志级别
  • 支持标准输出和文件存储两种适配器
  • 支持日志文件的自动轮转和清理
  • 支持异步写入和线程安全操作
  • 支持结构化的日志标签系统

使用手册

1. 基础日志记录
1.1 日志级别
// 不同级别的日志记录
XLog.Emergency("系统崩溃")  // 级别 0：紧急
XLog.Alert("需要立即处理")   // 级别 1：警报
XLog.Critical("严重错误")   // 级别 2：严重
XLog.Error("操作失败")      // 级别 3：错误
XLog.Warn("潜在问题")       // 级别 4：警告
XLog.Notice("重要信息")     // 级别 5：通知
XLog.Info("一般信息")       // 级别 6：信息
XLog.Debug("调试信息")      // 级别 7：调试
2. 日志配置
2.1 文件输出配置

文件输出适配器支持以下配置项：

prefs := XPrefs.New()
fileConf := XPrefs.New()

// 基础配置
fileConf.Set("Path", "./logs/app.log")     // 日志文件路径，支持环境变量 ${Env.xxx}
fileConf.Set("Level", "Debug")             // 日志级别：Emergency|Alert|Critical|Error|Warn|Notice|Info|Debug

// 轮转配置
fileConf.Set("Rotate", true)               // 是否启用日志轮转，默认 true
fileConf.Set("Daily", true)                // 是否按天轮转，默认 true
fileConf.Set("MaxDay", 7)                  // 日志文件保留天数，默认 7 天
fileConf.Set("Hourly", true)               // 是否按小时轮转，默认 true
fileConf.Set("MaxHour", 168)               // 日志文件保留小时数，默认 168 小时（7天）

// 文件限制
fileConf.Set("MaxFile", 100)               // 最大文件数量，默认 100 个
fileConf.Set("MaxLine", 1000000)           // 单文件最大行数，默认 100 万行
fileConf.Set("MaxSize", 134217728)         // 单文件最大体积，默认 128MB

prefs.Set("Log/File", fileConf)
2.2 标准输出配置

标准输出适配器支持以下配置项：

stdConf := XPrefs.New()

// 基础配置
stdConf.Set("Level", "Info")               // 日志级别：Emergency|Alert|Critical|Error|Warn|Notice|Info|Debug
stdConf.Set("Color", true)                 // 是否启用彩色输出，默认 true

prefs.Set("Log/Std", stdConf)
2.3 配置说明

  1. 日志级别控制：

    • 通过配置每个适配器的 Level 参数控制，低于该级别的日志不会输出
    • 可以通过 XLog.Level() 获取当前最大级别
    • 可以通过 LogTag 的 Level() 方法设置特定标签的日志级别，这将优先于全局级别
    • 示例： 
      tag := XLog.GetTag()
tag.Level(XLog.LevelDebug)  // 即使全局级别是 Info，带此标签的日志也会输出 Debug 级别
XLog.Debug(tag, "调试信息")   // 此日志会被输出
XLog.Watch(tag)
XLog.Debug("调试信息")        // 同样会被输出，因为继承了上下文标签的级别
XLog.Defer()                // 清除上下文标签

  2. 日志级别优先级（从高到低）：

    • Emergency (0): 系统不可用
    • Alert (1): 必须立即采取措施
    • Critical (2): 严重错误
    • Error (3): 错误
    • Warn (4): 警告
    • Notice (5): 重要信息
    • Info (6): 一般信息
    • Debug (7): 调试信息

  3. 文件轮转策略：

    • 按天轮转：每天创建新文件，自动清理超过 MaxDay 天数的文件
    • 按小时轮转：每小时创建新文件，自动清理超过 MaxHour 小时数的文件
    • 按大小轮转：当文件超过 MaxSize 时创建新文件
    • 按行数轮转：当文件超过 MaxLine 时创建新文件
    • 文件数量限制：通过 MaxFile 控制最大文件数

  4. 日志文件命名： 假设配置 Path 为 "./logs/app.log"：

    • 按天轮转：
      • 当前文件：app.log
      • 历史文件：app.2006-01-02.001.log, app.2006-01-02.002.log, ...
    • 按小时轮转：
      • 当前文件：app.log
      • 历史文件：app.2006-01-02-15.001.log, app.2006-01-02-15.002.log, ...
    • 按大小/行数轮转：
      • 当前文件：app.log
      • 历史文件：app.001.log, app.002.log, ...

    注意：

    • 如果 Path 配置中只有后缀（如 ".log"），则文件名部分为空，例如：
      • 当前文件：.log
      • 历史文件：2006-01-02.001.log（按天）, 2006-01-02-15.001.log（按小时）
    • 如果 Path 配置中只有目录，则使用空文件名和 ".log" 后缀
    • 历史文件的序号从 001 开始递增，最大受 MaxFile 参数限制
    • 日期格式使用 ISO 8601 标准（2006-01-02 表示年月日，15 表示小时）

  5. 标准输出特性：

    • 支持 ANSI 颜色输出，不同日志级别使用不同颜色
    • Emergency: 黑色
    • Alert: 青色
    • Critical: 品红色
    • Error: 红色
    • Warn: 黄色
    • Notice: 绿色
    • Info: 灰色
    • Debug: 蓝色
3. 日志标签
3.1 使用标签
// 创建标签
tag := XLog.GetTag()
tag.Set("module", "auth")
tag.Set("user", "admin")

// 记录带标签的日志
XLog.Info(tag, "用户登录成功")

// 使用上下文标签
XLog.Watch(tag)
XLog.Info("执行操作") // 自动带上标签
XLog.Defer() // 清除上下文标签
4. 错误处理
4.1 异常捕获
defer XLog.Caught(false)
// 你的代码...
panic("发生错误")

常见问题

1. 日志文件没有轮转？

确保正确配置了轮转参数：

  • Rotate: 是否启用轮转
  • Daily/Hourly: 按天/小时轮转
  • MaxDay/MaxHour: 文件保留时间
  • MaxLine/MaxSize: 单文件限制
2. 日志级别如何控制？

通过配置每个适配器的 Level 参数控制，低于该级别的日志不会输出。可以通过 XLog.Level() 获取当前最大级别。此外，可以通过 LogTag 的 Level() 方法设置特定标签的日志级别，这将优先于全局级别。

更多问题，请查阅问题反馈。

项目信息

Documentation

Overview

XLog 提供了一个遵循 RFC5424 标准的日志系统，支持多级别日志输出、多适配器管理、日志轮转和结构化标签等特性。

功能特性

  • 支持 RFC5424 标准的 8 个日志级别
  • 支持标准输出和文件存储两种适配器
  • 支持日志文件的自动轮转和清理
  • 支持异步写入和线程安全操作
  • 支持结构化的日志标签系统

使用手册

1. 基础日志记录

1.1 日志级别 

XLog.Emergency("系统崩溃")  // 级别 0：紧急
XLog.Alert("需要立即处理")   // 级别 1：警报
XLog.Critical("严重错误")   // 级别 2：严重
XLog.Error("操作失败")      // 级别 3：错误
XLog.Warn("潜在问题")       // 级别 4：警告
XLog.Notice("重要信息")     // 级别 5：通知
XLog.Info("一般信息")       // 级别 6：信息
XLog.Debug("调试信息")      // 级别 7：调试

2. 日志配置

2.1 文件输出配置

文件输出适配器支持以下配置项： 

prefs := XPrefs.New()
fileConf := XPrefs.New()

// 基础配置
fileConf.Set("Path", "./logs/app.log")     // 日志文件路径，支持环境变量 ${Env.xxx}
fileConf.Set("Level", "Debug")             // 日志级别：Emergency|Alert|Critical|Error|Warn|Notice|Info|Debug

// 轮转配置
fileConf.Set("Rotate", true)               // 是否启用日志轮转，默认 true
fileConf.Set("Daily", true)                // 是否按天轮转，默认 true
fileConf.Set("MaxDay", 7)                  // 日志文件保留天数，默认 7 天
fileConf.Set("Hourly", true)               // 是否按小时轮转，默认 true
fileConf.Set("MaxHour", 168)               // 日志文件保留小时数，默认 168 小时（7天）

// 文件限制
fileConf.Set("MaxFile", 100)               // 最大文件数量，默认 100 个
fileConf.Set("MaxLine", 1000000)           // 单文件最大行数，默认 100 万行
fileConf.Set("MaxSize", 134217728)         // 单文件最大体积，默认 128MB

prefs.Set("Log/File", fileConf)

2.2 标准输出配置

标准输出适配器支持以下配置项： 

stdConf := XPrefs.New()

// 基础配置
stdConf.Set("Level", "Info")               // 日志级别：Emergency|Alert|Critical|Error|Warn|Notice|Info|Debug
stdConf.Set("Color", true)                 // 是否启用彩色输出，默认 true

prefs.Set("Log/Std", stdConf)

2.3 配置说明

日志级别控制：

  • 通过配置每个适配器的 Level 参数控制，低于该级别的日志不会输出
  • 可以通过 XLog.Level() 获取当前最大级别
  • 可以通过 LogTag 的 Level() 方法设置特定标签的日志级别，这将优先于全局级别

示例： 

tag := XLog.GetTag()
tag.Level(XLog.LevelDebug)  // 即使全局级别是 Info，带此标签的日志也会输出 Debug 级别
XLog.Debug(tag, "调试信息")   // 此日志会被输出
XLog.Watch(tag)
XLog.Debug("调试信息")        // 同样会被输出，因为继承了上下文标签的级别
XLog.Defer()                // 清除上下文标签

日志级别优先级（从高到低）：

  • Emergency (0): 系统不可用
  • Alert (1): 必须立即采取措施
  • Critical (2): 严重错误
  • Error (3): 错误
  • Warn (4): 警告
  • Notice (5): 重要信息
  • Info (6): 一般信息
  • Debug (7): 调试信息

文件轮转策略：

  • 按天轮转：每天创建新文件，自动清理超过 MaxDay 天数的文件
  • 按小时轮转：每小时创建新文件，自动清理超过 MaxHour 小时数的文件
  • 按大小轮转：当文件超过 MaxSize 时创建新文件
  • 按行数轮转：当文件超过 MaxLine 时创建新文件
  • 文件数量限制：通过 MaxFile 控制最大文件数

日志文件命名： 假设配置 Path 为 "./logs/app.log"：

  • 按天轮转：
  • 当前文件：app.log
  • 历史文件：app.2006-01-02.001.log, app.2006-01-02.002.log, ...
  • 按小时轮转：
  • 当前文件：app.log
  • 历史文件：app.2006-01-02-15.001.log, app.2006-01-02-15.002.log, ...
  • 按大小/行数轮转：
  • 当前文件：app.log
  • 历史文件：app.001.log, app.002.log, ...

注意：

  • 如果 Path 配置中只有后缀（如 ".log"），则文件名部分为空，例如：
  • 当前文件：.log
  • 历史文件：2006-01-02.001.log（按天）, 2006-01-02-15.001.log（按小时）
  • 如果 Path 配置中只有目录，则使用空文件名和 ".log" 后缀
  • 历史文件的序号从 001 开始递增，最大受 MaxFile 参数限制
  • 日期格式使用 ISO 8601 标准（2006-01-02 表示年月日，15 表示小时）

标准输出特性：

  • 支持 ANSI 颜色输出，不同日志级别使用不同颜色
  • Emergency: 黑色
  • Alert: 青色
  • Critical: 品红色
  • Error: 红色
  • Warn: 黄色
  • Notice: 绿色
  • Info: 灰色
  • Debug: 蓝色

3. 日志标签

3.1 使用标签 

// 创建标签
tag := XLog.GetTag()
tag.Set("module", "auth")
tag.Set("user", "admin")

// 记录带标签的日志
XLog.Info(tag, "用户登录成功")

// 使用上下文标签
XLog.Watch(tag)
XLog.Info("执行操作") // 自动带上标签
XLog.Defer() // 清除上下文标签

4. 错误处理

4.1 异常捕获 

defer XLog.Caught(false)
// 你的代码...
panic("发生错误")

更多信息请参考模块文档。

Index

Constants

View Source 
const (
	// LevelUndefined 表示未设置日志级别。
	// 用于初始化状态或表示无效的日志级别。
	LevelUndefined    LevelType = -1
	LevelUndefinedStr           = "Undefined"

	// LevelEmergency 表示最高级别的紧急情况（级别 0）。
	// 用于记录导致系统完全不可用的灾难性故障，需要立即通知所有技术人员。
	LevelEmergency    LevelType = 0
	LevelEmergencyStr           = "Emergency"

	// LevelAlert 表示需要立即处理的警报情况（级别 1）。
	// 用于记录需要立即采取行动的关键情况，如严重的安全事件或系统资源耗尽。
	LevelAlert    = 1
	LevelAlertStr = "Alert"

	// LevelCritical 表示严重的错误情况（级别 2）。
	// 用于记录严重的系统问题，如主要组件失效或关键功能不可用。
	LevelCritical    = 2
	LevelCriticalStr = "Critical"

	// LevelError 表示一般错误情况（级别 3）。
	// 用于记录影响系统正常运行的错误，如接口调用失败或业务流程中断。
	LevelError    = 3
	LevelErrorStr = "Error"

	// LevelWarn 表示警告情况（级别 4）。
	// 用于记录可能导致问题的异常情况，如资源即将耗尽或配置不当。
	LevelWarn    = 4
	LevelWarnStr = "Warn"

	// LevelNotice 表示重要的正常情况（级别 5）。
	// 用于记录需要注意但不属于错误的重要系统事件，如服务启动或配置更改。
	LevelNotice    = 5
	LevelNoticeStr = "Notice"

	// LevelInfo 表示一般信息（级别 6）。
	// 用于记录系统的正常运行信息，如常规操作日志或状态更新。
	LevelInfo    = 6
	LevelInfoStr = "Info"

	// LevelDebug 表示调试信息（级别 7）。
	// 用于记录详细的调试信息，帮助开发人员诊断和排查问题。
	LevelDebug    = 7
	LevelDebugStr = "Debug"
)

Variables

This section is empty.

Functions

func Able 

func Able(level LevelType) bool

Able 检查指定的日志级别是否允许输出。 输入日志级别，如果该级别的日志允许输出则返回 true，否则返回 false。 注意：如果存在日志标签且定义了级别，则标签的级别优先于全局级别。

func Alert 

func Alert(data any, args ...any)

Alert 记录一条警报级别的日志。 输入日志内容和可选的格式化参数，支持通过 LogTag 指定特定的日志级别和标签。 此函数用于记录需要立即引起注意和处理的系统状况。

func Caller 

func Caller(stack int, fullpath bool) string

Caller 获取调用栈信息。 stack 为要跳过的调用层级数。 fullpath 为是否显示完整的文件路径，false 则只显示函数名。 返回格式化的调用栈信息。

func Caught 

func Caught(exit bool, handler ...func(string, int))

Caught 捕获并处理异常。 exit 为是否在处理后退出程序。 handler 为可选的自定义处理函数，接收错误信息和堆栈深度。

func Close 

func Close()

Close 关闭日志系统并释放相关资源。 此函数会等待所有待写入的日志完成写入，然后关闭所有日志适配器。

func Critical 

func Critical(data any, args ...any)

Critical 记录一条严重级别的日志。 输入日志内容和可选的格式化参数，支持通过 LogTag 指定特定的日志级别和标签。 此函数用于记录需要立即注意的严重系统故障。

func Debug 

func Debug(data any, args ...any)

Debug 记录一条调试级别的日志。 输入日志内容和可选的格式化参数，支持通过 LogTag 指定特定的日志级别和标签。 此函数用于记录系统调试和故障排除的详细信息。

func Defer 

func Defer()

Defer 清理当前 goroutine 的日志标签。 从全局映射中移除当前 goroutine 的标签关联，并将标签实例返回到对象池。 通常在 goroutine 结束前调用，用于防止内存泄漏。

func Elapse 

func Elapse(stack int, callback ...func()) func()

Elapse 创建一个用于计算函数执行时间的闭包。 stack 为要跳过的调用层级数。 callback 为可选的回调函数，在计时结束时调用。 返回一个在调用时输出执行时间的函数。

func Emergency 

func Emergency(data any, args ...any)

Emergency 记录一条紧急级别的日志。 输入日志内容和可选的格式化参数，支持通过 LogTag 指定特定的日志级别和标签。 此函数用于记录导致系统完全不可用的灾难性故障。

func Error 

func Error(data any, args ...any)

Error 记录一条错误级别的日志。 输入日志内容和可选的格式化参数，支持通过 LogTag 指定特定的日志级别和标签。 此函数用于记录需要解决的错误状况。

func Flush 

func Flush()

Flush 将缓冲区中的所有日志立即写入到目标位置。 此函数会等待所有缓冲的日志被写入后才返回。

func Info 

func Info(data any, args ...any)

Info 记录一条信息级别的日志。 输入日志内容和可选的格式化参数，支持通过 LogTag 指定特定的日志级别和标签。 此函数用于记录系统的常规操作信息。

func Notice 

func Notice(data any, args ...any)

Notice 记录一条通知级别的日志。 输入日志内容和可选的格式化参数，支持通过 LogTag 指定特定的日志级别和标签。 此函数用于记录值得注意但不一定是问题的事件。

func Panic 

func Panic(data any, args ...any)

Panic 记录一条紧急日志，并触发 panic。 输入日志内容和可选的格式化参数，支持通过 LogTag 指定特定的日志级别和标签。 此函数会在记录日志后立即触发 panic，中断程序执行。

func Print 

func Print(level LevelType, force bool, tag *LogTag, data any, args ...any)

Print 记录一条指定级别的日志。 输入日志级别、是否强制输出、日志标签、日志内容和可选的格式化参数。 此函数是所有日志记录函数的底层实现，支持完整的日志记录功能。

func PutTag 

func PutTag(tag *LogTag)

PutTag 将指定的日志标签实例返回到对象池。 在返回前会重置标签的状态，并标记其已被放入池中。 重复放入同一标签是安全的，会被忽略。

func Size 

func Size() int

Size 返回当前日志缓冲区中的日志数量。 此函数可用于监控日志系统的积压情况。

func Trace 

func Trace(stack int, err any) (string, int)

Trace 获取完整的错误堆栈信息。 stack 为要跳过的调用层级数。 err 为触发堆栈跟踪的错误。 返回格式化的堆栈信息和堆栈深度。

func Warn 

func Warn(data any, args ...any)

Warn 记录一条警告级别的日志。 输入日志内容和可选的格式化参数，支持通过 LogTag 指定特定的日志级别和标签。 此函数用于记录可能导致错误的潜在问题。

Types

type LevelType 

type LevelType int

LevelType 定义日志级别类型。 遵循 RFC5424 日志标准，定义了八个日志级别（0-7），用于表示日志消息的严重程度。 每个级别都有其特定的使用场景，从系统不可用的紧急情况到详细的调试信息。

func Level 

func Level() LevelType

Level 返回当前允许输出的最大日志级别。 任何高于此级别的日志都不会被记录，除非通过日志标签强制指定了更高的级别。

type LogTag 

type LogTag struct {
	sync.RWMutex // 读写锁，保证并发安全
	// contains filtered or unexported fields
}

LogTag 定义日志标签类型。 提供了一个线程安全的容器，用于存储和管理日志的元数据信息，如键值对和日志级别。 支持动态添加和获取标签信息，可以影响日志的输出行为和格式。

func GetTag 

func GetTag() *LogTag

GetTag 从对象池中获取一个已重置为初始状态的日志标签实例。

func Tag 

func Tag(pairs ...string) *LogTag

Tag 获取或创建与当前 goroutine 关联的日志标签。 可以通过可变参数设置键值对，格式为 [key1, value1, key2, value2, ...]。 如果当前 goroutine 没有关联的标签且未提供键值对，则返回 nil。

func Watch 

func Watch(tag ...*LogTag) *LogTag

Watch 将日志标签与当前 goroutine 关联。 如果提供了日志标签参数则使用该标签，否则创建新的标签。 此函数实现了 goroutine 本地的日志标签上下文。

func (*LogTag) Clone 

func (tg *LogTag) Clone() *LogTag

Clone 创建并返回当前日志标签的深度副本。 新标签包含原标签的所有键值对，但使用独立的内存空间。

func (*LogTag) Data 

func (tg *LogTag) Data() map[string]string

Data 返回日志标签的映射表示，将所有键值对转换为 map[string]string 格式。 使用缓存机制，仅在标签内容变更时重建映射。

func (*LogTag) Get 

func (tg *LogTag) Get(key string) string

Get 获取日志标签中指定键对应的值，如果键不存在则返回空字符串。

func (*LogTag) Level 

func (tg *LogTag) Level(level ...LevelType) LevelType

Level 设置或获取日志标签的日志级别。 当提供日志级别参数时进行设置，无参数时返回当前级别。 标签的日志级别可以覆盖全局的日志级别设置。

func (*LogTag) Reset 

func (tg *LogTag) Reset()

Reset 重置日志标签的所有字段为初始状态。 此方法会清空所有标签信息并重置内部状态标记。 通常在将标签对象放回对象池前调用，以确保下次使用时的状态正确。

func (*LogTag) Set 

func (tg *LogTag) Set(key string, value string)

Set 设置日志标签中的键值对。 如果键已存在，则更新其值；如果键不存在，则添加新的键值对。 设置后会标记需要重建文本和数据缓存。

func (*LogTag) Text 

func (tg *LogTag) Text() string

Text 返回日志标签的文本表示。 格式为 "[key1 = value1, key2 = value2, ...]"。 如果没有标签，则返回空字符串。 使用缓存机制，仅在标签内容变更时重建文本。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.