dd-trace-go 初始化必须在main()第一行执行，延迟或在goroutine中初始化会导致上下文丢失、Span不继承、Trace ID断裂；需传入tracer.WithService参数，HTTP中间件中须显式传递并注入context，每个Span必须调用Finish()且设置error标签。
dd-trace-go 初始化必须在 main() 开头执行
延迟初始化或放在 goroutine 里会导致上下文丢失、Span 不继承、Trace ID 断裂。Datadog Tracer 的全局状态（如 active span stack、propagation 配置）依赖于 tracer.Start() 的早期注册。
- 正确姿势：在
main()函数第一行调用tracer.Start()，并在defer tracer.Stop()放在最外层 defer - 错误写法：
go func(){ tracer.Start(...) }()或在 HTTP handler 内初始化 —— 此时 parent context 已丢失，所有子 Span 都变成孤立根 Span - 必须传入
tracer.WithService("your-service-name")，否则 Datadog 后端无法归类服务，服务地图为空 - 若使用 Kubernetes，建议用
tracer.WithService(os.Getenv("DD_SERVICE"))动态注入，避免硬编码
HTTP 中间件里手动创建 Span 要显式传递 context
Go 的 http.Handler 接口不携带 context，标准库也不自动注入，所以必须从 request.Context() 提取并注入到 Span 创建中，否则父子关系断裂。
- 用
req.Context()获取原始 context，再通过tracer.StartSpan("http.request", tracer.ChildOf(...))构建子 Span - 关键参数：
tracer.SpanContextFromRequest(req)是推荐方式（dd-trace-go/v2v1.60+），它自动解析traceparent和x-datadog-trace-id头 - 别直接用
tracer.StartSpan("http.request")—— 这会创建新 Trace，导致链路断开 - 记得把新 Span 的 context 注入回 request：用
req = req.WithContext(tracer.ContextWithSpan(req.Context(), span))
自定义框架集成要补全 Span 生命周期和 error 标签
官方 SDK 对 Gin/Echo 等框架做了完整封装（自动 start/finish/span tagging），但私有框架容易漏掉关键收尾动作，导致 Span 持续 dangling 或指标失真。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 每个 Span 必须显式调用
span.Finish()，尤其在 panic recovery 分支里也要补上 —— 否则 Datadog 侧显示“running”状态，数据不入库 - 设置错误标签：发生 error 时，必须调用
span.SetTag(ext.Error, true)和span.SetTag(ext.ErrorMsg, err.Error())，否则错误率指标为 0 - 数据库/HTTP client 调用需手动 wrap：比如用
tracer.WrapHTTPTransport(http.DefaultTransport)，否则 outbound 请求不带 trace header - 避免在 Span 上设置过多自定义 tag（尤其是高基数字符串），会显著增加 Datadog ingestion 成本和查询延迟
本地开发调试时禁用采样但保留 trace propagation
开发环境默认 100% 采样会压垮本地 Datadog Agent，但完全关闭又无法验证链路是否贯通 —— 需折中配置。
立即学习“go语言免费学习笔记（深入）”；
- 启动时加
tracer.WithSamplingRules([]tracer.SamplingRule{{Service: "*", Rate: 0}})关闭指标上报，但保留 trace header 透传 - 配合
DD_TRACE_DEBUG=true环境变量，让日志输出每条 Span 的 trace_id / span_id / parent_id，方便肉眼核对传播路径 - 用 curl 测试时务必带上
-H "traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"手动构造 trace context，验证你的中间件是否能正确提取 - 注意：Kubernetes Pod 内 DNS 解析失败是本地调试最常见的“无数据”原因，先
nslookup datadog-agent.default.svc.cluster.local确认连通性
