Go runtime/trace.NewTask 如何给异步链路加标签：上下文传播与跟踪边界

异步订单处理最难查的，不是某个 goroutine 有没有启动，而是同一笔请求拆成多个 goroutine 后，哪一段真正拖慢了整体耗时。runtime/trace.NewTask 可以把这条业务链标成一个任务：用返回的 context.Context 继续传播关联关系，用 task.End 明确结束点，再用 trace.WithRegion 标记任务内部的阶段。

为什么普通日志看不出异步链路的完整耗时

假设 HandleOrder 收到请求后，同时启动库存检查和优惠计算，最后由 AssembleOrder 汇总结果。每个函数单独打日志，只能看到几个时间片；如果没有共同的任务边界，就很难判断它们是否属于同一笔订单，也看不清最后一个 goroutine 到底何时结束。

func HandleOrder(ctx context.Context) error {
	ctx, task := trace.NewTask(ctx, "HandleOrder")
	defer task.End()

	stockDone := make(chan error, 1)
	priceDone := make(chan error, 1)
	go func() {
		trace.WithRegion(ctx, "CheckStock", func() {
			stockDone 

这里的关键不是给每个 goroutine 再建一个任务，而是把同一个 context.Context 传进去。这样执行追踪器可以把 CheckStock、CalculatePrice 和 AssembleOrder 归到 HandleOrder 的业务任务下。

NewTask 返回的 context.Context 才是传播载体

NewTask 的第一个返回值是带任务信息的 context.Context，第二个返回值才是用于结束任务的 *trace.Task。实际编码时要同时保留两者：ctx 用于下游调用，task 用于生命周期收口。

如果下游函数收到的是旧的 ctx，代码仍然能正常运行，但这个阶段不会挂在刚创建的任务上。排查时可以先检查 NewTask 返回值是否覆盖了后续调用使用的变量。

task.End 应该放在真正的业务收口处

上面的示例把 defer task.End() 放在 HandleOrder 内，前提是 AssembleOrder 已经等待两个结果。若函数启动 goroutine 后立即返回，任务就会过早结束，追踪中的延迟只覆盖“提交异步工作”而不是“异步工作完成”。

ctx, task := trace.NewTask(ctx, "HandleOrder")

go func() {
	defer task.End()
	waitForWorkers(ctx)
	AssembleOrder(ctx)
}()

这种写法把结束点移到了汇总 goroutine，适合任务所有权确实已经转移的场景。不要让外层和汇总 goroutine 都把 task.End 当成自己的清理动作；虽然重复调用只取第一次结束时间，但代码读者会难以判断谁拥有任务。

用 go tool trace 验证任务和阶段是否出现

独立程序需要先用 trace.Start 写出 trace 文件，再在工作完成后调用 trace.Stop。测试和基准也可以直接使用 go test -trace=trace.out 生成文件。

go test -trace=trace.out ./...
go tool trace trace.out

打开追踪后，先确认 HandleOrder 任务的时间范围覆盖了预期的异步阶段，再观察 CheckStock、CalculatePrice 和 AssembleOrder 是否位于正确的任务上下文中。若只看到运行时调度事件，却没有这些业务标记，优先检查 ctx 传递和 trace.Start 是否覆盖了实际工作。

三个容易误判的边界

1. 任务类型要稳定。 NewTask 的 taskType 用于分类，别把订单号、用户 ID 这类无限增长的值直接拼进类型名；动态细节可以另行记录。
2. region 要在同一 goroutine 收尾。 用 trace.WithRegion 最省心；手动使用 region 时，开始和结束要遵循同一 goroutine 的嵌套关系。
3. trace 不是 CPU 热点分析替代品。 它更适合看调度、阻塞和跨 goroutine 的时间链路，热点 CPU 或内存问题仍应结合相应 profile 判断。

常见问题

NewTask 会自动让所有 goroutine 关联到同一任务吗？

不会。必须把 NewTask 返回的 context.Context 传给下游 goroutine；新 goroutine 若继续使用旧 ctx，就不会带上这个任务关系。

task.End 调用两次会怎样？

任务延迟统计只使用第一次调用的结束时间，但工程上仍应明确唯一的任务所有者，避免提前收口或重复清理。

每个阶段都要创建 NewTask 吗？

通常不需要。一次请求或一次订单用一个任务表达整体边界，内部阶段用 trace.WithRegion 标记即可；只有确实存在独立生命周期的子操作才考虑子任务。

为什么 trace 文件里有调度事件却看不到业务阶段？

常见原因是追踪没有覆盖工作区间，或者 region 和日志使用了没有经过 NewTask 的旧 context.Context。先检查启动范围和 ctx 变量传递。

把任务边界写成可复查的约定

给异步链路加标记时，可以固定一条小约定：入口创建一次 NewTask，返回的 context.Context 贯穿所有相关 goroutine，阶段用 trace.WithRegion，最后由明确的汇总点调用 task.End。这样追踪结果既能看到运行时调度，也能回到业务名称，不必靠多份时间戳日志猜测链路。