登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  Golang >  Go问答

Go runtime/trace.Log 为什么 trace.Log 的值不会替代业务日志

来源:17golang原创

时间:2026-11-19 23:17:19 228浏览 收藏

runtime/trace.Log 把 category 和 message 记成 Go 执行追踪中的一次性事件,供追踪分析使用。它不会因为函数名包含 Log 就向业务日志的输出器写入记录,也不会自动进入 slog 的 Handler 或日志采集平台。需要持续保留的业务事件,应继续由业务日志记录;trace.Log 用来补充追踪会话中的业务含义。

官方文档地址:https://pkg.go.dev/runtime/trace

假设你给任务处理函数加了一句 trace.Log,随后在标准错误或日志平台里搜索不到 message。我的排查顺序会先看它属于哪个输出通道,而不是先怀疑字符串格式。这里讨论的是两种记录能力的职责,不涉及某次版本升级,也不假设它们已经被项目自动打通。

名字相似,记录的对象不同

trace.Log 的参数是 context、category 和 message,作用是在执行追踪里放入带时间信息的标注。追踪同时提供调度、阻塞等运行时事件,业务标注可以帮助解释这些事件对应哪类工作。需要可分析的数据时,仍须由应用安排追踪采集及输出。

业务日志则由项目选用的日志组件处理。以标准库 slog 为例,Logger 产生记录,由 Handler 决定输出方式;项目还要自行安排采集、存储、检索和保留策略。给 trace.Log 传一个 message,并没有替你完成这些配置。

关注点trace.Log业务日志,以 slog 为例
主要用途为执行追踪增加业务标注记录应用事件、结果及结构化属性
输出归属追踪数据配置的 Handler
分类方式category 与 message级别、消息和属性等
关联方式可关联 context 中的 trace task需要显式属性或自定义 Handler 支持
业务事件分别与追踪标注和业务日志输出通道关联
结构说明图:追踪标注分组与业务日志分组各有输出归属;两者共享业务事件背景,但没有自动转发关系。

category 和 message 应该放什么

category 是少量稳定的事件类别,message 放具体说明。官方 API 假定系统只有少量不同类别,因此不宜把每个请求号都放进 category,造成类别随请求数量增长。比如 category 用 job,message 用公开的演示任务标识;详细结果字段继续交给业务日志。

context 如果来自 trace.NewTask,标注就能关联该任务。业务函数之间传递同一条派生 context,可以保留任务关系;随意换成 context.Background 会丢掉原先上下文携带的关联。这个关联也不会自动把 slog 日志的属性补齐。

trace.Log 不是一个返回格式化字符串的函数,也没有消息级别参数。需要格式化时可以使用 trace.Logf;但改用 Logf 仍然属于执行追踪标注,并没有切换到普通日志输出。本文不把追踪标注当作长期留存业务事实的唯一渠道。

最小示例:同一请求保留两种记录

下面的函数片段假定调用方已经安排追踪采集,并传入可用的 Logger。示例适用于提供 log/slog 的 Go 1.21 及以后工具链。它不包含完整服务启动程序,两个调用分别服务于不同读者。

package jobs

import (
    "context"
    "log/slog"
    "runtime/trace"
)

func RunJob(ctx context.Context, logger *slog.Logger, jobID string) {
    // 创建任务派生上下文,给后续追踪标注保留任务归属。
    taskCtx, task := trace.NewTask(ctx, "job")
    defer task.End()

    // category 保持稳定,具体关联值放在 message。
    trace.Log(taskCtx, "job", jobID)

    // 业务日志显式带上关联属性,由 Logger 的 Handler 决定输出。
    logger.InfoContext(taskCtx, "任务已接收", "job_id", jobID)
}

调用方应保证 ctx 和 logger 非 nil。示例只记录“已接收”,没有假称任务已完成;实际工作结束后,再在真实完成点记录结果。jobID 只是应用选定的关联值,它不会因为被传入 trace.Log 就变成 slog 属性,所以业务日志仍显式添加 job_id。

为观察业务日志,可由调用方配置一个明确输出到标准错误的 Logger:

package jobs

import (
    "log/slog"
    "os"
)

func NewLogger() *slog.Logger {
    // 明确选择文本输出;采集和留存策略由部署环境另外安排。
    return slog.New(slog.NewTextHandler(os.Stderr, nil))
}

这段配置只建立业务日志通道,不会启用执行追踪。反过来,启用追踪也不会替换这个 Handler。示例未执行,本文不提供虚构的终端输出或追踪截图。

任务上下文与追踪标注、业务关联属性的静态关系
结构说明图:追踪任务通过 taskCtx 关联 trace.Log;业务事件通过显式 job_id 属性关联日志记录。相同演示标识用于对应两类资料,不表示自动传播字段。

旧日志代码应该怎样调整

如果旧代码已经用 slog 记录了请求结果,不必为了加入追踪而把这些调用整体改成 trace.Log。更合适的增量做法是保留业务记录,只在需要解释调度或耗时背景的位置添加少量追踪标注;让类别稳定,消息简短,并选择能在两种资料里对应的非敏感业务标识。

排查“没有看到消息”时,先确认正在查看的是业务日志还是追踪数据。业务日志侧检查 Logger、Handler 和级别配置;追踪侧确认采集会话覆盖了事件发生的时段,并且已经妥善输出数据。不能因为业务日志里没有 message 就认定函数没有调用,也不能因为一次追踪里有标注就认定长期日志已经保存。

若项目确实需要统一封装,可在一个明确命名的业务函数内分别调用两种接口,保持字段策略一致。应清楚说明封装会产生两种输出;不要让读者误以为标准库提供了内置桥接。追踪数据也可能保存 message,因此避免把口令、令牌或完整私人请求放进去。

相关问题

给 InfoContext 传入 taskCtx,会自动写入 trace task ID 吗?

不应这样假定。日志记录需要的关联属性应显式添加,或者由项目实现并说明自定义 Handler 的处理规则。

category 可以用请求 ID 吗?

不适合作为默认设计。category 应保持少量稳定类别,请求 ID 可作为合适的关联值放在消息或业务日志属性中。

trace.Log 能表示一个代码段持续了多久吗?

它是一次性标注。执行追踪另有 region 等区间概念;不要把一个 message 本身当成开始与结束都完整的耗时记录。

参考资料:Go trace.Log 文档、Go slog 文档。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>