Go runtime/trace.NewTask 怎样给跨函数工作流标记任务边界

当一个请求经过入口函数、任务编排函数，最后又拆成多个 goroutine 时，只在入口处打印一条日志，通常很难知道这些执行片段是否属于同一件事。Go 的 runtime/trace.NewTask 可以为这类逻辑操作建立一个 task：它返回一个携带 task 的新 context.Context，后续使用这个 context 写入的日志和 region 都能关联到该 task。

官方文档：https://pkg.go.dev/runtime/trace#NewTask

关键做法是：用返回的 ctx 继续传递任务，用 task.End() 标记真正的完成点。NewTask 不是普通的耗时计时器，也不是 pprof 的替代品；它服务的是执行追踪中的“这几段工作属于同一个逻辑操作吗”。

先分清 task、region 和 log 的职责

runtime/trace 的用户标注可以分成三层。Log 记录一次带类别和消息的事件；region 表示某个 goroutine 内的一段时间区间；task 则表示一个可能需要多个 goroutine 协作的更高层逻辑操作。

因此，订单编排、一次 HTTP 请求的内部处理、一个批次的异步导入，都可以考虑用 task 表示。具体的数据库调用或单个解析阶段，则更适合继续用 region 描述。

从父 context 创建任务上下文

NewTask 的第一个参数是父 context，第二个参数是 taskType。返回值有两个：新的 context 和任务句柄。新的 context 不是原 context 的修改版，而是一个携带 task 关联信息的派生 context；后续函数必须接收并使用这个返回值。

package main

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

func handleRequest(parent context.Context, requestID string) {
    // 新 ctx 才携带当前逻辑任务，后续函数不要继续使用 parent。
    ctx, task := trace.NewTask(parent, "request-workflow")
    defer task.End()

    // 这里传递的是携带 task 的 ctx，日志和 region 才能归到该任务。
    loadProfile(ctx, requestID)
}

func loadProfile(ctx context.Context, requestID string) {
    // 业务函数继续接收 ctx，而不是重新从 context.Background() 开始。
    trace.Log(ctx, "request", requestID)
}

上例把 End 放在入口函数的 defer 中，适用于“入口函数返回就代表工作全部结束”的简单流程。若入口函数只是启动后台分支，不能直接照搬这个位置，否则 task 会在后台工作完成前提前关闭。

让多个函数和 goroutine 共用同一个 task

NewTask 真正有价值的地方，是把返回的 ctx 交给多个工作分支。每个分支可以用 trace.Log 写事件，也可以用 trace.WithRegion 标记本 goroutine 内的步骤。它们不需要共享一个可变的“当前任务”全局变量。

func runWorkflow(parent context.Context, jobID string) error {
    ctx, task := trace.NewTask(parent, "import-workflow")

    var wg sync.WaitGroup
    wg.Add(2)

    go func() {
        defer wg.Done()
        // 同一个 ctx 让准备阶段归属于 import-workflow。
        trace.WithRegion(ctx, "prepare", func() {
            trace.Log(ctx, "job", jobID)
            prepareInput(ctx, jobID)
        })
    }()

    go func() {
        defer wg.Done()
        // 另一个 goroutine 也使用同一个 ctx，形成同一任务下的并行分支。
        trace.WithRegion(ctx, "consume", func() {
            consumeInput(ctx, jobID)
        })
    }()

    wg.Wait()
    // 只有两个分支都完成后，任务边界才真正闭合。
    task.End()
    return nil
}

这段代码的重点不在 WaitGroup 本身，而在 ctx 的来源始终只有一个。若某个分支误用 context.Background()，它仍然可能执行成功，但该分支发出的 Log 或 region 就失去了当前 task 的关联。

把 End 放在真正的完成点

执行追踪会把 task 延迟理解为从创建 task 到调用 End 的时间。End 过早，记录到的只是“调度工作”的时长；End 过晚，多个独立操作可能被错误地揉成一个任务。跨 goroutine 场景通常应把 End 放到等待所有必要工作完成的汇合点。

func runAsync(parent context.Context, id string) {
    ctx, task := trace.NewTask(parent, "async-job")

    done := make(chan struct{})
    go func() {
        defer close(done)
        // 这里的 region 属于 ctx 携带的 async-job task。
        trace.WithRegion(ctx, "worker", func() {
            doWork(ctx, id)
        })
    }()

    <-done
    // 等后台工作完成后再 End，任务的结束点才与业务语义一致。
    task.End()
}

Task.End 可以安全地作为收尾动作调用；官方文档说明，多次调用时只有第一次调用参与延迟测量。不过工程上仍应把所有权设计清楚，尽量让一个负责汇合的函数调用一次，避免读代码的人无法判断任务何时结束。

嵌套任务和 taskType 怎么取

如果传入的父 context 本身已经携带 task，NewTask 创建的就是子 task。这个关系适合表达“请求任务”包含“批处理子任务”这样的层级。子任务仍然使用自己的返回 ctx，不能把父 ctx 和子 ctx 混用。

func runChild(parent context.Context, batchID string) {
    // 子 task 继承父 task 的上下文关系，便于在追踪中观察层级。
    ctx, child := trace.NewTask(parent, "batch-child")
    defer child.End()

    trace.Log(ctx, "batch", batchID)
    processBatch(ctx, batchID)
}

taskType 用来对 task 分类，应该使用有限且稳定的类别，例如 request-workflow、import-workflow。不要把用户 ID、订单号或随机字符串拼进 taskType；这些动态值应放到 trace.Log 的消息中。类别过多会让追踪分析失去聚合意义。

最容易踩到的四个边界

1. 只创建，不传播：调用了 NewTask，却把旧 ctx 传给下游，结果 task 下没有预期的日志和 region。
2. 入口提前 End：入口只负责投递 goroutine，却在返回前或返回时结束任务，导致后台工作被排除在任务延迟之外。
3. 把 task 当计时器：task 的价值是执行追踪中的逻辑归属；需要业务指标时，仍应使用独立的计时和指标系统。
4. 用动态字符串当 taskType：把每个请求都变成一个新类别，不利于按类型观察延迟分布；动态标识放进 Log 更合适。

结论：用一条 ctx 贯穿，用一个完成点收口

为跨函数工作流建立任务边界，可以按这条路径落地：从父 context 调用 trace.NewTask，把返回的 ctx 传到所有相关函数和 goroutine，在这些分支中使用 Log 或 WithRegion 做细节标注，最后等真正的工作汇合后调用 task.End()。

如果任务只在一个 goroutine 内执行，region 往往已经足够；当逻辑操作需要多个 goroutine 协作，或者需要在追踪中看到一组工作属于同一请求时，NewTask 才能把这条链路组织起来。

相关问题

• NewTask 返回的 ctx 能否替换父 ctx？可以作为后续任务链路的 ctx 传递，但不要修改或复用 context 的值语义来保存可变状态。
• task.End 应该由哪个 goroutine 调用？由能确认所有必要工作已经完成的收口逻辑调用，示例中通常是等待分支结束的 goroutine。
• region 和 task 能同时使用吗？可以。region 描述单个 goroutine 的局部步骤，传入携带 task 的 ctx 后会关联到该 task。
• 如何把一次任务写入 trace 文件？需要在程序中用 trace.Start 开启追踪、用 trace.Stop 收尾，再使用 Go 的 trace 工具分析生成的文件。