zipkin客户端初始化必须指定正确的endpoint地址，即指向zipkin collector的http接收端（如http://localhost:9411/api/v2/spans），而非ui地址；填错或遗漏路径将导致span静默丢弃且无报错。
Zipkin客户端初始化必须指定正确的Endpoint地址
Go服务启动时，zipkinhttp.NewReporter 传入的URL必须指向Zipkin Collector的HTTP接收端（默认是 http://localhost:9411/api/v2/spans），而不是UI地址。如果填成 http://localhost:9411 或漏掉 /api/v2/spans，日志里不会报错，但Span完全不上传——这是最常被忽略的静默失败点。
实操建议：
- 用
curl -X POST http://localhost:9411/api/v2/spans --data-binary @span.json手动测试Endpoint是否可写 - 在Reporter初始化后加一行日志：
log.Printf("Zipkin reporter configured for %s", endpoint)，确认地址拼接无误 - 若Zipkin部署在K8s中，Endpoint应为Service DNS名（如
http://zipkin.default.svc.cluster.local:9411/api/v2/spans），不是ClusterIP或Pod IP
OpenTracing与OpenTelemetry过渡期要避免混用API
很多老项目还在用 opentracing-go + zipkin-go-opentracing，但新项目应直接用 open-telemetry-go + otelcol/zipkin exporter。两者不能共存：同一进程里同时调用 ot.InitGlobalTracer() 和 otel.SetTracerProvider() 会导致Span丢失，且无明确错误提示。
判断依据：
- 查
go.mod：出现github.com/opentracing/opentracing-go就是旧栈；出现go.opentelemetry.io/otel就是新栈 - 追踪代码中是否调用
tracing.StartSpan()（旧）或tracer.Start(ctx, "handler")（新） - 旧方案中
zipkin-go的http.Transport需手动配置超时，新方案通过otelhttp.NewTransport()自动集成
HTTP中间件注入TraceID需覆盖所有入口路径
只在主路由上加 otelhttp.Middleware 不够。Gin/Echo等框架的静态文件、健康检查（/health）、指标接口（/metrics）若没显式挂载中间件，这些请求就不会生成Span，导致链路断开。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
正确做法：
- Gin中用
r.Use(otelhttp.Middleware("service-name"))全局注册，而非仅对r.GET("/api/...")单独加 - 如果用了自定义Router（比如gRPC gateway），需对gateway生成的HTTP handler再包一层
otelhttp.Handler - 检查
net/http.DefaultServeMux是否有未接管的路径——例如直接http.HandleFunc("/ping", ...)的写法会绕过OTel中间件
采样率配置不当会导致高QPS服务压垮Zipkin
zipkin-go 默认采样率是1.0（全量），而 otel/sdk/trace 默认是0.001（千分之一）。微服务QPS超过500后，全量上报会让Zipkin Collector CPU飙升，甚至丢Span。
调整建议：
- 开发环境用
zipkin.NewModularSampler(zipkin.ProbabilisticSampler(0.1))（10%） - 生产环境按服务等级分级：核心订单服务设0.05，查询类服务设0.001
- 避免用
zipkin.CountingSampler(100)这类固定频次采样——突发流量下仍可能打满Collector
真正麻烦的是跨语言链路：Java服务设了0.01采样，Go这边设0.1，最终Zipkin收到的Span里ParentID对不上，整条链就散了。采样策略必须全局对齐。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
