Logger

Logger 是 DD 的核心类型，提供线程安全的日志记录功能。

创建

// 通过 New 创建
logger, _ := dd.New(dd.DefaultConfig())

// 自定义配置创建
logger, _ := dd.New(dd.Config{
    Level: dd.LevelInfo,
    Targets: []dd.OutputTarget{
        dd.ConsoleOutput(),
        dd.FileOutput("logs/app.log"),
    },
})

日志方法

基础日志

方法	说明
Debug(args ...any)	Debug 级别日志
Info(args ...any)	Info 级别日志
Warn(args ...any)	Warn 级别日志
Error(args ...any)	Error 级别日志
Fatal(args ...any)	Fatal 级别日志（默认调用 os.Exit(1)，defer 不会执行；可通过 FatalHandler 自定义）
Log(level LogLevel, args ...any)	指定级别日志

格式化日志

方法	说明
Debugf(format string, args ...any)	格式化 Debug
Infof(format string, args ...any)	格式化 Info
Warnf(format string, args ...any)	格式化 Warn
Errorf(format string, args ...any)	格式化 Error
Fatalf(format string, args ...any)	格式化 Fatal（默认调用 os.Exit(1)，defer 不会执行；可通过 FatalHandler 自定义）
Logf(level LogLevel, format string, args ...any)	格式化指定级别

结构化日志

方法	说明
DebugWith(msg string, fields ...Field)	结构化 Debug
InfoWith(msg string, fields ...Field)	结构化 Info
WarnWith(msg string, fields ...Field)	结构化 Warn
ErrorWith(msg string, fields ...Field)	结构化 Error
FatalWith(msg string, fields ...Field)	结构化 Fatal（默认调用 os.Exit(1)，defer 不会执行；可通过 FatalHandler 自定义）
LogWith(level LogLevel, msg string, fields ...Field)	结构化指定级别

logger.InfoWith("请求完成",
    dd.String("method", "GET"),
    dd.Int("status", 200),
    dd.Duration("elapsed", 100*time.Millisecond),
)

级别管理

level := logger.GetLevel()                    // 获取当前级别
_ = logger.SetLevel(dd.LevelDebug)            // 设置级别
enabled := logger.IsLevelEnabled(dd.LevelInfo)// 检查级别

// 快捷检查
logger.IsDebugEnabled()
logger.IsInfoEnabled()
logger.IsWarnEnabled()
logger.IsErrorEnabled()
logger.IsFatalEnabled()

// 动态级别解析器
logger.SetLevelResolver(func(ctx context.Context) dd.LogLevel {
    if isDebug {
        return dd.LevelDebug
    }
    return dd.LevelInfo
})
resolver := logger.GetLevelResolver()

字段链

// 预设字段，返回 LoggerEntry
entry := logger.WithFields(
    dd.String("service", "api"),
    dd.Int("version", 2),
)

// 单字段
entry := logger.WithField("env", "prod")

输出目标管理

// 添加 Writer
_ = logger.AddWriter(os.Stderr)

// 移除 Writer
_ = logger.RemoveWriter(os.Stderr)

// 获取 Writer 数量
count := logger.WriterCount()

// 设置写入错误处理器
logger.SetWriteErrorHandler(func(w io.Writer, err error) {
    fmt.Fprintf(os.Stderr, "写入失败: %v\n", err)
})

上下文集成

// 添加上下文提取器
_ = logger.AddContextExtractor(func(ctx context.Context) []dd.Field {
    return []dd.Field{
        dd.String("trace_id", dd.GetTraceID(ctx)),
    }
})

// 替换所有提取器
_ = logger.SetContextExtractors(extractor1, extractor2)

// 获取当前提取器
extractors := logger.GetContextExtractors()

钩子管理

// 注册钩子
_ = logger.AddHook(dd.HookBeforeLog, func(ctx context.Context, hc *dd.HookContext) error {
    // 日志前处理
    return nil
})

// 替换钩子注册表
_ = logger.SetHooks(registry)

// 获取钩子注册表
hooks := logger.GetHooks()

采样控制

// 设置采样配置
logger.SetSampling(&dd.SamplingConfig{
    // 采样参数
})

// 获取采样配置
cfg := logger.GetSampling()

安全配置

// 设置安全配置
logger.SetSecurityConfig(dd.DefaultSecurityConfig())

// 获取安全配置
sec := logger.GetSecurityConfig()

字段验证

// 设置字段验证
logger.SetFieldValidation(dd.StrictSnakeCaseConfig())

// 获取验证配置
validation := logger.GetFieldValidation()

生命周期

// 刷新缓冲
_ = logger.Flush()

// 关闭日志记录器
_ = logger.Close()

// 优雅关闭（带超时）
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
_ = logger.Shutdown(ctx)

// 检查是否已关闭
closed := logger.IsClosed()

// 等待过滤协程完成
ok := logger.WaitForFilterGoroutines(3 * time.Second)
active := logger.ActiveFilterGoroutines()

调试输出

方法	说明
Print(args ...any)	输出到配置的 Writer（LevelInfo，受安全过滤）
Println(args ...any)	与 Print 行为一致（底层 Log() 已自动换行）
Printf(format string, args ...any)	格式化输出（LevelInfo，受安全过滤）
JSON(data ...any)	紧凑 JSON 格式输出到 stdout（含调用者信息，不经过安全过滤）
JSONF(format string, args ...any)	格式化紧凑 JSON 输出到 stdout（含调用者信息，不经过安全过滤）
Text(data ...any)	美化打印格式输出到 stdout（不含调用者信息，不经过安全过滤）
Textf(format string, args ...any)	格式化文本输出到 stdout（不含调用者信息，不经过安全过滤）

下一步

• LoggerEntry -- 预设字段链式调用
• 配置 -- Config 详解
• 输出目标 -- FileWriter 详解