Go runtime/trace.NewTask 怎样跨 goroutine 跟踪一次逻辑操作

当一次请求先启动两个并行 goroutine，最后再汇总结果时，只在每个函数里单独写日志，往往只能看到几个分散的时间点，无法回答“这些工作是不是同一个逻辑操作”。Go 的 runtime/trace.NewTask 专门用来建立这层关联：它返回一个带任务信息的派生 Context 和一个 Task，把派生 Context 传给多个 goroutine，再用 trace.Log 或 trace.WithRegion 记录局部信息，最后在逻辑操作真正结束时调用 Task.End。

这篇只解决跨 goroutine 的任务关联，不把 NewTask 当作取消机制，也不展开 goroutine 阻塞定位。官方文档说明，任务可以覆盖多个 goroutine，执行追踪工具会按任务类型统计从创建到结束的延迟。

官方资料：https://pkg.go.dev/runtime/trace#NewTask

最小原则是：在逻辑操作入口创建一次任务，沿着调用边界传递返回的 Context，在最终完成点结束 Task；局部 Region 和 Log 都使用同一个派生 Context。

先看影响面：为什么分散日志很难还原一次操作

假设一个订单处理请求需要并行读取用户资料和库存，两个 goroutine 结束后才生成最终结果。没有任务关联时，trace 里虽然仍能看到 goroutine、调度、系统调用和自定义事件，但“用户资料读取”和“库存读取”属于哪一次订单处理，需要靠时间和调用栈猜测。

这就是本例的故障现场：每个阶段都有信息，整体却缺少一个共同的逻辑标识。根因不是 goroutine 数量多，而是观测数据没有共享任务上下文。NewTask 的作用是补上这个关联层；它不替代业务请求 ID，也不负责传递取消信号。

用 NewTask 创建跨 goroutine 的任务边界

trace.NewTask(parent, taskType) 接收父 Context，返回新的 Context 和 Task。新的 Context 携带任务信息，后续把它传给 trace.Log、trace.WithRegion 或下游函数，就能让这些注释附着到这个任务上。

下面的示例用两个 worker 表示并行阶段，汇总 goroutine 负责判断整个逻辑操作何时完成。示例中的 trace.out 是待由执行追踪工具读取的文件；图示和代码解释的是静态关系，不代表本文在本机执行过这段程序。

package main

import (
	"context"
	"log"
	"os"
	"runtime/trace"
	"sync"
)

func main() {
	// 追踪输出需要一个可写文件，并在退出前关闭它。
	f, err := os.Create("trace.out")
	if err != nil {
		log.Fatalf("创建 trace 文件失败: %v", err)
	}
	defer func() {
		if err := f.Close(); err != nil {
			log.Printf("关闭 trace 文件失败: %v", err)
		}
	}()

	// Start/Stop 包住需要观察的时间窗口；Start 失败时不要继续假装已采集。
	if err := trace.Start(f); err != nil {
		log.Fatalf("启动执行追踪失败: %v", err)
	}
	defer trace.Stop()

	ctx, task := trace.NewTask(context.Background(), "order-process")
	var wg sync.WaitGroup
	wg.Add(2)

	go func() {
		defer wg.Done()
		// 显式使用 NewTask 返回的 Context，避免丢失任务关联。
		trace.WithRegion(ctx, "load-profile", func() {
			trace.Log(ctx, "order", "profile-loaded")
		})
	}()
	go func() {
		defer wg.Done()
		// 两个 worker 可以并行，但仍属于同一个逻辑任务。
		trace.WithRegion(ctx, "load-inventory", func() {
			trace.Log(ctx, "order", "inventory-loaded")
		})
	}()

	// 只有两个阶段都结束，整个 order-process 才算完成。
	wg.Wait()
	task.End()
}

这里的关键不是把 ctx 设成全局变量，而是把它作为依赖显式传入。这样函数签名仍能表达调用边界，也不会把某个请求的任务信息意外泄露给另一个请求。

让 Region 和 Log 共享同一个任务上下文

任务本身只描述一段较高层的逻辑操作。真正帮助定位的是附着在任务上的局部观测：

• trace.WithRegion 记录一个 goroutine 内的时间区间，适合包住“读取资料”“调用库存服务”这类阶段。
• trace.Log 记录一次性事件，适合放订单号类别、阶段结果等少量上下文。
• 两者都要接收从 NewTask 返回的派生 Context，才能和任务建立关联。

Region 仍然受 goroutine 生命周期约束：一个 region 在哪个 goroutine 开始，就应在同一个 goroutine 结束；而 Task 是跨 goroutine 的更高层关联。不要因为任务可以跨 goroutine，就把一个 Region 的开始和结束拆到两个 goroutine。

在逻辑完成点调用 Task.End

Task.End 标记任务结束，执行追踪器会用任务创建到结束的时间计算该任务类型的延迟分布。它不是 context.Cancel，不会让 worker 停止；也不是 sync.WaitGroup.Done，不会替你等待并发工作。

因此结束位置应由业务语义决定。并行阶段全部成功、失败已经汇总，或请求已经进入最终返回路径时，才是合适的结束点。若把 task.End() 放进任意一个 worker 的 defer，另一个 worker 仍在运行时任务就可能提前结束；若完全忘记调用，任务延迟就没有完整终点。

如果结束动作只有一个明确的最终汇总函数，可以把它放在汇总函数的尾部；如果错误路径也要结束任务，就把结束动作放在能覆盖所有返回路径的位置，并避免重复设计多个不清晰的结束责任。

收集 trace 文件，再用 go tool trace 查看关联

独立程序可以使用 trace.Start 和 trace.Stop 采集一个时间窗口；测试和 benchmark 也可以使用 Go 测试工具的 trace 选项。采集完成后，把文件交给 go tool trace，在查看器中按任务、goroutine、Region 或 Log 观察关系。

# 让 Go 测试在指定文件中写入执行追踪。
go test -trace=trace.out ./...

# 使用 Go 自带工具打开已采集的追踪文件。
go tool trace trace.out

这里的两个命令是收集和打开的最小入口。执行追踪适合观察短时间窗口中的调度、系统调用、GC 与 goroutine 关系；它不是长期指标系统，也不应替代 CPU 或内存剖析来回答所有性能问题。

常见误区：任务关联解决什么，不能解决什么

总结与相关问题

跨 goroutine 跟踪一次逻辑操作时，先在入口调用 runtime/trace.NewTask，再把返回的 Context 传给各个 worker；局部阶段用 WithRegion，一次性信息用 Log，全部逻辑完成后由明确的汇总点调用 Task.End。最后用 trace.Start/Stop 形成文件，再交给 go tool trace 观察。

相关问题：

• NewTask 返回的 Context 可以直接替换原来的请求 Context 吗？
• 一个 Task 可以关联多个 goroutine 吗？可以，任务就是为更高层的跨 goroutine 逻辑操作设计的。
• Region 能跨 goroutine 结束吗？不能，Region 的开始和结束应位于同一个 goroutine。
• Task.End 能替代 context 的取消吗？不能，它只标记追踪任务的结束。