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。示例未执行,本文不提供虚构的终端输出或追踪截图。

旧日志代码应该怎样调整
如果旧代码已经用 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 文档。
-
502 收藏
-
502 收藏
-
501 收藏
-
501 收藏
-
501 收藏
-
177 收藏
-
Golang · Go问答 | 22分钟前 | 标准库 · Go问答 · Go Goroutine runtime/trace go tool trace Region.End StartRegion257 收藏
-
Golang · Go问答 | 27分钟前 | 标准库 · Go问答 · 问题排查 · Go defer bufio.Writer runtime/trace go tool trace trace.Stop 追踪文件481 收藏
-
143 收藏
-
494 收藏
-
291 收藏
-
Golang · Go问答 | 1小时前 | 错误处理 · Go问答 · Go io.Writer runtime/trace FlightRecorder maxBytes WriteTo 执行追踪479 收藏
-
187 收藏
-
411 收藏
-
341 收藏
-
429 收藏
-
Golang · Go问答 | 2小时前 | 标准库 · 性能排查 · Go问答 · Go Goroutine 调度 runtime.GOMAXPROCS 并行度 NumCPU NumGoroutine 逻辑CPU192 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习