Go runtime/trace 怎样给异步工作标记 task

用 trace.NewTask 创建逻辑任务，把返回的 context.Context 显式传入异步工作，再将 WithRegion 和 Log 绑定到该 Context。最后由明确的任务所有者在实际工作完成后调用 task.End()。仅在外层创建task，不能自动把所有goroutine里的标记归到它下面。

官方接口：https://pkg.go.dev/runtime/trace；标记实现与结束语义：https://go.dev/src/runtime/trace/annotation.go。

先分清任务、区域和日志的职责

假设一个预览批处理把可见项计数交给工作goroutine，调用方收到计数后再接收结果。需要描述的是一次完整逻辑操作，以及它在不同goroutine中的局部工作。

区域应在同一个goroutine内开始并结束；多个区域可以关联到同一任务。这里把task保存在 ctx，由它连接 工作goroutine 与 调用goroutine 中的标记。图中的分组是归属关系，不表示执行时间线。

把任务Context传到异步工作

下面代码保存为 main.go 后可用于小范围采集示例。它只计算固定的可见项，不访问外部系统；本文未执行这段示例，也不将图示当成采集结果。

package main

import (
    "context"
    "fmt"
    "os"
    "runtime/trace"
)

func processBatch(parent context.Context) {
    ctx, task := trace.NewTask(parent, "preview-batch")
    defer task.End() // 所有异步工作和结果处理完成后才标记结束。

    done := make(chan int, 1)
    go func(workCtx context.Context) {
        count := 0
        // 区域的开始和结束都位于这个工作goroutine。
        trace.WithRegion(workCtx, "count-visible", func() {
            flags := []bool{true, false, true, true}
            for _, visible := range flags {
                if visible {
                    count++
                }
            }
            trace.Log(workCtx, "stage", "counted")
        })
        done 

要关注的是传入工作函数的 workCtx 来源。它来自NewTask返回的ctx，而不是原来的parent，也不是新建的Background。前者带有当前任务的关联信息；后两者不能代替它关联这次新任务。

如果parent本身带有任务，再基于它NewTask会形成子任务关系。一个操作要共用同一task还是拆成子任务，应由业务粒度决定，不需要为每个函数都额外创建task。

由任务所有者决定结束时机

processBatch 持有结束责任：它先等待 done，再处理计数，函数退出时才执行 Task.End。负责同步的对象是通道，不是task。End是结束标记，不会等待goroutine，也不会取消工作。

本例涉及三个边界：“工作拥有者”包含 processBatch 和 Task.End；“工作通知”包含 工作goroutine 和 done；“采集资源”包含 trace.Stop 和 trace文件。processBatch接收done，工作goroutine发送done；processBatch拥有Task.End调用，trace.Stop属于采集收尾，trace文件承载采集数据。

真正的后台队列若在提交函数返回后继续执行，不能简单在提交函数里defer task.End；应把结束责任交给能确认任务完成的一方。请求Context的取消策略也要独立设计，不能为了保留trace关联就忽略原有取消语义。

控制标记内容与采集范围

任务类型和区域名用于分类，应保持为少量稳定名称。源码对此有明确提示，因此不要把订单号或每次变化的随机值拼入task类型。日志category也采用有限集合，消息只写必要、允许采集的信息。

trace.Log写入的是执行跟踪，不会自动进入应用的slog或标准日志。示例只记录阶段名和计数，没有写入完整请求、用户资料或凭据。关闭采集也不意味着所有标记调用都绝对无开销；不要把标记当作业务逻辑开关。

示例采集文件由run管理：创建成功后负责关闭，启动成功后负责Stop，业务工作在Stop之前完成。0600 是Unix权限请求，不能等同于所有平台上的统一访问控制；实际目录和文件保留策略仍应按部署环境管理。

查看工具官方说明：https://pkg.go.dev/cmd/trace。需要自行复现时，可使用以下命令；它们不是本文的运行记录。

# 在保存main.go的目录运行；已有async-task.trace时程序会拒绝覆盖。
go run main.go
# 由本机工具读取自己生成的trace文件。
go tool trace async-task.trace

检查采集结果时，重点看preview-batch是否包含预期区域与日志，以及任务结束是否覆盖业务完成。不要只因为文件存在，就推断每个异步步骤都已正确关联。采集范围应限定在需要诊断的工作窗口内。

常见问题

WithRegion里启动goroutine，能覆盖它的全部耗时吗？

不能这样推断。Region描述调用goroutine中的函数区间；异步函数需要自己的区域，整体关联由task Context承担。

task.End会取消Context吗？

不会。结束标记与取消、等待分别处理，示例通过done等待，不靠End控制工作。

为什么创建task后仍看不到关联日志？

先看采集是否覆盖工作时段，再看Log与WithRegion是否收到NewTask返回的ctx。只有创建task而丢弃返回的ctx，不能表达所需关联。