go项目接入opentelemetry需避开四大陷阱：tracer名称须按服务/模块隔离；http埋点必须用otelhttp或otelgin且顺序正确；otlp exporter需匹配endpoint协议与鉴权头；resource属性（如service.name）必须显式配置，否则数据全标为unknown_service:go。
Go 项目接入 OpenTelemetry 不需要重写业务逻辑，但必须避开几个关键陷阱：tracer 名称混用、exporter 未注册导致静默丢数据、HTTP 中间件顺序错乱导致 context 丢失。下面直奔实操要点。
otel.Tracer 实例不能全局复用一个名称
你写 otel.Tracer("default") 看似省事，实际会让 HTTP handler、GORM 查询、Kafka 消费者共用同一套 span 生命周期，造成 span name 冲突、attribute 覆盖、采样策略失效。
- 每个服务/模块应使用专属名称，例如
otel.Tracer("user-service")或otel.Tracer("auth-middleware") - 不要在包级变量里缓存 tracer，应在初始化时通过构造函数传入（如 Gin handler 初始化）或从
context.Context中提取 - 若用
otel.GetTracerProvider().Tracer(...)，务必确认 tracer provider 已调用SetTracerProvider(tp)且 exporter 已正确注册，否则返回的是 noop 实现，日志和 trace 全部不发
HTTP 层埋点必须用 otelhttp 或 otelgin，且顺序不能错
手动调用 propagator.Extract() 或直接读 r.Header.Get("traceparent") 是错的——W3C 格式校验、大小写归一、多值合并都由 propagator 自动处理；而中间件顺序错误会导致下游服务收不到 trace context。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- Gin 项目优先用
otelgin.Middleware，它自动从gin.Context提取并注入 span，无需额外操作 - 原生
net/http必须把otelhttp.NewHandler套在最外层 handler 上，例如http.ListenAndServe(":8080", otelhttp.NewHandler(mux, "root")) - 若同时用 Prometheus metrics 中间件和 otelhttp，确保 otelhttp 在外层（先建 span，再记录指标），否则 metrics 可能拿不到 span context
- 客户端请求要用
otelhttp.NewTransport()包装，而不是自己 inject header——重复 inject 会触发校验失败
OTLP 导出器配置失败常因 endpoint 或 headers 错误
本地跑通但上生产就收不到数据？大概率是 endpoint 地址、协议、鉴权头没对齐。OpenTelemetry 默认走 gRPC（4317），但很多 collector 只暴露 HTTP（4318）端口，且阿里云、Elastic APM 等平台强制要求带鉴权 header。
- 检查环境变量：
OTEL_EXPORTER_OTLP_ENDPOINT是否指向 collector 的 HTTP 接口（如http://otel-collector:4318），不是 gRPC 地址 - 阿里云可观测链路 OpenTelemetry 版需设置
OTEL_EXPORTER_OTLP_HEADERS，格式为Authorization=Bearer <token></token>，endpoint 路径类似https://<region>.tracing.aliyuncs.com/adapt_@xxxxx@xxxx/api/otlp/v1/traces</region> - Elastic APM 要求
OTEL_EXPORTER_OTLP_ENDPOINT指向 APM Server 的 OTLP 接口（如https://apm-server:8200/v1/otlp），并配置OTEL_EXPORTER_OTLP_HEADERS为Authorization=ApiKey <base64-encoded></base64-encoded> - 启动时加
OTEL_LOG_LEVEL=debug可看到 exporter 连接状态和失败原因
自动仪表化（auto-instrumentation）适合快速验证，但不替代手动埋点
Sidecar 方式（如 otel/autoinstrumentation-go）确实能零代码捕获 HTTP、gRPC、DB 驱动调用，但它只覆盖标准库和常见驱动，对自定义协议、内部业务逻辑、异步任务完全无感。
- Kubernetes 中部署 sidecar 时，必须设
securityContext.runAsUser: 0和privileged: true，否则无法 ptrace 注入 -
OTEL_GO_AUTO_TARGET_EXE必须指向二进制绝对路径，且该进程需以非 root 用户启动（sidecar 会降权执行） - 自动埋点生成的 span 名称固定（如
http.server.request），无法体现业务语义；关键路径仍需手动调用tracer.Start(ctx, "checkout-payment")补充业务标签和 error 记录 - 自动仪表化不采集 metric，log 关联也受限——真正落地仍要结合
go.opentelemetry.io/otel/metric和结构化日志（如 zap）
最易被忽略的一点：resource 配置。不设 service.name、service.version、telemetry.sdk.language 等 resource 属性，所有 trace 和 metric 在 Jaeger/Prometheus 里都会变成“unknown_service:go”，排查时根本分不清是哪个服务打的数据。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
