Jaeger Agent 本地启动失败且 UDP 端口不通，主因是 Agent 未正确连接 Collector 或端口不匹配；推荐直接使用 jaegertracing/all-in-one 镜像（默认暴露 6831/udp），或手动部署时显式配置 --collector.host-port=127.0.0.1:14267（gRPC）或 --collector.http-host-port=127.0.0.1:14268（HTTP），并确保 Go SDK 的 LocalAgentHostPort 与 Agent 实际监听协议（6831 compact）一致，Docker 环境中避免用 localhost 而应改用 host.docker.internal:6831。
Jaeger Agent 本地启动失败，UDP 端口不通怎么办
Agent 启动后 Go 应用上报无数据，90% 是因为 Agent 没连上 Collector，或端口监听错位。Jaeger Agent 默认只监听 6831/udp（compact 协议），但 Collector 不监听这个端口——它只暴露 14268/http 或 14250/grpc。
- 开发环境最稳方案：直接用
jaegertracing/all-in-one镜像，它内置 Agent + Collector + UI，且默认暴露6831/udp - 手动部署 Agent 时，必须加
--collector.host-port=127.0.0.1:14267（gRPC）或--collector.http-host-port=127.0.0.1:14268（HTTP），否则 Agent 收到 span 后无法转发 - 验证 Agent 是否工作：
nc -u localhost 6831能通 ≠ Agent 正常；要抓包看是否真有 UDP 包发出，或查 Agent 日志里有没有successfully connected to collector
Go SDK 初始化时 LocalAgentHostPort 配错的典型表现
Go 应用里配了 LocalAgentHostPort: "localhost:6831"，但 Jaeger UI 里看不到服务名、Span 数为 0，甚至没报错——这是静默丢弃，不是崩溃。
- Agent 实际监听的是
6832/udp（binary 协议），但 SDK 默认发 compact 协议到6831，端口不匹配就直接丢包 - Agent 运行在 Docker 中，Go 应用跑在宿主机，
localhost指向错：应配成host.docker.internal:6831（Mac/Windows）或宿主机真实 IP（Linux） - Agent 没开
--discovery.min-peers=1，又没配 Collector 地址，会卡在“等待 peer”状态，日志里反复打印no peers available
新项目别再用 jaeger-client-go，改用 OpenTelemetry + jaegerexporter
jaeger-client-go 已归档，它不支持 Go 的 context.Context 透传模型，goroutine、DB、HTTP 调用全断链——你看到的“单跳链路”，基本是这个原因。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 初始化必须在
main()开头完成：otel.SetTracerProvider(tp)，否则所有Tracer().Start()返回 noop tracer - Gin 埋点不能只加
otelgin.Middleware，还要确保tp已注册jaeger.New导出器，且中间件注册前已调用otel.SetTracerProvider - HTTP 客户端必须用
otelhttp.NewClient()，禁用http.DefaultClient；DB 必须用otelmysql.Wrap(sql.Open())，不是手动span.Start()/End()
跨 goroutine 和异步回调里 Span 断裂的真实原因
HTTP handler 里写 go doWork()，Jaeger UI 里就出现孤立 root span，trace_id 全 0——这不是 Agent 问题，是 Go 的 context 不自动继承。
立即学习“go语言免费学习笔记（深入）”；
- 正确写法是
go doWork(req.Context())，不是go doWork() -
time.AfterFunc回调中，原req.Context()可能已被 cancel，得用ctx := otel.WithSpanContext(context.Background(), span.SpanContext())构造新上下文 - 手动创建子 span 时，parent 必须来自当前请求 context：
tracer.Start(ctx, "db.query")，禁用context.Background()
