descheduler 项目中的 logr 结构化日志 API 深度解析:从 Logger/LogSink 双接口到 slog 互操作
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》的启发,但与其核心主张有两点差异:
-
坚持日志 API,而不是退回到
fmt.Printf()。考虑到输出位置、时间戳、文件行号装饰与结构化日志等需求,logr 把日志 API 收敛为恰好两类:info 与 error。- info 日志:想告诉用户、但并非错误的信息;
- error 日志:真正的错误。如果代码从下层函数收到了
error,并且选择记录它而不把它向上返回,就应该使用 error 日志。
-
info 日志采用数值 verbosity 而非命名级别。这给了开发者表达 info 日志任意重要程度的手段,而无需使用 "warning"、"trace"、"debug" 这类带语义含义的名字。由于 verbosity 是数值,可以放心地认为"应用以更高 verbosity 运行"意味着"会产出更多(且更不重要)的日志"。
3.3 为什么不是纯接口
Logger 被实现为结构体而非接口,是为了让 Go 编译器能够优化"高 V 级 Info 日志未被触发"的场景(如高 V 日志的调用开销)。虽然这些优化并未全部实现,但结构体形态是确保它们未来可以实现的先决条件;所有真正的工作都藏在 LogSink 接口后面。
4. 常见实现:面向后端的生态
logr 本身是 API,真正写日志的是实现。原文档列出的实现(非穷举)包括:
- 函数实现(可桥接到非结构化库):funcr
- testing.T(用于 Go 测试,JSON 风格输出):testr
- github.com/google/glog:glogr
- k8s.io/klog(面向 Kubernetes):klogr
- testing.T(klog 风格文本输出):ktesting
- go.uber.org/zap:zapr
- log(Go 标准库日志器):stdr
- github.com/sirupsen/logrus:logrusr
- github.com/wojas/genericr:genericr(便于自行实现后端)
- logfmt(Heroku 风格):logfmtr
- github.com/rs/zerolog:zerologr
- github.com/go-kit/log:gokitlogr(自 v0.12.0 起兼容 go-kit/kit/log)
- bytes.Buffer(写入缓冲区):buflogr(适合测试时断言某些值确实被记录)
对 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 的底层抽象":
- 依赖:项目在 go.mod 中声明
github.com/go-logr/logr v1.4.3(间接依赖),由 k8s 生态组件透传引入; - 载体:所有插件与核心模块持有的是
klog.Logger(logr 兼容 logger),来源为klog.NewKlogr()(实现见 vendor/k8s.io/klog/v2/klogr.go),它把结构化键值合并后透传 klog 输出; - 典型调用:插件中大量使用
logger.V(n).Info(...)、logger.Error(err, "msg", ...)的结构化写法,对象引用统一用klog.KObj(pod)表达,例如 toomanyrestarts.go 与 removeduplicates.go; - 主循环日志: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); - 测试:单元测试通过
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)的上佳入口。