修复 Hertz + OpenTelemetry 链路追踪中的数据竞争问题

修复 Hertz + OpenTelemetry 链路追踪中的数据竞争问题

问题背景

在使用 CloudWeGo Hertz 框架配合 hertz-contrib/obs-opentelemetry 进行链路追踪时,当使用 WithShouldIgnore 选项时,会触发数据竞争警告:

vbscript 复制代码
HERTZ: Race detected.
Please be aware that the protocol.Request passed to handler is only valid before the handler returns.
DO NOT attempt to keep and access protocol.Request after the handler returns.

使用 Go 的 -race 检测器运行时,还会发现 DATA RACE 错误。

问题复现

复现代码

创建 main.go:

go 复制代码
package main

import (
    "context"
    "strings"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/obs-opentelemetry/provider"
    hertztracing "github.com/hertz-contrib/obs-opentelemetry/tracing"
)

func main() {
    p := provider.NewOpenTelemetryProvider(
        provider.WithServiceName("test-service"),
        provider.WithExportEndpoint("localhost:4317"),
        provider.WithInsecure(),
    )
    defer p.Shutdown(context.Background())

    // 使用 WithShouldIgnore 过滤健康检查等路径
    tracer, cfg := hertztracing.NewServerTracer(
        hertztracing.WithShouldIgnore(func(ctx context.Context, c *app.RequestContext) bool {
            return strings.HasPrefix(string(c.Path()), "/health")
        }),
    )

    h := server.Default(tracer, server.WithHostPorts("127.0.0.1:8080"))
    h.Use(hertztracing.ServerMiddleware(cfg))

    h.GET("/health", func(ctx context.Context, c *app.RequestContext) {
        c.String(200, "ok")
    })

    h.GET("/api/test", func(ctx context.Context, c *app.RequestContext) {
        c.String(200, "test")
    })

    h.Spin()
}

复现步骤

bash 复制代码
# 1. 使用 -race 标志运行
go run -race main.go

# 2. 发送请求
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/api/test

# 3. 观察控制台输出,会看到竞态警告

根因分析

经过调试,发现两个独立的问题:

问题 1: serverTracer.Start() 中的 shouldIgnore 调用

go 复制代码
// tracing/tracer_server.go - 原代码
func (s *serverTracer) Start(ctx context.Context, c *app.RequestContext) context.Context {
    if s.config.shouldIgnore(ctx, c) {  // <- 问题在这里
        return ctx
    }
    // ...
}

原因 :serverTracer.Start() 通过 server.WithTracer() 注册,它在请求解析之前就被调用。

此时:

  • 请求头和 body 可能还未完全解析
  • shouldIgnore 函数访问 c.Path() 等字段可能触发数据竞争

重要发现 :ServerMiddleware 中已经有相同的 shouldIgnore 检查,所以 Start() 中的检查是冗余的。

问题 2: span.End() 后访问 span 属性

go 复制代码
// tracing/tracer_server.go - 原代码
span.End(oteltrace.WithTimestamp(getEndTimeOrNow(ti)))

metricsAttributes := extractMetricsAttributesFromSpan(span)  // <- 数据竞争风险

原因 :span.End() 调用后,OpenTelemetry exporter 可能在另一个 goroutine 中开始处理这个 span。此时再访问 span 的属性会导致数据竞争。

修复方案

修复 1: 删除 Start() 中的 shouldIgnore 检查

go 复制代码
func (s *serverTracer) Start(ctx context.Context, c *app.RequestContext) context.Context {
    // NOTE: Do not call shouldIgnore here. At this point the request may not be
    // fully parsed yet, accessing RequestContext fields can cause data races.
    // The shouldIgnore check is performed in ServerMiddleware instead.
    tc := &internal.TraceCarrier{}
    tc.SetTracer(s.config.tracer)
    return internal.WithTraceCarrier(ctx, tc)
}

修复 2: 在 span.End() 之前提取 metrics 属性

go 复制代码
func (s *serverTracer) Finish(ctx context.Context, c *app.RequestContext) {
    // ... 省略前面的代码 ...

    // Extract metrics attributes before span.End() to avoid data race
    // with the exporter which may process the span in another goroutine.
    metricsAttributes := extractMetricsAttributesFromSpan(span)

    span.End(oteltrace.WithTimestamp(getEndTimeOrNow(ti)))

    s.counters[ServerRequestCount].Add(ctx, 1, metric.WithAttributes(metricsAttributes...))
    s.histogramRecorder[ServerLatency].Record(ctx, elapsedTime, metric.WithAttributes(metricsAttributes...))
}

完整 diff

diff 复制代码
diff --git a/tracing/tracer_server.go b/tracing/tracer_server.go
--- a/tracing/tracer_server.go
+++ b/tracing/tracer_server.go
@@ -76,9 +76,10 @@ func (s *serverTracer) createMeasures() {
 }

 func (s *serverTracer) Start(ctx context.Context, c *app.RequestContext) context.Context {
-	if s.config.shouldIgnore(ctx, c) {
-		return ctx
-	}
+	// NOTE: Do not call shouldIgnore here. At this point the request may not be
+	// fully parsed yet, accessing RequestContext fields can cause data races.
+	// The shouldIgnore check is performed in ServerMiddleware instead.
 	tc := &internal.TraceCarrier{}
 	tc.SetTracer(s.config.tracer)

@@ -135,10 +136,13 @@ func (s *serverTracer) Finish(ctx context.Context, c *app.RequestContext) {
 		recordErrorSpanWithStack(span, httpErr, panicMsg, panicStack)
 	}

+	// Extract metrics attributes before span.End() to avoid data race
+	// with the exporter which may process the span in another goroutine.
+	metricsAttributes := extractMetricsAttributesFromSpan(span)
+
 	span.End(oteltrace.WithTimestamp(getEndTimeOrNow(ti)))

-	metricsAttributes := extractMetricsAttributesFromSpan(span)
 	s.counters[ServerRequestCount].Add(ctx, 1, metric.WithAttributes(metricsAttributes...))
 	s.histogramRecorder[ServerLatency].Record(ctx, elapsedTime, metric.WithAttributes(metricsAttributes...))
 }

验证方法

bash 复制代码
# 在 tracing 目录下运行测试
cd tracing
go test -race ./...

# 应该看到类似输出:
# ok  	github.com/hertz-contrib/obs-opentelemetry/tracing	1.778s

修复后的执行流程

scss 复制代码
请求到达
    ↓
serverTracer.Start()        ← 仅创建 TraceCarrier,不访问请求数据
    ↓
请求解析完成
    ↓
ServerMiddleware            ← shouldIgnore 检查在这里进行
    ↓
c.Next(ctx)                 ← handler 执行
    ↓
handler 返回
    ↓
serverTracer.Finish()
    ↓
extractMetricsAttributes()  ← 在 span.End() 之前调用
    ↓
span.End()                  ← span 提交给 exporter

关键要点

  1. serverTracer.Start() 调用时机:在请求解析之前,此时访问 RequestContext 字段是不安全的
  2. shouldIgnore 检查位置 :应该在 ServerMiddleware 中进行,而不是在 Start() 中
  3. span.End() 后的数据竞争 :不要在 span.End() 之后访问 span 的任何属性

参考资料

相关链接

相关推荐
用户46043852250867 小时前
关于 Paimon-Rust 的写操作(细节)
后端
掘金酱8 小时前
AI 带来的新生意|稀土掘金 X-Lab 年度大会招募开启
前端·后端·vibecoding
nice_lcj5208 小时前
【从零理解计算机网络 · 02】分层模型:别背 OSI 七层,看数据怎么被“打包“和“拆包“
java·后端·tcp/ip·计算机网络·面试·osi·分层模型
SimonKing9 小时前
给Deepseek Harness装上插件市场,从此插件无忧
java·后端·程序员
利威尔xu10 小时前
Go Mutex 饥饿模式:正常模式等待者饿死,1ms 阈值自动切换崩溃
开发语言·后端·面试·golang·并发编程
一条Go10 小时前
边缘 Agent:为什么是它连出来,而不是平台连进去
后端·架构·github
huangfuyk11 小时前
前端融入/转后端避坑指南:AI 时代的安全边界、数据防线与实战细节
后端·ai编程
掘金者阿豪11 小时前
GitLab 服务器疑似遭入侵:从 502 故障到 Root 权限异常的完整排查复盘
后端
云起SAAS12 小时前
手机靓号选号商城H5源码 完整前后台可直接运行
前端·javascript·后端
the局外人12 小时前
Python 实战检索优化:BM25、向量与重排
数据库·后端·python