Uptrace默认不接收Go服务数据，需确保uptrace-dsn拼写正确、端口（14318）匹配、token权限有效；Go SDK必须显式传入DSN并使用otlptracehttp.New，且context传播、中间件注册、数据库插件等环节缺一不可。
Uptrace 能直接用，但默认配置下它不接收你的 Go 服务数据——关键在 uptrace-dsn 的拼写、端口和 token 权限，三者错一个，Span 就静默丢弃，连错误日志都不打。
启动 Uptrace 服务时必须确认端口和 DSN 匹配
Uptrace 默认监听 14318 端口（HTTP），不是常见的 4318（OTLP gRPC）或 8080。如果你改过 docker-compose.yml 里的 ports，或者用了反向代理，uptrace-dsn 里的 host 和 port 必须同步更新。
-
uptrace-dsn格式必须是http://<token>@localhost:14318/<project_id>，不能漏掉http://前缀 - 本地开发用
localhost，容器内调用要换成uptrace（Docker Compose service name）或宿主机 IP（如host.docker.internal） - 如果 Uptrace 启动后访问
http://localhost:14318页面能打开，但curl -v http://localhost:14318/health返回 404，说明服务没真正就绪，别急着连 SDK
Go SDK 初始化必须显式传入 DSN，不能只靠环境变量
Uptrace 的 Go SDK 不读取 UPTRACE_DSN 环境变量，必须手动传参。常见错误是复制了 OpenTelemetry 的通用示例，漏掉 WithHeaders 里塞 DSN 这一步。
- 导出器必须用
otlptracehttp.New，不是otlptracegrpc.New—— Uptrace 当前只支持 HTTP 协议上传 trace -
WithEndpoint("localhost:14318")里的地址必须和 DSN 中的 host:port 一致，否则 headers 会被忽略 - token 需从 Uptrace 控制台「Project Settings」里复制完整字符串，包含
http://和/<project_id>，不要手动截断
Span 不上报？先检查 context 传播是否被中断
Uptrace 依赖 OpenTelemetry 的 context 传递机制。Gin、Echo 等框架中间件若未正确注入 otelhttp.NewMiddleware，或手动创建的 goroutine 没用 otel.GetTextMapPropagator().Inject，Span 就会断链。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- HTTP handler 外部发起的异步任务（如
go func() { ... }()）必须显式携带原始ctx，否则新 goroutine 里tracer.Start生成的是孤立 Span - Gin 用户务必在路由注册前加
r.Use(otelgin.Middleware("my-service"))，否则请求入口就断了 - 数据库调用（如 GORM）需启用插件：
gorm.Open(..., gorm.Config{Plugin: otelgorm.New()})，否则 DB 查询不会自动埋点
指标和日志关联需要额外配置，不是开箱即用
Uptrace 默认只收 trace 数据。想把 log.Printf 或 zap 日志按 TraceID 关联，得手动注入 context 并格式化输出。
- 日志库必须支持
ctx透传，例如 zap：用logger.WithOptions(zap.AddCallerSkip(1)).Info("msg", zap.String("trace_id", trace.SpanFromContext(ctx).SpanContext().TraceID().String())) - Prometheus 指标若想和 trace 关联，需在
CounterVec或Histogram的 label 里加入trace_id，但这会爆炸性增加指标维度，生产慎用 - Uptrace 控制台里点击某个 Span 查看详情时，右上角「Logs」tab 是空的——除非你已部署 Loki 并在 Uptrace 设置里填了 Loki URL
Uptrace 的坑不在安装，而在数据链路的每个衔接点都要求精确匹配：DSN 字符串、端口、context 传播、中间件注册顺序。少一个环节，数据就消失得无声无息，连 warning 都不报。调试时优先 curl http://localhost:14318/api/traces 看是否有数据流入，再查 SDK 日志级别是否设为 debug。
