用 slog HandlerOptions 为错误日志补充调用位置

最直接的做法，是在创建 JSONHandler 或 TextHandler 时传入 &slog.HandlerOptions{AddSource: true}。内置 Handler 会为日志增加 source 属性；JSON 输出包含函数名、文件和行号，文本输出则表现为 FILE:LINE。如果只想保留错误日志，可以同时把 Level 设为 slog.LevelError。

但有一个重要边界：AddSource 是 Handler 级别的开关，不会自动判断“只有 Error 才加位置”。把 LevelError 和 AddSource 放在同一个错误专用 Handler 上，才是最简单、可控的组合。

目标和边界：先决定哪些日志需要 source

我在本地调试时习惯给所有日志打开调用位置，上线后却发现每条 Info 都携带文件路径，既增加日志体积，也让常规查询显得很嘈杂。后来更实用的策略是把错误流单独定义：Error 及更高级别包含 source，普通业务流水保持精简。

全流程总览：调用位置从哪里进入日志

Logger 创建日志记录时会保存调用位置 PC。内置 Handler 在 AddSource 打开且 source 可用时，把它转换成 slog.Source，再以固定键 source 输出。slog.Source 包含 Function、File 和从 1 开始计数的 Line。

这里有两个常见误解。第一，AddSource 并不是把当前 goroutine 的完整调用栈写入日志，它只补充一个调用位置。第二，ReplaceAttr 只能改写准备输出的 source，不能修复 Record 里已经记录错误的 PC；包装函数问题需要在创建 Record 时解决。

阶段一：创建错误专用 Handler

下面是一个可以直接运行的 JSON 日志示例。LevelError 让该 Handler 只接收 Error 及以上级别，AddSource 负责增加调用位置。

package main

import (
    "errors"
    "log/slog"
    "os"
)

func main() {
    // 错误专用 Handler：过滤低级别记录，并补充调用位置
    opts := &slog.HandlerOptions{
        Level:     slog.LevelError,
        AddSource: true,
    }
    logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))

    // 这条 Info 低于 LevelError，不会由当前 Handler 输出
    logger.Info("service ready", slog.String("service", "billing"))

    // Error 会携带 source、错误内容和业务字段
    logger.Error(
        "charge failed",
        slog.Any("err", errors.New("gateway timeout")),
        slog.String("order_id", "o-42"),
    )
}

输出结构类似下面这样，实际函数名、路径和行号以项目为准：

{"time":"...","level":"ERROR","source":{"function":"main.main","file":"/work/app/main.go","line":24},"msg":"charge failed","err":"gateway timeout","order_id":"o-42"}

如果换成 TextHandler，source 会写成 /work/app/main.go:24。两种格式的语义相同，只是 JSON 更适合日志平台按 source.file、source.line 建立字段索引。

阶段二：用 ReplaceAttr 缩短文件路径

容器构建路径或 CI 工作目录往往很长，直接输出绝对路径会占用不少空间。HandlerOptions.ReplaceAttr 会收到包括 source 在内的内置属性，因此可以只保留文件名，或者裁剪成仓库相对路径。

package logging

import (
    "log/slog"
    "path/filepath"
)

func ErrorOptions() *slog.HandlerOptions {
    return &slog.HandlerOptions{
        Level:     slog.LevelError,
        AddSource: true,
        ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
            // source 是内置属性，值类型为 *slog.Source
            if a.Key == slog.SourceKey {
                source, ok := a.Value.Any().(*slog.Source)
                if ok {
                    // 复制一份，避免直接修改可能被共享的 Source 值
                    trimmed := *source
                    trimmed.File = filepath.Base(trimmed.File)
                    return slog.Any(slog.SourceKey, &trimmed)
                }
            }
            return a
        },
    }
}

这段代码仍保留函数名和行号，只把 /work/app/internal/payment/service.go 缩短为 service.go。如果仓库里有多个同名文件，建议保留最后两到三层目录，而不是只留 basename。

阶段三：验证直接调用的文件与行号

不要用肉眼看一次日志就结束。调用位置最容易在重构、增加封装层或切换 Handler 时回退。一个实用测试是把 JSON 写进缓冲区，解析 source 后断言文件名和行号范围。

func TestErrorContainsSource(t *testing.T) {
    var buf bytes.Buffer

    // 使用与生产一致的 AddSource 配置
    logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{
        Level:     slog.LevelError,
        AddSource: true,
    }))

    // 记录本行附近的错误，后面验证 source 是否存在且可用
    logger.Error("write failed", slog.String("object", "invoice"))

    // 解析 JSON，避免依赖字段顺序和时间内容
    var record struct {
        Source struct {
            Function string `json:"function"`
            File     string `json:"file"`
            Line     int    `json:"line"`
        } `json:"source"`
    }
    if err := json.Unmarshal(buf.Bytes(), &record); err != nil {
        t.Fatalf("解析日志失败: %v", err)
    }
    if record.Source.File == "" || record.Source.Line 

测试不必把行号写死，因为插入代码会导致脆弱失败。若必须检查准确调用点，可以在调用前通过 runtime.Caller 记录期望行号，再允许一个明确的小偏移。

阶段四：封装函数为什么会把位置指向包装层

很多项目会封装 Errorf、ErrorContext 或统一错误码函数。若包装函数内部直接调用 logger.Error，slog 看到的调用者就是包装函数，source 自然指向日志工具文件，而不是业务文件。

修复方法是显式取得调用方 PC，用它创建 slog.Record，再交给原 Handler。下面示例只有一层包装，因此 runtime.Callers 的 skip 为 2：跳过 runtime.Callers 自身和 Errorf。

package logging

import (
    "context"
    "fmt"
    "log/slog"
    "runtime"
    "time"
)

func Errorf(ctx context.Context, logger *slog.Logger, format string, args ...any) {
    // 先检查级别，避免在日志被过滤时仍格式化消息和查找调用栈
    if !logger.Enabled(ctx, slog.LevelError) {
        return
    }

    // 跳过 Callers 和当前包装函数，取得业务调用点 PC
    var pcs [1]uintptr
    runtime.Callers(2, pcs[:])

    // 使用业务调用点创建 Record，AddSource 会据此生成 source
    record := slog.NewRecord(
        time.Now(),
        slog.LevelError,
        fmt.Sprintf(format, args...),
        pcs[0],
    )

    // 直接交给 Handler，错误由调用方的日志策略统一处理
    _ = logger.Handler().Handle(ctx, record)
}

如果包装层不止一层，固定的 skip 可能再次失准。此时应统一入口数量，或通过 runtime.CallersFrames 跳过日志包自身的帧，找到第一个业务包帧。无论选哪种方式，都要用测试锁定 source，而不是靠经验调整数字。

推荐流程

1. 先确认错误日志是独立输出，还是与普通日志共用一个 Handler。
2. 独立错误流使用 LevelError + AddSource；共用流则评估是否接受所有级别都带 source。
3. 通过 ReplaceAttr 统一路径格式，保留函数名和行号。
4. 直接调用先写结构测试，确认 JSON 或文本格式符合日志平台字段约定。
5. 若存在日志包装函数，改用 runtime.Callers + slog.NewRecord 传递业务调用点。
6. 上线前比较日志体积与处理开销，并确认告警查询没有依赖旧字段结构。

常见误区

• 误以为 AddSource 只影响 Error：它影响当前 Handler 接收的所有记录；是否只接收 Error 由 Level 或路由策略决定。
• 在 ReplaceAttr 中猜行号：ReplaceAttr 适合改写路径和键名，不适合修复错误的调用 PC。
• 包装 logger.Error 后不做测试：source 很可能稳定地指向包装函数，看似有位置，实际没有定位价值。
• 直接删除完整路径：多个包可能有同名文件，至少保留足够目录层级来区分。
• 忽略开销：调用位置需要额外栈信息处理；在高吞吐日志路径中应按需启用并做基准测试。

速查表

这套配置的重点不是“让日志更详细”，而是让错误日志能直接回到有效的业务调用点。先用 HandlerOptions 打开 source，再把路径、级别和包装层逐项收紧，最终得到的信息才既可定位，又不会让日志系统背负多余成本。

参考资料

• Go 标准库 log/slog 文档
• Go 官方博客：Structured Logging with slog