服务注册与分布式协调 / 系统课时
接入 OpenTelemetry 分布式追踪
接入 OpenTelemetry 分布式追踪
这一课把 Temporal 的 Client、Workflow、Activity 与下游 HTTP Span 串成同一条 Trace,并建立一套判断方法:先看编排动作何时发生,再看 Activity 何时真正执行,最后把延迟归因到排队、重试还是外部依赖。
学习目标
- 为 Temporal Go Client 和 Worker 接入 OpenTelemetry tracing interceptor。
- 让 Activity 的下游 HTTP 调用继承同一 Trace 上下文。
- 根据 Span 与 Temporal 时间点区分编排等待和真实执行耗时。
先明确要串起来的链路
Temporal 的调用链不是普通的同步 RPC。Client 发起 Workflow 后,执行可能跨 Worker、跨进程、跨很长时间;Workflow 再调度 Activity,Activity 才真正访问 HTTP、数据库或消息系统。因此关键不是“给每个函数包一个 Span”,而是让 Trace Context 经 Temporal Header 跨越这些边界。

当前常用的 Go SDK 集成位于 go.temporal.io/sdk/contrib/opentelemetry。它通过 interceptor 在 Client、Workflow 与 Activity 边界创建并传播 Span;Activity 使用普通 context.Context,因此后续被 OpenTelemetry 自动埋点的 HTTP、gRPC 或数据库客户端可以自然继承当前 Span。
接入拦截器并验证父子链路
下面示例要求本机已有可访问的 Temporal Server,默认地址为 localhost:7233。示例使用 stdout exporter,避免额外依赖 Collector;它同时启动 Worker、执行一个 Workflow,并让 Activity 调用本地 HTTP 服务。
package main
import (
"context"
"fmt"
"log"
"net/http"
"net/http/httptest"
"time"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
temporalotel "go.temporal.io/sdk/contrib/opentelemetry"
"go.temporal.io/sdk/client"
"go.temporal.io/sdk/worker"
"go.temporal.io/sdk/workflow"
)
const taskQueue = "otel-demo"
func OrderWorkflow(ctx workflow.Context, url string) (string, error) {
ctx = workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
StartToCloseTimeout: 10 * time.Second,
})
var result string
err := workflow.ExecuteActivity(ctx, CallDownstream, url).Get(ctx, &result)
return result, err
}
func CallDownstream(ctx context.Context, url string) (string, error) {
httpClient := &http.Client{
Transport: otelhttp.NewTransport(http.DefaultTransport),
}
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
return "", err
}
resp, err := httpClient.Do(req)
if err != nil {
return "", err
}
defer resp.Body.Close()
return resp.Status, nil
}
func main() {
ctx := context.Background()
exporter, err := stdouttrace.New(stdouttrace.WithPrettyPrint())
if err != nil {
log.Fatal(err)
}
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
defer func() { _ = tp.Shutdown(ctx) }()
otel.SetTracerProvider(tp)
tracingInterceptor, err := temporalotel.NewTracingInterceptor(
temporalotel.TracerOptions{},
)
if err != nil {
log.Fatal(err)
}
options := client.Options{}
options.Interceptors = append(options.Interceptors, tracingInterceptor)
c, err := client.Dial(options)
if err != nil {
log.Fatal(err)
}
defer c.Close()
w := worker.New(c, taskQueue, worker.Options{})
w.RegisterWorkflow(OrderWorkflow)
w.RegisterActivity(CallDownstream)
if err := w.Start(); err != nil {
log.Fatal(err)
}
defer w.Stop()
downstream := httptest.NewServer(
otelhttp.NewHandler(
http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(http.StatusNoContent)
}),
"downstream",
),
)
defer downstream.Close()
run, err := c.ExecuteWorkflow(ctx, client.StartWorkflowOptions{
ID: fmt.Sprintf("otel-order-%d", time.Now().UnixNano()),
TaskQueue: taskQueue,
}, OrderWorkflow, downstream.URL)
if err != nil {
log.Fatal(err)
}
var result string
if err := run.Get(ctx, &result); err != nil {
log.Fatal(err)
}
if err := tp.ForceFlush(ctx); err != nil {
log.Fatal(err)
}
fmt.Println("workflow result:", result)
}预期输出中会先出现 stdout exporter 产生的多段 Span JSON;Trace ID、Span ID、时间戳和内部字段属于动态值。最后的业务结果应为:
workflow result: 204 No Content检查 Trace 时不要只数 Span 数量,而要确认 Temporal 产生的 Workflow/Activity Span 与 otelhttp 产生的 HTTP Client/Server Span 共享同一条 Trace,并且父子关系连续。具体 Span 名称可能随 SDK 或 OpenTelemetry instrumentation 版本变化,不应把名称文本写死成告警条件。
区分编排等待与真实执行
定位“Workflow 看起来很慢”时,至少比较三个时间区间。第一段是 Workflow 决定调度 Activity 到 Activity 真正开始之间的等待,常见原因包括 Task Queue backlog、Worker 不可用或并发槽不足;第二段是 Activity 的实际运行时间;第三段是 Activity 内部下游 Span 的时间。
如果 Activity Span 很短,但从调度到开始存在明显空档,应优先检查 Worker poller、Task Queue backlog 和并发限制,而不是优化 Activity 代码。反过来,如果 Activity 本身很长且下游 HTTP/DB Span 占据大部分时间,瓶颈已经离开编排层,应继续沿 Trace 下钻依赖。
生产化时守住边界
生产环境通常把 exporter 换成 OTLP,经 Collector 统一做采样、脱敏和后端路由。Temporal 自身的 Workflow ID、Run ID 很适合用于日志与 Trace 检索,但它们通常是高基数字段,不应直接变成指标标签。
Workflow 代码还受确定性与 Replay 约束。优先依赖 Temporal 官方 tracing interceptor 自动生成编排 Span,不要在 Workflow 中随意调用普通 OpenTelemetry API 创建依赖墙钟时间或随机值的自定义 Span。Go SDK 还提供新的 OpenTelemetry v2 集成,但其 API 处于实验阶段;生产迁移前应核对当前版本兼容性与历史 Replay 影响。
最终验收标准不是“后端里出现了 Span”,而是从一次 Client 请求能够沿同一 Trace 定位到 Workflow、Activity 和真实下游调用,并能用等待空档与 Activity 内部耗时把编排问题和执行问题分开。