descheduler 项目中的 logr 结构化日志 API 深度解析:从 Logger/LogSink 双接口到 slog 互操作

原创2026-10-11 23:45:411,685 阅读
文章标签:云原生运维

descheduler 项目中的 logr 结构化日志 API 深度解析:从 Logger/LogSink 双接口到 slog 互操作

导读

本文以 Kubernetes 生态中广泛采用的轻量日志抽象层 logr 为核心,系统讲解其"双 API"设计(面向应用作者的 Logger 与面向日志库实现者的 LogSink)、结构化键值对日志的典型用法、与 Go 标准库 slog 的差异与互操作方案,以及 FAQ 中的关键设计决策。文中结合当前仓库 descheduler(sigs.k8s.io/descheduler)的真实使用场景,说明 logr 如何作为 klog 的底层抽象贯穿于去调度器的插件、驱逐与主循环中,帮助读者既掌握 logr 的使用方法,也理解其在真实 Kubernetes 组件中的落地形态。


1. logr 是什么:一套不做日志的日志 API

logr 的核心主张是:它不提供日志实现,只定义一套 API。Go 程序与库在编写日志代码时,只需依赖 logr.Logger 这一低扇出(low dependency fan-out)类型,而真正把日志写到文件、stdout 或其它后端的动作,全部交由实现了 LogSink 接口的后端完成。

这套设计把两类使用者彻底解耦:

  • Logger 类型——面向应用与库作者。它提供一套小而稳定的 API,可以在任何需要输出日志的地方使用;
  • LogSink 接口——面向日志库实现者。它是一个纯接口,由各日志框架实现以提供真正的日志功能。

由于解耦,库作者写代码时只面向 logr.Logger,而"选择什么日志实现"这件事被上移到接近 main() 的位置统一决定;应用开发者可以随时按需更换实现,无需改动业务代码。

该机制在当前仓库 vendor/github.com/go-logr/logr/README.md 中有完整阐述,并且 descheduler 正是这一理念的受益者:项目 go.mod 中声明了 github.com/go-logr/logr v1.4.3(作为间接依赖),而所有业务代码并不直接面向 logr 实现,而是经由 klog.Logger(即 klog.NewKlogr() 返回的 logr 兼容 logger)统一输出。

2. 典型用法:从根 Logger 到业务代码的传递

logr 推荐的用法是:在应用生命周期早期决定并创建"根 logger",然后把它传给各个库与结构体。

2.1 在 main 中创建根 Logger

func main() {
    // ... 其它初始化代码 ...

    // 创建"根"logger。logimpl 是选定的具体实现,
    // 它接收若干初始参数并返回一个 logr.Logger。
    logger := logimpl.New(param1, param2)

    // ... 其它初始化代码 ...

    app := createTheAppObject(logger)
    app.Run()
}

2.2 在业务代码中按 logr.Logger 使用

除初始化阶段外,其它包完全不需要知道实现是谁,只需要面向收到的 logr.Logger 输出日志:

type appObject struct {
    // ... 其它字段 ...
    logger logr.Logger
    // ... 其它字段 ...
}

func (app *appObject) Run() {
    app.logger.Info("starting up", "timestamp", time.Now())

    // ... 应用代码 ...
}

这种"根部创建、四处传递"的模式在 descheduler 中体现得十分典型。在 pkg/framework/plugins/removeduplicates/removeduplicates.go 等插件中,logger klog.Logger 作为插件结构体的字段被注入,随后以结构化方式输出:

logger.V(2).Info("Processing node", "node", klog.KObj(node))
logger.Error(err, "Error listing evictable pods on node", "node", klog.KObj(node))

同一模式也出现在 pkg/framework/plugins/removepodshavingtoomanyrestarts/toomanyrestarts.go:

logger.V(2).Info("Processing node", "node", klog.KObj(node))
logger.V(4).Info(fmt.Sprintf("ignoring pod for eviction due to: %s", err.Error()), "pod", klog.KObj(pod))
logger.Error(err, "eviction failed")

可以看到:消息是常量字符串,动态信息全部通过键值对表达;对象引用使用 klog.KObj() 序列化为可读的 namespace/name 形式,而不是整个对象。这正是 logr 结构化日志"消息恒定、键值承载变量"的规范用法。

3. 为什么需要 logr:背景与设计动机

3.1 背景

如果 Go 标准库当初就定义了日志接口,这个项目可能不会存在。Go 官方后来在 slog(见 golang/go#56345)的开发中采纳了 logr 的部分设计,但也保留了一些、改动了一些。两者的对照如下(摘自原文档):

特性 logr slog
高层 API Logger(按值传递) Logger(按指针传递)
低层 API LogSink Handler
栈展开 由 LogSink 完成 由 Logger 完成
跳过辅助函数 WithCallDepth、WithCallStackHelper Logger 不支持
按需生成日志值 Marshaler LogValuer
日志级别 非负整数,越大越"不重要" 正负都有,0 表示 info,越大越"重要"
错误日志 始终记录,不设 verbosity 普通条目,级别 >= LevelError
通过 context 传递 logger NewContext、FromContext 无 API
为 logger 命名 WithName 无 API
沿调用链调整日志详略 V 无 API
键值对分组 不支持 WithGroup、GroupValue
传递 context 以提取附加值 无 API InfoCtx 等 API 变体

slog 的高层 API 明确被定位为可叠加在共享 slog.Handler 之上的众多 API 之一;logr 就是其中之一,并通过转换函数与 slog 互通(见第 5 节)。

3.2 灵感来源与差异

logr 的设计深受 Dave Cheney 博客《Let's talk about logging》的启发,但与其核心主张有两点差异:

  1. 坚持日志 API,而不是退回到 fmt.Printf()。考虑到输出位置、时间戳、文件行号装饰与结构化日志等需求,logr 把日志 API 收敛为恰好两类:info 与 error。

    • info 日志:想告诉用户、但并非错误的信息;
    • error 日志:真正的错误。如果代码从下层函数收到了 error,并且选择记录它而不把它向上返回,就应该使用 error 日志。
  2. info 日志采用数值 verbosity 而非命名级别。这给了开发者表达 info 日志任意重要程度的手段,而无需使用 "warning"、"trace"、"debug" 这类带语义含义的名字。由于 verbosity 是数值,可以放心地认为"应用以更高 verbosity 运行"意味着"会产出更多(且更不重要)的日志"。

3.3 为什么不是纯接口

Logger 被实现为结构体而非接口,是为了让 Go 编译器能够优化"高 V 级 Info 日志未被触发"的场景(如高 V 日志的调用开销)。虽然这些优化并未全部实现,但结构体形态是确保它们未来可以实现的先决条件;所有真正的工作都藏在 LogSink 接口后面。

4. 常见实现:面向后端的生态

logr 本身是 API,真正写日志的是实现。原文档列出的实现(非穷举)包括:

对 Kubernetes 系组件而言,klogr 是最重要的一条链路。descheduler 走的正是这条路:klog.NewKlogr()(定义见 vendor/k8s.io/klog/v2/klogr.go)返回一个功能上等同于 klogr.NewWithOptions(klogr.FormatKlog) 的 klog.Logger,即 logr API 的实现直接把结构化键值合并后透传给 klog 输出。descheduler 的全部插件与核心流程都持有 klog.Logger,例如 defaultevictor.go 中的 logger klog.Logger 字段,以及测试中通过 klog.NewKlogr() 注入的 logger(见 defaultevictor_test.go)。

5. 与 slog 的互操作

logr 与 slog 的互操作是双向的:既可以用 logr.Logger 的 API 驱动 slog.Handler,也可以用 slog.Logger 的 API 驱动 logr.LogSink。核心转换函数是:

  • FromSlogHandler:把 slog.Handler 包装成 logr.Logger;
  • ToSlogHandler:把 logr.LogSink 包装成 slog.Handler;
  • 惯例上再用 slog.New 把该 Handler 包装进 slog 的高层 API。

5.1 用 logr.LogSink 作为 slog 的后端

理想情况下,一个 logr sink 实现应同时实现普通 logr 接口与 SlogSink。由于公共的 Enabled 方法在参数上存在冲突(见 golang/go#59110),同一个类型无法同时实现 slog.Handler 与 logr.Sink。

若两者都支持,日志调用可直接从高层 API 到达后端,无需转换参数;FromSlogHandler/ToSlogHandler 往返转换也无需额外包装——唯一的例外是:当 Logger.V 曾调整过 verbosity 时,ToSlogHandler 需要用一个包装器在后续日志调用中继续保持该 verbosity。此类实现还应同时支持两边的特殊值接口(logr.Marshaler、slog.LogValuer、slog.GroupValue),logr 不会主动转换它们。

不支持 slog 的代价(原文档列出的缺陷)包括:

  • 源码位置记录:经 slog.Logger 调用时正确,但其它情况下可能错误——因为 logr.Sink 自己做栈展开,而不是使用高层 API 传入的程序计数器;
  • slog 级别 <= 0 可以通过取反无损映射为 logr 级别,但所有 > 0 的 slog 级别(如 slog.LevelWarning,slog.Logger.Warn 使用它)在调用 sink 前必须映射为 0,因为 logr 不支持"比 info 更重要"的级别;
  • slog 的 group 概念只能靠"在键名前缀组名、点号分隔"近似实现,对 JSON 这类结构化输出而言,把键值对嵌套进对象会更好;
  • slog 的特殊值与接口无法按预期工作;
  • 开销大概率更高。

这些缺陷足够严重,因此原文档建议:混用 slog 与 logr 的应用应当切换到其它后端。

5.2 用 slog.Handler 作为 logr 的后端

反方向(用纯 slog.Handler、不带 logr 支持)的效果更好:

  • logr 的所有 verbosity 级别都能通过取反 1:1 映射到对应 slog 级别;
  • 栈展开由 SlogSink 完成,得到的程序计数器传给 slog.Handler;
  • Logger.WithName 添加的名称会被收集起来,以 logger 为键、/ 分隔的字符串为值记入额外属性;
  • Logger.Error 会被转成级别为 slog.LevelError 的日志记录;若提供了 error,还会附加一个键为 err 的属性。

主要缺点是 logr.Marshaler 不受支持。类型最好同时实现 logr.Marshaler 与 slog.Valuer;如果不需要与不支持 slog 的 logr 实现保持兼容,那么只实现 slog.Valuer 就足够了。

5.3 slog 的 context 支持

slog 本身不支持把 logger 放进 context.Context,logr 用 NewContextWithSlogLogger 与 FromContextAsSlogLogger 补齐了这个缺口:它们与 NewContext/FromContext 共用同一个 context key,分别存储与取出 slog.Logger 指针。当 NewContextWithSlogLogger 之后调用 FromContext 时,后者会自动把 slog.Logger 转换成 logr.Logger;FromContextAsSlogLogger 则负责相反方向。

这种方案让"只用 slog 或只用 logr"的二进制尽量高效、无多余分配——这也是 API 存储 slog.Logger 指针而非 slog.Handler 的原因:若存储 Handler,取出时创建 slog.Logger 必然要分配一次。代价是来回切换会增加分配。

鉴于 logr 已被许多包(尤其是 Kubernetes)广泛使用,原文档给出的建议是:在需要上下文日志(contextual logging)的代码中使用 logr.Logger API。另一种替代方案是把值存进 context、并配置后端在发日志时提取这些值,但这要求日志调用携带 context,而 logr API 不支持这一点。

6. FAQ:结构化日志与 V 级的设计哲学

6.1 为什么用结构化日志?

  • 更易查询:键值对让检索特定值变得容易——比如按错误码过滤请求日志、按对象名与命名空间检索 Kubernetes reconciler 日志;
  • 更易交叉引用:只要保持键的约定一致,就能把与某个概念相关的所有日志行聚合起来;
  • 提供更精细的过滤维度:可以配置"只记录某些键、不记录另一些",或只输出某键匹配某值的日志行,而不只是依赖 V 级和名字;
  • 更好表达结构化数据:部分数据天然是结构化的(如元组关联对象),结构化日志在输出时可以保留这种结构。

6.2 为什么用 V 级而不是命名级别(Info/Warning/Error)?

V 级给了运维人员一个轻松控制日志嘈杂程度的旋钮:包可以借此区分一条消息的相对重要程度;当某个 logger 或包输出过多时,用户直接调整该库的 V 级即可,无需改代码。命名级别(如 warning/trace/debug)表面相似,但本质差异在于缺乏语义——verbosity 是纯数值。

6.3 为什么不允许格式化字符串?

格式化字符串会抵消结构化日志的大部分好处:

  • 不做模糊搜索/正则就很难检索;
  • 无法结构化存储数据(内容被拍平进字符串);
  • 无法交叉引用;
  • 不易压缩(消息不是常量)。

唯一的例外技巧是:把位置参数转成带数字键的键值对——但那等于用无意义键做键值日志。若确实必须用格式化字符串,就把它用在某个键的值里、自己调用 fmt.Sprintf,例如把 log.Printf("unable to reflect over type %T") 改写成 logger.Info("unable to reflect over type", "type", fmt.Sprintf("%T"))。

原文档还给出了两个来自 Kubernetes 代码库的迁移示例:

// 之前(klog):
klog.V(4).Infof("Client is returning errors: code %v, error %v", responseCode, err)
// 之后(logr):
logger.Error(err, "client returned an error", "code", responseCode)

// 之前(klog):
klog.V(4).Infof("Got a Retry-After %ds response for attempt %d to %v", seconds, retries, url)
// 之后(logr):
logger.V(4).Info("got a retry-after response when requesting url",
    "attempt", retries, "after seconds", seconds, "url", url)

迁移心法只有两步:① 用 TL;DR 风格写出这条日志到底想说什么,作为常量消息;② 凡是想用格式符的地方,看它前面的词,把它变成键值对。

6.4 各库 V 级不一致怎么办?

没关系。按 logger 粒度控制 V 级,用 WithName 给不同库传不同的 logger。当然,同一个 logger 内部应尽量保持 V 级口径一致,这样决策"请求多详细的日志"才更容易。

6.5 如何选择 V 级与键名?

V 级只有一个硬约束:V 级越高表示日志越啰嗦、越偏调试。实践起点可以是:0 表示"永远想看"、1 表示"可能想关掉的常见日志"、10 表示"我要压测你的日志采集栈"。然后从 1 向上、从 10 向下逐步填充中间级别(10 以下偏 debug/trace,1 以上偏更啰嗦的 info)。参考:slog 预定义了 -4 给 debug 日志(对应 logr 的 4),这与 Kubernetes 官方推荐一致。

键名约定(原文档建议):

  • 键要人类可读;
  • 常量键通常是好主意;
  • 全代码库保持键的一致性;
  • 键应自然对应消息字符串的组成部分;
  • 简单键用小写,复杂键用 lowerCamelCase(Kubernetes 已采纳该约定)。

键名本身几乎不受限制(甚至允许空格),但最好只用可打印 ASCII 字符、并匹配日志行的整体字符集。键就是每条日志消息的 schema:同一日志行在不同实例若使用不同键,会让结构化日志几乎不可用——Sprintf() 是给值用的,不是给键用的!

6.6 为什么键值对而不是 map?

键值对在优化上容易得多,尤其在**分配(allocation)**方面——zap(启发 logr 接口的结构化日志器)的性能数据可以佐证。虽然接口看起来不那么直观,但换来了潜在更优的性能,也免去了用户每次都要敲 map[string]string{} 的负担。

7. 在 descheduler 中的落地:logr × klog 的实战切片

logr 在 descheduler 中的真实形态是"logr API 作为 klog 的底层抽象":

  1. 依赖:项目在 go.mod 中声明 github.com/go-logr/logr v1.4.3(间接依赖),由 k8s 生态组件透传引入;
  2. 载体:所有插件与核心模块持有的是 klog.Logger(logr 兼容 logger),来源为 klog.NewKlogr()(实现见 vendor/k8s.io/klog/v2/klogr.go),它把结构化键值合并后透传 klog 输出;
  3. 典型调用:插件中大量使用 logger.V(n).Info(...)、logger.Error(err, "msg", ...) 的结构化写法,对象引用统一用 klog.KObj(pod) 表达,例如 toomanyrestarts.go 与 removeduplicates.go;
  4. 主循环日志:descheduler 主流程同样遵循"常量消息 + 键值对"规范,例如 descheduler.go 中的 klog.V(1).InfoS("Number of evictions/requests", "totalEvicted", ..., "evictionRequests", ...),以及驱逐模块中 klog.ErrorS(err, "Error evicting pod", "limit", ..., "namespace", ..., "pod", klog.KObj(pod)) 的写法(见 evictions.go);
  5. 测试:单元测试通过 klog.NewKlogr() 直接注入 logger(见 defaultevictor_test.go),验证了"根 logger 由调用方注入、业务代码只面向抽象"的解耦设计。

这套组合的价值在于:logr 提供的抽象让 descheduler 的插件代码无需感知底层输出格式(文本还是 JSON),而 klog 则保证了与整个 Kubernetes 生态(-v 标志、klog 格式、KObj 约定)的一致性——两者的衔接点正是 klogr 这一 logr 后端实现。

8. 总结

logr 是一个"只定义 API、不提供实现"的 Go 日志抽象层:Logger 让应用与库作者以结构化的键值对方式记录 info/error 日志,LogSink 则把"怎么写、写到哪里"交给后端实现,二者在根部解耦、可随时替换。它坚持常量消息 + 数值 V 级的哲学,拒绝格式化字符串与命名级别,从而保证日志的可检索、可过滤与可交叉引用。通过 FromSlogHandler/ToSlogHandler 与 context 辅助函数,logr 与 Go 标准库 slog 可以双向互操作,虽然各自存在权衡。在 descheduler 项目中,logr 经由 klog.NewKlogr() 落地,成为去调度插件、驱逐模块与主循环统一的结构化日志底座——这既是 logr 设计意图的活样板,也是理解整个 Kubernetes 日志体系(logr/klog/slog)的上佳入口。

登录后查看全文
descheduler