最省事的起点是用otelhttp.NewHandler包裹HTTP handler，自动完成span创建、context注入和header传播；需配合自动resource探测、req客户端埋点及otlpgrpc导出器。
用 otelhttp 包裹 HTTP handler 是最省事的起点
绝大多数 Golang 云原生服务都是 HTTP 服务，手动在每个 handler 里调用 tracer.Start() 和 span.End() 不仅重复、还容易漏掉 defer 或上下文传递错误。直接用 go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp 提供的中间件，两行代码就能自动完成 span 创建、context 注入、header 传播和生命周期管理。
- 必须用
otelhttp.NewHandler()包裹原始 handler，不能只传入函数指针——否则丢失请求元信息（如 URL 路径、method） - 如果用了 Gin/Echo 等框架，别试图“兼容旧 middleware”，直接替换路由注册方式；Gin 的
Use(otelgin.Middleware())是第三方封装，稳定性不如官方otelhttp - 注意：它默认把整个 HTTP 请求生命周期作为一个 span，若需拆解内部逻辑（如 DB 查询、RPC 调用），得在 handler 内部用同一
Tracer手动创建子 span
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 业务逻辑
})
wrapped := otelhttp.NewHandler(handler, "api.health")
http.Handle("/health", wrapped)
初始化 SDK 别手写 resource，用 resource.WithHost() 等自动探测
硬编码 service name、host、env 容易在不同环境出错，比如 Kubernetes 下 Pod 名称、namespace、container ID 都该自动获取。OpenTelemetry Go SDK 提供了 resource.New() + WithHost()/WithContainer()/WithK8s() 等 detector，能从 cgroup、procfs、downward API 自动填充，比自己读 /etc/hostname 或环境变量更可靠。
- 本地开发时
WithK8s()会失败并静默跳过，不影响启动；生产环境只要挂载了 k8s metadata 卷，就自动生效 -
resource.WithProcess()会采集进程名、PID、启动参数，但不包含 Go 版本——需额外加semconv.ServiceVersionKey.String(runtime.Version()) - 别漏掉
resource.WithTelemetrySDK()，它能让后端（如 Jaeger、阿里云 SLS）识别 SDK 类型和版本，排查导出异常时很关键
res, _ := resource.New(ctx,
resource.WithHost(),
resource.WithContainer(),
resource.WithK8s(),
resource.WithTelemetrySDK(),
)
HTTP 客户端调用也要埋点，req 库比原生 http.Client 更省心
服务 A 调用服务 B，如果只在服务 A 的入口埋点，链路到 outbound HTTP 就断了。原生 http.Client 需要自己 wrap RoundTripper 并处理 context 透传，而 req 库内置了 OpenTelemetry 支持，只需传一个 Tracer 实例，所有请求自动创建 child span 并继承 trace context。
- 必须确保调用方和被调用方使用相同的 trace header 格式（默认是
traceparent），否则跨语言链路拼不上；req默认启用 W3C Trace Context，无需额外配置 - 如果下游是老系统（只认
uber-trace-id），得关掉req的 W3C 模式，并手动注入 OpenTracing 兼容 header - 别在循环里反复 new
req.Client——它内部有连接池和 tracer 缓存，全局复用即可
client := req.C().SetTracer(tracer)
resp, err := client.R().
SetContext(ctx). // 关键：传入上游 context，才能继承 traceID
Get("https://api.example.com/users")
导出器选 otlptracegrpc 而非 otlptracehttp，尤其在容器环境
虽然两者都走 OTLP 协议，但 otlptracegrpc 使用 gRPC over HTTP/2，支持流式批量上报、头部压缩、连接复用；而 otlptracehttp 是单次 POST，高频小 span 场景下 CPU 和网络开销明显更高。在 Kubernetes 中，Collector 通常暴露 gRPC 端口（如 otel-collector:4317），直接连它比走 HTTP 网关更稳定。
立即学习“go语言免费学习笔记（深入）”；
- gRPC 导出器默认启用了 keepalive，但若 Collector 在 NAT 后（如某些边缘节点），可能被中间设备断连——此时需显式配置
grpc.WithKeepaliveParams() - 别忽略超时设置：
otlphttp.NewClient()默认无超时，网络卡顿时会阻塞整个 trace pipeline；otlpgrpc.NewClient()可通过grpc.WithTimeout()控制 - 若 Collector 不可用，SDK 默认会丢弃 span；如需降级（如日志 fallback），得自己实现
Exporter接口，不是简单配个参数
