TraceID必须在Gin中间件开头通过c.Request.WithContext()注入context，优先用OpenTelemetry Extract解析traceparent，确保日志、span、Sentry、ELK中traceID与spanID一致；调试时需预设context并初始化OTel propagator。
TraceID 必须在 Gin 中间件里生成并注入 context
不是在 handler 里临时生成，也不是靠 logrus hook 单独塞字段——那样 traceID 无法被后续中间件、日志库、链路追踪 SDK（如 OpenTelemetry）一致读取。Gin 的 c.Request.Context() 是唯一可靠的上下文载体。
常见错误是只往 c.Set("trace_id", ...) 里存，但 c.Set 不影响 c.Request.Context()，导致下游日志或 span 创建时拿不到 traceID，最终日志和链路断开。
- 正确做法：用
c.Request.WithContext(context.WithValue(...))替换原始 request context - 必须在中间件开头就提取 header（
X-Trace-ID或traceparent），缺失时才生成新 UUID - 如果用了 OpenTelemetry，优先调用
otel.GetTextMapPropagator().Extract()解析 W3C traceparent，再tracer.Start()，否则会丢掉上游 span 上下文
logrus 日志中稳定输出 TraceID 的关键不是 Hook 而是 Field 绑定
很多方案用 logrus.Hook 每次请求注册一个新 hook，看似能写入 trace_id 字段，但实际隐患很大：hook 是全局注册的，多个请求并发时可能互相覆盖；且 hook Fire 执行时机晚于日志 entry 创建，字段可能没生效。
真正可靠的方式是把 traceID 作为 logrus Entry 的 field，在日志打点前就绑定好。
- 在中间件里获取 traceID 后，用
c.Set("logger_fields", logrus.Fields{"trace_id": traceID}) - 后续 handler 中通过
c.MustGet("logger_fields").(logrus.Fields)获取，并传给log.WithFields(...).Info(...) - 更推荐：封装一个
Logger(c *gin.Context) *logrus.Entry函数，统一从 context 提取 traceID 并返回带字段的 entry - 避免使用
logrus.AddHook()动态注册，尤其不要在每个 handler 里重复 Add
Gin + OpenTelemetry 场景下 traceID 和 spanID 必须同步透传
只保证日志有 traceID 不够，如果 spanID 没对齐，Sentry 或 ELK 里查到的日志和异常无法关联到同一 span，链路就断了。OpenTelemetry 的 SpanContext 包含 traceID、spanID、traceFlags 等，必须整体传播。
典型错误是中间件里只提取 X-Trace-ID，却忽略 traceparent 或 tracestate，导致子 span 的 parent 关系丢失，调用树扁平化。
- 务必用
propagation.HeaderCarrier(c.Request.Header)构造 carrier，交给otel.GetTextMapPropagator().Extract() - 调用
tracer.Start(propagatedCtx, "http-server")后，新 ctx 已含完整 span context，再用c.Request.WithContext(ctx)注入 - handler 里通过
trace.SpanFromContext(c.Request.Context())取 span，再调span.SpanContext().TraceID().String()获取 traceID —— 这个值才和日志、Sentry 里的完全一致 - 不要自己拼
fmt.Sprintf("%s-%s", traceID, spanID)，OpenTelemetry 的 traceID 是 16 字节十六进制字符串，直接用.String()即可
VSCode 调试启动时自动注入 TraceID 需绕过 Gin 默认中间件顺序
VSCode 的 launch.json 启动服务时，Gin 还没跑起来，没法靠 HTTP header 注入。想让本地调试日志也带 traceID，得在应用初始化阶段就设好默认 trace context，否则第一层中间件会生成新 ID，和后续远程调用不一致。
这不是加个环境变量就能解决的事，因为 Gin 的中间件链是运行时构建的，调试模式下必须提前干预。
- 在
main()开头，用context.WithValue(context.Background(), "default_trace_id", uuid.New().String())初始化一个调试专用 context - 自定义 Gin engine 时，重写
engine.HandleContext()或在第一个中间件里检查是否处于调试模式（比如os.Getenv("DEBUG_TRACE") == "true"） - 若检测到调试模式，跳过 header 提取逻辑，直接从预设 context 取 traceID，并创建 root span
- 注意：调试模式下的 traceID 不能写死，否则并发请求全撞同一个 ID；仍需每次请求生成新 UUID，只是不依赖 header
最易被忽略的是：调试时生成的 traceID 如果没同步注入到 OpenTelemetry 的 global tracer，Sentry 捕获的异常里就不会有 trace_id 字段，ELK 里也搜不到对应日志——这需要显式调用 otel.SetTextMapPropagator() 并确保 tracer 已初始化。
