结论：用 opentelemetry sdk + 自动 resource 探测 + otelhttp/otelgrpc 中间件可构建生产级遥测层；必须用 detectors（如 kubernetes/env/host）自动识别 service.name 等资源属性，避免硬编码导致标签错乱；http/grpc 须用对应中间件封装以保障 context 传播与 span 完整性；导出器首选异步 otlpgrpc 并配合理配置 batch 和 endpoint；指标需异步 exporter 防 goroutine 阻塞。
直接结论：用 OpenTelemetry SDK + 自动 resource 探测 + otelhttp/otelgrpc 中间件，就能在 Golang 模块里搭出真正能进生产环境的遥测层，不需要手写 context 传播或反复 patch HTTP 客户端。
初始化 SDK 时别手动填 resource，用 detectors 自动识别
硬编码 service.name 或 host.name 是最常见也最容易翻车的点——K8s 环境下 Pod 名、Namespace、Cluster 名全靠 runtime 推断，手动写死会导致 trace/metric 标签错乱、Grafana 查询失效。go.opentelemetry.io/otel/sdk/resource 提供的 detector 能自动抓取这些信息，配合 go.opentelemetry.io/contrib/detectors 下的 k8s、env、host 探测器，一行代码就搞定：
res, _ := resource.New(ctx,
resource.WithDetectors(
detectors.NewKubernetesDetector(),
detectors.NewEnvDetector(),
detectors.NewHostDetector(),
),
)
- 必须在
resource.New里传detectors.NewKubernetesDetector()，否则 K8s 部署时service.instance.id会是空字符串，导致指标聚合失败 - 如果用
docker-compose本地调试，detectors.NewEnvDetector()会读取OTEL_SERVICE_NAME环境变量，比硬编码更灵活 - 不调用
WithDetectors而只用WithServiceName("my-svc")，会导致 Prometheus 的job和instance标签无法对齐，Grafana 里的服务拓扑图会断连
HTTP 和 gRPC 服务必须用 otelhttp / otelgrpc 中间件包装
自己调 tracer.Start + span.End 不仅重复，还极大概率漏掉 context 传播逻辑。比如 Gin 路由里没显式从 header 解析 traceparent，跨服务调用链就直接断掉。otlhttp 和 otelgrpc 已经封装好 W3C Trace Context 协议解析、span 生命周期管理、error 自动标注等细节：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
r := gin.New()
r.Use(otelgin.Middleware("my-api")) // ← 自动创建 server span 并注入 context
-
otelhttp.NewHandler包装http.Handler时，第二个参数是operation name，建议设为路由路径（如"/user/{id}"），而不是固定字符串，否则所有请求都归到同一个 span 名下，无法区分接口粒度 - gRPC 客户端调用前，必须用
otelgrpc.WithClientOptions()包装grpc.Dial，否则 client-side span 不会发出去；服务端则需在grpc.Server初始化时传入otelgrpc.UnaryServerInterceptor() - 中间件默认把 status code 记为 span attribute，但不会标记 error —— 只有返回非 nil error 且 HTTP 状态码 ≥ 400 时才触发
span.SetStatus，这点要和业务错误码逻辑对齐
导出器优先选 otlpgrpc，别用 jaeger 或 zipkin 直连
jaeger-thrift 或 zipkin-http 导出器在云原生环境里容易成为瓶颈：它们是同步阻塞式发送，一旦后端抖动或网络延迟升高，会拖慢整个服务的响应。otlpgrpc 基于 gRPC 流式传输，自带重试、背压、batching 和 TLS 加密，还能复用 OpenTelemetry Collector 这个统一入口做采样、过滤、格式转换：
exporter, _ := otlptracegrpc.New(context.Background(),
otlptracegrpc.WithInsecure(), // 生产环境换为 WithTLSCredentials
otlptracegrpc.WithEndpoint("otel-collector:4317"),
)
-
otlptracegrpc默认 batch size 是 512，每 5 秒 flush 一次；如果 QPS 很高（比如 >1k/s），建议调大WithBatcher参数，避免频繁小包发送 - 别把
OTEL_EXPORTER_OTLP_ENDPOINT设成公网地址 —— Collector 应该部署在集群内，通过 ClusterIP Service 暴露，否则 trace 数据会绕行公网，既慢又不安全 - 如果用 Istio，Collector 可以接在 sidecar 后面，复用 mTLS；但要注意 Istio 默认禁用
4317端口，得在Sidecar资源里显式放开
指标上报必须配异步 exporter，且禁用同步 blocking
OpenTelemetry 的 metric.MeterProvider 默认用同步方式 push 数据，遇到网络卡顿就会 block 整个 goroutine。尤其在高频打点场景（比如每个请求都记录 http.request.duration），可能引发 goroutine 泄漏：
mp := metric.NewMeterProvider(
metric.WithReader(
prometheus.New(),
),
)
-
prometheus.New()返回的是异步 exporter，但前提是你的MeterProvider没被其他同步 reader 覆盖 —— 检查是否误用了memory.New()或stdout.New()这类调试型 reader - 如果你用
otlpmetricgrpc，必须显式设置WithPeriodicExporter并指定 interval（如 10s），否则它默认用 60s，会导致 Grafana 里指标延迟严重 - 所有
Counter和Histogram的Record调用都是 lock-free 的，但Gauge如果绑定了函数回调（比如采集内存使用率），这个函数不能阻塞，否则会卡住整个 metrics pipeline
真正难的不是写几行 SDK 初始化代码，而是让遥测数据在 K8s 的 Pod 重启、HPA 扩缩、Istio 注入、Collector 升级这些真实扰动下依然稳定可查 —— 关键在于 resource 自动探测、中间件封装、OTLP 协议栈和异步指标 pipeline 这四层必须咬合，缺一不可。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
