Consul不直接提供OpenTelemetry配置，需在Gin启动前从Consul同步读取otel_exporter_jaeger_endpoint、otel_service_name、otel_sampler_ratio等参数，构造结构体后传入NewTracerProvider初始化，并显式注入otelgin.Middleware；服务名须与中间件参数严格一致，采样率不支持运行时热更新。
Consul配置项如何映射到OpenTelemetry初始化参数
Consul本身不直接提供OpenTelemetry配置，它只负责存储和分发键值对（KV）或服务发现元数据。你需要在Gin启动时从Consul读取otel_exporter_jaeger_endpoint、otel_service_name、otel_sampler_ratio等参数，并手动注入到OTel SDK初始化逻辑中。关键不是“Consul集成OTel”，而是“用Consul的配置驱动OTel初始化”。
常见错误现象：直接把Consul KV路径写进jaeger.New()调用里，导致启动失败——因为jaeger.WithEndpoint()只接受字符串常量或运行时已解析的URL，不支持延迟求值。
- 从Consul读取配置必须在
NewTracerProvider()之前完成，否则exp构造器拿不到真实endpoint - 推荐使用
consulapi.NewClient()配合client.KV().Get()同步拉取，避免异步初始化竞争 - Consul中建议按环境隔离路径，例如
dev/observability/otel/jaeger_endpoint，避免prod误用测试地址 - 若Consul不可用，必须提供硬编码fallback（如
http://localhost:14268/api/traces），否则服务无法启动
为什么不能用Consul的Service Tags传OTel参数
Consul的服务注册tags字段（Tags: []string{"otel-sampler=0.1", "otel-service=auth"}）看似方便，但实际不可靠：tags长度限制为256字节、不支持嵌套结构、且otelgin.Middleware()完全不读取Consul tags。这些tag只用于服务发现过滤，不是配置通道。
真正生效的只有你代码里显式读取并传入SDK的值。比如你从Consul拿到"0.01"，必须手动转成float64再喂给tracesdk.TraceIDRatioBased()，否则采样率永远是默认的1.0。
- 不要依赖Consul UI手动修改tags来调整采样——改了也没用
- Service Name必须与
otelgin.Middleware("xxx")第一个参数严格一致，否则Jaeger里显示为"unknown_service:gin" - Consul健康检查失败时，配置读取可能超时，需设置
client.SetWriteTimeout(3 * time.Second)
Gin启动时如何安全加载Consul配置并初始化TracerProvider
顺序错了就会panic：先调otelgin.Middleware()再读Consul，或者并发读Consul又没加锁，都可能导致TracerProvider用空值初始化。
正确做法是把Consul读取、OTel Provider创建、Gin路由注册拆成明确三步，且前两步在main()最开头串行执行：
func main() {
// 1. 初始化Consul client并拉取OTel配置
cfg, err := loadOtelConfigFromConsul("dev")
if err != nil {
log.Fatal("failed to load otel config from consul: ", err)
}
<pre class="brush:php;toolbar:false;">// 2. 创建TracerProvider（此时cfg已就绪）
tp, err := NewTracerProvider(cfg.ServiceName, cfg.JaegerEndpoint, cfg.SamplerRatio)
if err != nil {
log.Fatal("failed to create tracer provider: ", err)
}
defer tp.Shutdown(context.Background())
// 3. 注册Gin中间件（必须用tp生成全局Tracer）
r := gin.Default()
r.Use(otelgin.Middleware(cfg.ServiceName, otelgin.WithTracerProvider(tp)))
r.GET("/health", func(c *gin.Context) { c.JSON(200, "ok") })
r.Run(":8080")}
-
loadOtelConfigFromConsul()应返回结构体，而非map[string]string，避免字段拼写错误（如serice_name）静默失效 -
otelgin.WithTracerProvider(tp)必须显式传入，否则中间件会 fallback 到全局默认provider，而该provider未配置Jaeger exporter - 所有
defer tp.Shutdown()必须在HTTP server启动前注册，否则Ctrl+C时无法flush未发送span
Consul配置变更后如何热更新OTel采样率
OpenTelemetry Go SDK不支持运行时替换TracerProvider，所以Consul里改了otel_sampler_ratio，旧连接的span仍按老比率采样。热更新只能靠重建Span处理器（Processor），但代价高、易出错，生产环境通常不这么做。
更务实的做法是：把采样率设为固定值（如0.001），仅在debug阶段通过Consul临时调高；或让Consul配置控制的是otel_exporter_jaeger_endpoint（切换Jaeger集群），而非采样逻辑。
- 如果真需要动态采样，得自己实现
sdktrace.Sampler接口，内部定期查Consul——但每次Span创建都触发一次Consul请求，性能灾难 - Consul Watch机制（
client.KV().ListWatch()）适合通知进程reload，但reload意味着重启Gin服务，无法做到无感更新 - 最容易被忽略的一点：即使采样率更新了，Jaeger UI里旧trace仍显示“Sampled: true”，因为采样决策发生在Span创建瞬间，不可逆
