Go slog.HandlerOptions 怎么按级别过滤调试日志

Go 使用 log/slog 记录结构化日志时，调试信息是否输出，关键看实际 handler 的 HandlerOptions.Level。它表示“最低记录级别”：设置为 slog.LevelInfo 后，Debug 会被丢弃，Info、Warn、Error 仍然保留；如果没有设置，内置 handler 默认按 Info 处理。

先把级别关系看清：Level 是最低门槛

slog.Level 本质上是表示严重程度的整数，数值越大，级别越高。内置的常用级别依次可以理解为 Debug、Info、Warn、Error。handler 判断一条记录的级别是否达到配置的最低级别，达到或超过才交给输出端。

因此，LevelInfo 不是“只输出 Info”，而是“Info 及以上都输出”。这也是生产环境通常从 Info 开始的原因：保留正常运行信号，同时压掉可能很密集的调试细节。

这个判断发生在 handler 一侧。日志调用仍然可以写成 logger.Debug，只是当它低于门槛时不会被处理；昂贵的参数计算则应配合 logger.Enabled 提前避免。

用 HandlerOptions.Level 固定过滤调试日志

如果服务启动后级别不会频繁改变，直接把 slog.LevelInfo 交给 HandlerOptions.Level 就够了。下面使用文本 handler，并把它设为默认 logger，便于同时覆盖顶层的 slog.Info、slog.Debug 等调用。

package main

import (
	"log/slog"
	"os"
)

func main() {
	// LevelInfo 是最低门槛，所以 Debug 被过滤，Info/Warn/Error 仍会输出。
	opts := &slog.HandlerOptions{Level: slog.LevelInfo}
	handler := slog.NewTextHandler(os.Stdout, opts)
	slog.SetDefault(slog.New(handler))

	// 这条记录低于 Info，不会进入 handler 的输出。
	slog.Debug("cache probe", "key", "user:42")
	// 这两条达到门槛，会输出为结构化文本。
	slog.Info("request accepted", "path", "/health")
	slog.Warn("cache miss", "key", "user:42")
}

如果改成 slog.NewJSONHandler，过滤语义不变，只是输出格式变成逐行 JSON。AddSource 和 ReplaceAttr 负责来源字段或属性改写，不会改变最低级别的判断。

临时排障用 LevelVar 动态打开 Debug

线上排查时，重启服务或重建一套 logger 往往会丢失现场。slog.LevelVar 实现了 Leveler，可以放进 HandlerOptions.Level；之后调用 Set 改变门槛，原 handler 就会读取新的级别。

package main

import (
	"log/slog"
	"os"
)

// programLevel 由 Info 起步，作为整个程序的动态最低级别。
var programLevel = new(slog.LevelVar)

func main() {
	// LevelVar 默认是 Info；handler 会在每条记录判断当前值。
	handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: programLevel,
	})
	logger := slog.New(handler)

	logger.Debug("before switch") // 默认被过滤。
	programLevel.Set(slog.LevelDebug)
	logger.Debug("during diagnosis") // 临时打开 Debug。
	programLevel.Set(slog.LevelInfo)
	logger.Debug("after switch") // 恢复生产门槛。
}

LevelVar 适合由配置刷新、管理接口或受控的诊断开关驱动。它支持多 goroutine 安全读写，但“能动态切换”不等于应该永久打开 Debug：生产环境仍需限制开启范围和持续时间，避免日志量、敏感属性和存储成本一起上升。

设置了级别却没生效，先查这四个对象

最常见的误判不是比较符写错，而是修改的配置没有连接到正在产生日志的对象。值班时可以按下面的顺序缩小范围：

1. 确认 logger 来源：调用的是 slog.Debug 顶层函数，还是某个通过 slog.New 创建的独立 logger。前者只受 slog.SetDefault 设置的默认 logger 影响。
2. 确认 handler 来源：传给 HandlerOptions 的是实际被 logger 持有的 handler，而不是初始化阶段留下的另一份配置。
3. 确认级别方向：想打开 Debug 要降低门槛到 LevelDebug；设置成 LevelError 会让输出更少，不会让 Debug 出现。
4. 确认问题类型：Level 只按记录级别过滤，不按消息文本、模块名或属性值过滤。需要按租户、请求或组件拆分时，应在 handler 或 logger 设计中另外处理。

还有一个性能细节：handler 的 Enabled 会在参数处理前被调用。对于昂贵的字符串拼接、序列化或诊断采样，可以先判断 logger.Enabled(ctx, slog.LevelDebug)，确认 Debug 当前开启后再计算参数。

上线前用一张清单确认回退路径

实际部署中，推荐让默认值保持 Info，把 Debug 作为短时、可审计、可回退的诊断能力。这样既能保留排障抓手，也不会把正常日志管道变成无边界的调试流。

相关问题

HandlerOptions.Level 不设置时会输出 Debug 吗？

不会。内置 TextHandler 和 JSONHandler 在 Level 为 nil 时按 Info 作为默认最低级别，因此 Debug 记录会被过滤。

把 Level 设置成 slog.LevelInfo 是只保留 Info 吗？

不是。它保留 Info、Warn 和 Error；如果只想保留 Error，应把最低级别设置为 slog.LevelError。

修改 LevelVar 后需要重新创建 logger 吗？

不需要。只要 handler 的 Level 引用了同一个 LevelVar，调用 Set 后后续记录就会使用新门槛。

为什么我打开了 Debug 仍然看不到日志？

先确认代码调用的 logger 是否使用了目标 handler，再确认是否通过 slog.SetDefault 绑定了默认 logger；独立 logger 不会自动跟随另一个 logger 的 handler。