OpenTelemetry Go 怎么配对 HTTP 客户端与服务端 Span

Go 服务调用另一个 HTTP 服务后，如果观测平台里出现两条互不相干的 Span，通常不是“按 URL 再匹配一次”就能解决。正确的关联依据是传播的 Trace Context：客户端创建 CLIENT Span，把上下文注入请求头；服务端从请求头提取上下文，再创建 SERVER Span。两端使用同一个 Trace ID，平台才能把一次跨服务请求还原成一条链路。

官方资料：https://opentelemetry.io/docs/languages/go/

otelhttp 包文档：https://pkg.go.dev/go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp

为什么客户端和服务端 Span 能配对

HTTP 语义约定把出站请求定义为客户端 Span，把入站请求定义为服务端 Span。真正连接它们的是 W3C Trace Context 一类的传播字段，而不是服务名、请求时间或路径字符串。客户端 Span 是一次出站操作，服务端 Span 是接收端操作；当服务端正确提取了上游上下文，它就会成为同一 Trace 中的下游 Span。

因此，看到两个 Span 并不等于已经配对。要重点看 Trace ID 是否相同、服务端 Span 是否为 SERVER、客户端 Span 是否为 CLIENT，以及请求头是否在代理或自定义 RoundTripper 中被保留。

Go 中应该在哪一层接入 instrumentation

常规 net/http 客户端可以用 otelhttp.Transport 包住底层 Transport，服务端则用 otelhttp.NewHandler 包住业务 Handler。这样注入和提取都发生在 HTTP 边界，业务函数只需要继续使用传入的 context.Context。

package main

import (
    "context"
    "net/http"

    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)

func client() *http.Client {
    // Transport 负责在出站请求头中注入当前 Trace Context，并创建 CLIENT Span。
    transport := otelhttp.NewTransport(http.DefaultTransport)
    return &http.Client{Transport: transport}
}

func server() http.Handler {
    business := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 使用提取后的请求上下文，让业务内新建的 Span 继续这条 Trace。
        ctx := r.Context()
        _ = ctx
        w.WriteHeader(http.StatusNoContent)
    })
    // Handler 负责提取上游上下文，并创建 SERVER Span。
    return otelhttp.NewHandler(business, "orders")
}

func request(ctx context.Context, client *http.Client, url string) error {
    // 把带有当前 Span 的 ctx 绑定到请求；不要重新使用 context.Background()。
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return err
    }
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    // 及时关闭响应体，避免连接复用和链路结束判断受到影响。
    defer resp.Body.Close()
    return nil
}

断链时先查这三处

第一处是上下文：调用 client.Do 时，请求应由当前业务 Span 的上下文创建，不能在中途换成新的背景上下文。第二处是传输层：如果自定义 RoundTripper 没有把 otelhttp.Transport 放在实际发送链路上，客户端可能只有手工 Span，没有自动注入。第三处是边界层：服务端要用包裹后的 Handler 接收请求，不能只在业务函数里另起一个没有父级的 Span。

如果中间经过反向代理，还要确认代理没有删除或改写传播头。跨进程传播只依赖请求头，服务名变化、端口变化本身不会让 Trace 断开；但错误的采样配置会让某一端没有记录可见 Span，这属于采样结果问题，不应误判为 HTTP 配对逻辑错误。

用最小判断表确认结果

结论可以压缩成一句话：先让客户端把上下文带出去，再让服务端在入口提取并沿用；不要用 URL、时间戳或服务名代替 Trace Context。这样即使请求经过代理、重试或多个 Go 服务，排查也有明确的证据链。

常见追问

只创建手工 Span，为什么还是看不到父子关系？

手工 Span 只存在于本地进程，跨进程还需要传播器把上下文写入请求，并由接收端提取。优先使用 otelhttp 这类官方生态 instrumentation，减少遗漏。

客户端和服务端 Span 名称必须完全相同吗？

不需要。关联的关键是 Trace Context 和正确的 SpanKind；名称、路由和地址属性用于检索与解释，应遵循 OpenTelemetry 的 HTTP 语义约定。