runtime/trace 是 Go 官方自带、零依赖、开箱即用的最轻量级追踪方案，仅需 trace.Start() 和 trace.Stop() 即可捕获调度、GC、系统调用等底层事件，并支持 trace.Log() 和 trace.Region() 打点，适用于单服务调试与 PoC 场景。
Go 项目里想快速加个轻量追踪，别碰 OpenTelemetry 全家桶——它适合生产级分布式链路，但对单服务、调试型或 PoC 场景来说太重，初始化错一步就静默失效。真要“快速”且“轻量”，runtime/trace 是 Go 官方自带、零依赖、开箱即用的唯一选择。
为什么 runtime/trace 是最轻的起点
它不依赖任何第三方包，也不需要配置 exporter、sampler 或 resource。只要调 trace.Start()，就能捕获 goroutine 调度、系统调用、GC、网络阻塞等底层运行时事件，还能手动打点标记业务逻辑。数据直接写进 io.Writer（比如文件或内存 buffer），导出后用 Go 自带的 go tool trace 可视化，整个流程不连 collector、不发网络、不占额外 goroutine。
- 启动快：几行代码就能跑起来，
go run main.go后立刻有 trace 文件 - 无传播负担：不涉及 context 透传、header 注入、跨服务关联，天然适合单体或本地调试
- 低干扰：采样粒度在 runtime 层，不影响业务逻辑结构，也不要求你改 handler 或 db 调用方式
- 但注意：它不生成 Span/TraceID，也不兼容 Jaeger/OTLP 等后端，纯属“本机行为快照”
三步启用 runtime/trace 并避免常见失败
很多人卡在第一步就失败，典型现象是 trace.Start() 返回 error 或后续 go tool trace 打不开文件。根本原因不是代码写错，而是时机和 writer 不匹配。
- 必须在
main()最早处调用trace.Start()，不能放在 goroutine 里，也不能晚于第一个用户 goroutine 启动 -
trace.Start()接收一个实现了io.Writer的对象，推荐用os.Create("trace.out")；别用bytes.Buffer——它没实现io.Seeker，go tool trace会报failed to read trace: invalid trace - 必须在程序退出前调
trace.Stop()，否则文件不完整；建议用defer trace.Stop()，但要确保它在main()函数内，且不在子 goroutine 中
怎么加业务标记让 trace 有用而不臃肿
纯 runtime 事件只能告诉你“goroutine 阻塞了 12ms”，但不知道这 12ms 发生在哪条请求路径里。这时候要用 trace.Log() 和 trace.Region() 插入语义标记，但别滥用。
-
trace.Log(ctx, "db", "query start")：适合记录离散事件，比如“开始查用户”“缓存 miss”，参数少、开销极低 -
trace.StartRegion(ctx, "http_handler")+region.End()：适合包裹一段同步执行逻辑，自动计算耗时；注意 region 必须成对，且不能跨 goroutine - 别在循环里高频打点：
trace.Log()虽轻量，但每秒上万次仍会拖慢 runtime；调试期可开，上线前删掉或用条件编译（//go:build debug）隔离 - ctx 来自
context.Background()即可，runtime/trace不依赖 OpenTelemetry 的 context 传播机制
真正容易被忽略的是：trace 文件不是实时可读的。你得先 trace.Stop() 关闭写入，再用 go tool trace trace.out 打开——中间任何一步中断（比如 panic 未被捕获、进程被 kill -9），文件就损坏。如果要做自动化采集，务必加 os.Interrupt 和 syscall.SIGTERM 信号处理来兜底 trace.Stop()。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
