搭建Golang环境并集成链路追踪组件-Golang-PHP中文网

go链路追踪静默失效的根本原因是tracerprovider未在main()开头注册且未调用otel.settracerprovider和otel.settextmappropagator，导致otel.tracer()返回nil span，所有埋点失效、jaeger无数据。

搭建golang环境并集成链路追踪组件

Go 环境装好了不代表链路追踪能跑起来；otel.Tracer 不 panic、span 为 nil、Jaeger 里空空如也——这八成是环境和 SDK 初始化没对上，不是代码写错了。

很多人的 go version 能跑，但 go get go.opentelemetry.io/otel 报错或依赖不生效，根源在模块模式没开或 GOPATH 干扰。

运行 go env -w GO111MODULE=on 强制启用模块（Go 1.16+ 默认开启，但 CI 或旧脚本可能关着）
删掉项目根目录下的 vendor/ 目录（除非你明确要 vendor）
别在 $GOPATH/src 下新建项目——go mod init 会误推 module 名，导致 import 路径错乱
验证 go 是否真在 PATH：macOS/Linux 执行 which go，Windows 用 PowerShell 运行 Get-Command go

otel.Tracer("x") 永远不会 panic，但若没提前设好 TracerProvider，它返回的 span 就是 nil，所有埋点静默失效——HTTP handler、DB 查询、goroutine 全部断链，日志里连 warning 都没有。

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

必须在 main() 函数第一行（或紧随 init() 后）调用初始化函数，例如 initTracer()
严禁在 init() 里初始化：配置（如 JAEGER_AGENT_HOST）还没加载，jaeger.NewTracer() 可能返回 nil，otel.SetTracerProvider(tp) 传入 nil 不报错但彻底失效
注册后必须配齐两件事：otel.SetTracerProvider(tp) 和 otel.SetTextMapPropagator(propagation.TraceContext{})，缺一不可
本地调试时加一句 log.Printf("tp: %v", otel.GetTracerProvider())，确认输出不是 <nil></nil>

手写中间件去读 req.Header.Get("traceparent") 再 tracer.Start()，会导致跨 goroutine 传播失败、net.peer.ip 缺失、状态码不自动记录、span name 固定为 HTTP GET 而非真实路由。

正确姿势：http.ListenAndServe(":8080", otelhttp.NewHandler(myHandler, "my-service"))
Gin 用户必须用 ginotel.Middleware，不是 gin.Use(otelhttp.NewHandler(...)) —— 否则路由参数丢失，span name 变成 GET /
otelhttp.NewHandler 第二个参数（span name）不能为空字符串，Jaeger 等导出器会静默丢弃该 span
handler 内部若 panic 或提前 return，defer span.End() 不执行，span 被丢弃——务必确保 span.End() 在函数退出前被调用

Go 的 context.Context 不跨 goroutine 自动携带 span，db.Query()、http.Client.Do()、go func() {}() 全部默认从 context.Background() 开始新链路。

出向 HTTP：用 &http.Client{Transport: otelhttp.NewTransport(http.DefaultTransport)}，别直接改 http.DefaultClient
DB 查询：必须用 db.QueryContext(ctx, ...)，不能用 db.Query(...)；GORM 要调 WithContext(ctx)
启动 goroutine：写成 go doWork(ctx)，不是 go doWork(context.Background())
异步逻辑如 time.AfterFunc、sync.WaitGroup，同样要传 ctx，并用 context.WithTimeout 控制生命周期