必须用go build -toolexec接管编译流程，否则AST修改不生效；GO111MODULE=on必须开启，禁用go run和IDE一键运行，确保GOROOT/GOPATH不冲突，Gin注入需满足HandlerFunc签名且不手动重复StartSpan。
Go 编译期注入链路追踪的前提条件
必须用 go build -toolexec 接管编译流程，否则语法树修改不会生效。这不是可选配置，而是 Go Agent 实现无侵入埋点的唯一入口。不启用该参数，所有 AST 分析和代码插入都只停留在本地调试阶段，生成的二进制里完全不含监控逻辑。
-
GO111MODULE=on必须开启，否则toolexec工具无法正确解析模块路径和依赖关系 - 不能使用
go run或 IDE 的一键运行 —— 它们绕过完整构建链，跳过-toolexec - 确保
GOPATH和GOROOT不冲突，尤其当本地同时存在多个 Go 版本时，toolexec会按当前 shell 的go命令版本执行，容易因版本不一致导致 AST 解析失败
Gin HTTP handler 自动注入 trace context 的位置判断
Go Agent 不是简单地在每个函数开头插 span := tracer.StartSpan(...)，而是识别 Gin 的 HandlerFunc 类型签名和注册模式。它只在满足以下全部条件的函数上插入：函数名未以 test 或 mock 开头、参数列表含 *gin.Context、返回值匹配 Gin 中间件或路由 handler 约定（如 func(c *gin.Context) 或 func(c *gin.Context) interface{}）。
- 手动写的中间件（如
func(c *gin.Context) { c.Next() }）会被注入；但func(http.ResponseWriter, *http.Request)这类原生 net/http handler 不会 —— Gin Agent 不处理非 Gin 生态代码 - 如果 handler 里用了
c.Request.Context()却没调用otel.GetTextMapPropagator().Extract(...)，注入后的 span 上下文仍可能丢失，因为 Go Agent 只负责创建 span，不接管传播逻辑 - 别在 handler 内部再手动调用
otel.Tracer("xxx").Start()，会导致 span 嵌套错乱，父子关系断裂
编译期注入后 trace ID 无法跨服务传递的常见原因
注入本身成功，不代表链路能串联。最关键的断点往往不在你的服务内，而在 outbound HTTP 调用时的 header 注入缺失。Go Agent 默认只处理 inbound 请求，outbound 需显式启用 HTTP client 拦截器。
- 若使用
http.DefaultClient发起请求，必须提前 wrap 成otelhttp.NewClient(http.DefaultClient)，否则 trace_id 不会写入traceparentheader - 用
resty或go-resty/resty/v2时，需调用.SetTransport(otelhttp.NewTransport(http.DefaultTransport))，仅设置SetHeader手动塞traceparent是无效的 —— OpenTelemetry 的 propagator 会覆盖它 - Gin handler 注入的 span 使用的是全局
otel.Tracer，但如果服务启动时没调用otel.SetTracerProvider(tp)，所有 span 都会静默丢弃，日志里也无报错
AST 修改后编译失败的典型错误信息与修复方向
最常见的失败不是语法错误，而是类型推导冲突。比如 Go Agent 在 func(c *gin.Context) 开头插入的 span 创建代码，若原函数已声明同名变量 span，就会触发 duplicate declaration。
立即学习“go语言免费学习笔记（深入）”；
- 错误信息示例：
./handler.go:42:2: duplicate declaration: span→ 检查该 handler 内是否已有var span ...或span := ... -
cannot use ... as type ... in assignment→ 注入的 span 结束代码（如span.End()）被插在 defer 语句之后，而 defer 引用的变量在注入点之后才声明，AST 重排后作用域失效 - 升级 Go 版本后注入失败？dst 库对 Go 1.22+ 的泛型语法支持滞后，建议锁定 Go Agent 适配的 Go 版本范围（目前稳定支持到 1.21），不要盲目升级 SDK
