Golang链路追踪实现方法与技巧

opentelemetry-go 是 Go 链路追踪最稳妥选择，需用 otel.Tracer 和 context.Context 传递 span，HTTP 用 otelhttp 插件，DB 用 otelsql.Register 注册驱动，属性设置须避免高基数字段。

Go 里用 opentelemetry-go 做链路追踪是当前最稳妥的选择

Go 官方生态没有内置分布式追踪标准，opentelemetry-go 是目前事实上的标准实现，它兼容 OpenTracing 和 OpenCensus 的语义，同时被主流后端系统（Jaeger、Zipkin、Datadog、New Relic）原生支持。别再用已归档的 opentracing-go 或维护停滞的 go-opencensus，它们要么停止更新，要么缺少上下文传播的健壮实现。

关键点在于：必须用 otel.Tracer 替代自定义 tracer，且所有 span 必须通过 context.Context 传递——这是跨 goroutine 和 HTTP 边界传播 traceID 的唯一可靠方式。

• otel.Tracer("my-service") 返回的 tracer 是线程安全的，可全局复用
• 每个 HTTP handler、DB 查询、RPC 调用都应从入参 ctx context.Context 中提取 parent span，并创建 child span
• 切勿在 goroutine 中直接用 context.Background() 启动 span，会丢失父子关系

HTTP 请求自动注入/提取 trace context 的正确写法

Go 的 net/http 不自动处理 tracing header，必须手动在 middleware 中完成 inject/extract。OpenTelemetry 提供了 httptrace 和 propagation 模块，但真正起作用的是 otelhttp 这个官方插件包——它封装了完整的 client/server 端 header 读写逻辑。

常见错误是自己手写 req.Header.Set("traceparent", ...)，这会漏掉 tracestate，导致多 vendor 场景下上下文丢失；或在 extract 时没调用 otel.GetTextMapPropagator().Extract()，导致 span.parent 为 nil。

• server 端：用 otelhttp.NewHandler(http.HandlerFunc(...), "api") 包裹 handler
• client 端：用 otelhttp.NewClient(&http.Client{}) 替代原始 http.Client
• 若需自定义 propagation（如只传 traceparent），需显式配置 otel.SetTextMapPropagator(propagation.TraceContext{})

数据库查询埋点必须用 driver wrapper，不能只 wrap sql.DB

单纯给 sql.DB 加一层 wrapper（比如用 otelsql.Open）只覆盖了 Query/Exec 等顶层方法，但无法捕获 sql.Tx 内部的 Stmt.Exec、预编译语句、或 Rows.Scan 阶段的延迟——这些都会造成 span 断裂或 duration 不准。

真正有效的做法是使用 otelsql.InjectDriver 注册带 tracing 的 driver，让所有底层连接操作都被拦截。例如 PostgreSQL 要用 github.com/jackc/pgx/v5/pgxpool + otelsql.Register，MySQL 要用 github.com/go-sql-driver/mysql + otelsql.Register，且必须在 init() 中完成注册，早于任何 sql.Open 调用。

• 错误示范：db, _ := sql.Open("mysql", dsn); db = otelsql.Wrap(db) —— 只覆盖部分路径
• 正确做法：otelsql.Register("mysql", &mysql.MySQLDriver{})，然后 sql.Open("mysql", dsn)
• 注意：driver name 必须和 sql.Open(driverName, ...) 中第一个参数完全一致

Span 属性设置要克制，避免高基数 label 拖垮后端存储

很多团队习惯把 user_id、request_id、甚至完整 query string 当作 span attribute 打进去，结果在 Jaeger 或 Tempo 中查半天加载不出 trace——因为后端按 label 建索引，高基数字段（如每请求都不同的值）会让索引爆炸。

OpenTelemetry 明确建议：只将低基数、有分析价值的字段设为 attribute，比如 http.method、http.status_code、db.system；高基数或敏感字段（如 email、token、完整 body）应作为 span.Event 记录，或干脆不采集。

• 推荐保留的 attribute：http.route（如 /api/v1/users/{id}）、db.statement（仅含占位符，如 SELECT * FROM users WHERE id = ?）
• 禁止写入的 attribute：http.url（含 query 参数）、user.email、request.body
• 调试用 event 示例：span.AddEvent("user_login_success", trace.WithAttributes(attribute.String("user_id", uid)))

func handleUserGet(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    span := trace.SpanFromContext(ctx)
    // ✅ 正确：低基数 route
    span.SetAttributes(attribute.String("http.route", "/api/v1/users/:id"))
    // ❌ 错误：高基数 url（含 /users/1234567890）
    // span.SetAttributes(attribute.String("http.url", r.URL.String()))
}

跨服务调用时，trace context 的传播比 span 数据本身更重要；一旦 context 断了，再精细的 attribute 也串不成完整链路。