Go生态最主流Zipkin客户端是openzipkin/zipkin-go，支持HTTP/gRPC上报及常见HTTP框架中间件；需注意v0.4+默认用v2 API、全局复用Tracer、context传span、排查collector配置/网络/header透传三类基础问题。
Zipkin 客户端该用哪个库
Go 生态里最主流、维护最勤的 Zipkin 客户端是 openzipkin/zipkin-go，不是 uber/jaeger-client-go（那是 Jaeger 的），也不是已归档的 smartystreets/go-aws-sdk-zipkin。它支持 HTTP 和 gRPC 两种上报方式，且原生适配 net/http 和 gin 等常见 HTTP 框架的中间件模式。
容易踩的坑：openzipkin/zipkin-go v0.4+ 默认使用 v2 API（即 /api/v2/spans），但老版本 Zipkin Server（404 /api/v2/spans —— 此时得降级客户端或升级服务端。
- 推荐初始化方式：用
zipkin.NewHTTPCollector指定 URL，并显式传入zipkin.HTTPBatchSize(1)（调试期避免攒批导致延迟） - 若 Zipkin Server 开在
http://localhost:9411，collector 地址必须写全路径：http://localhost:9411/api/v2/spans，漏掉/api/v2/spans会静默失败 - 不建议用 UDP collector（
zipkin.NewUDPTransport），Go 的net.Conn.WriteTo在高并发下易丢包，且 Zipkin 服务端默认不监听 UDP
怎么给 HTTP 请求自动埋点
核心是用 zipkin.NewServerSampler + zipkin.NewServerMiddleware 包裹 handler，而不是手动在每个路由里调 span.Finish()。它会自动提取 X-B3-TraceId 等 header，生成 parent/child 关系。
常见错误现象：所有 trace 都是单个 span，没有上下游关联 —— 多半是调用方没透传 B3 header，或服务端 middleware 没生效（比如注册顺序错，放在了 CORS 或 gzip 中间件之后）。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 确保 client 发起请求时带
X-B3-TraceId、X-B3-SpanId、X-B3-ParentSpanId、X-B3-Sampled四个 header；用zipkin.NewClientSampler+zipkin.NewClientMiddleware可自动注入 - gin 用户直接用
zipkinhttp.NewMiddleware，别自己写 wrapper；echo 用户用zipkinhttp.NewEchoMiddleware - 如果用了反向代理（如 nginx），确认它没过滤掉
X-B3-开头的 header（nginx 默认会 strip 下划线 header，需加underscores_in_headers on;）
gRPC 服务怎么接 Zipkin
openzipkin/zipkin-go 本身不提供 gRPC server/client 拦截器，得靠社区封装的 github.com/openzipkin/zipkin-go-opentracing（已归档）或更轻量的 github.com/grpc-ecosystem/go-grpc-middleware/tracing/zipkin。后者依赖 openzipkin/zipkin-go v0.4+，且只做 span 生命周期管理，不侵入业务逻辑。
性能影响明显：gRPC 默认压缩 payload，但 zipkin 拦截器会在每次 unary call 中序列化 span 数据，若单次请求 span 数超 50，可能拖慢吞吐。建议在拦截器里加采样控制（比如只对 error 或耗时 >500ms 的请求打点）。
- server 端注册拦截器：用
grpc.UnaryInterceptor(zipkin.UnaryServerInterceptor(...))，参数里传入zipkin.NewTracer(...)实例 - client 端调用前，确保 context 带了 span：
ctx = zipkin.NewContext(ctx, span)，否则下游收不到 trace 上下文 - 别把
zipkin.NewTracer放在 handler 内部反复创建 —— 它含内部 goroutine 和 buffer，应全局复用
trace 数据发不出去？先看这三处
Zipkin 接入失败，80% 出在 collector 配置、网络连通性、header 透传这三点。不要一上来就查代码逻辑，先确认基础链路通不通。
- 用
curl -v http://localhost:9411/api/v2/services看 Zipkin Server 是否响应正常（返回 JSON 数组） - 在 Go 服务里加一行日志：
log.Printf("collector err: %v", err)，捕获zipkin.NewHTTPCollector返回的 error；常见是connection refused或timeout - 用
tcpdump -i lo port 9411或strace -e trace=connect,sendto,recvfrom -p $(pidof your-go-app)确认 Go 进程是否真发出了请求
跨 Docker 或 Kubernetes 时，localhost 在容器内指向自己，不是宿主机；必须用宿主机 IP 或 service 名（如 zipkin.default.svc.cluster.local），这个细节经常被忽略。
