常见陷阱与最佳实践

本章把前九章散落各处的坑收拢成一张网：70 条陷阱按六个领域汇总，事故率最高的十组问题单独深讲，再给一份"旧教程 → v2 现状"的纠偏对照（Jaeger v2 与 OTel Go 近两年变化密集，网上教程和 AI 生成代码的半数错误都落在这张表里）、分主题最佳实践、上线自检清单和一张按症状索引的调试速查表。基线 Jaeger v2.22.0、OpenTelemetry Go v1.47.0 / contrib v0.72.0，各条目的验证出处见对应章节正文。

陷阱汇总表

领域一：版本与部署（见 00-概述与安装.md、02-v2架构与组件.md、03-部署与Kubernetes.md）

领域二：埋点与 SDK（见 01-核心概念.md、05-Go客户端埋点.md）

领域三：采样（见 06-采样.md）

领域四：存储后端（见 04-存储后端.md）

领域五：可靠性与管道（见 09-性能与运维.md）

领域六：查询、UI 与 SPM 联动（见 07-查询UI与API.md、08-可观测性联动.md）

高危陷阱深讲

1. “UI 没数据”：一条五层排查链

这是 Jaeger 排障的第一高频场景，而答案几乎总是多个默认值叠加，不是单一故障。按命中概率排序过一遍：

1. SDK 根本没导出来：本地连 all-in-one 没带 WithInsecure（TLS 打明文端口）、忘 Shutdown()（短生命周期服务尾部全丢）、propagator no-op 导致只有孤立根。先开 SDK 侧 debug 日志或在 collector 上查 otelcol_receiver_accepted_spans 增速——增速为 0 是上游问题，增速正常再往下查。
2. 采样把数据掐了：独立 collector 未配 remote_sampling 时对来拉策略的 SDK 宣告 0.001；SDK 默认虽是 ParentBased(AlwaysOn)，一旦有人显式配了裸 ratio 就更糟。
3. 网络与绑定：容器里 endpoint 绑了 localhost（出厂模板默认值），端口"可见但拒连"；UDP 6831 没映射（老客户端还零报错）。
4. 落库了但查不到：ES 后端大写服务名静默失踪；写入后 1 秒内 refresh 未完成；tag 值超 256 字符不进索引。
5. UI 姿势问题：服务列表看 unknown_service:；搜索时间窗没覆盖；trace 被归档后不可搜索。

2. batch processor 吞错：不报错的丢数据

Collector 生态里 batch 是最顺手加的 processor，但对 Jaeger 管道它有个致命细节：batch 异步导出时对上游返回成功、吞掉下游错误，失败只体现在 “Sender failed” 日志里。官方 delivery-guarantees 页因此明说示例配置 “not lossless”。无损骨架：

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: []                      # 关键一：不放 batch
      exporters: [jaeger_storage_exporter]
exporters:
  jaeger_storage_exporter:
    queue:
      wait_for_result: true               # 关键二:拿到真实写入结果才确认
storage:
  backends:
    es_main:
      write_mode: sync                    # 关键三：ES 同步刷盘语义

批处理需求改用 exporter 自带的 queue.batch.{min_size,max_size,flush_timeout}（注意 min_size 零值 = 不合并）。这条链打通后，存储失败会一路回传到 receiver，以 gRPC Unavailable / HTTP 503 告知客户端——错误可见，才有重试和背压可言。完整配方见 09-性能与运维.md。

3. ES 索引管理：v2.21+ 起旧字段是"启动失败"级错误

docs 部分页面还在展示 use_ilm、use_aliases、create_mappings 这些 v1 时代的键，但 v2.22 源码里 jaeger.es.config.rejectLegacyRotationFlags（Beta，自 v2.21.0）默认拒绝它们，rejectLegacyTagsAsFields（自 v2.22.0）拒绝顶层 tags_as_fields。新语法是 indices.<type>.rotation 下 periodic / manual_rollover / auto_rollover / data_stream 四选一——其中 data_stream 语法存在但校验返回 “not yet implemented”。两个容易误判的细节：官方 config-elasticsearch.yaml 示例仍用顶层 date_layout/rollover_frequency（属于"legacy 周期字段未被列进拒绝名单"，接受但 Deprecated，别当新配置范本）；jaeger-ilm-policy 这个策略名只在 jaeger-es-rollover init 流程里写死，新语法 auto_rollover.policy_name 可自定义，只是策略本体要预先建好。被 gate 拒绝时进程直接起不来，报错会点名违规键——这是少数"配置写错反而好排查"的场景。

4. 采样的三层误解：0.001、all-in-one 和 tail

• 0.001 到底坑了谁：不配 remote_sampling 时，策略服务对来拉策略的 SDK 宣告 probabilistic 0.001；已到达 collector 的 span 一条不丢。所以"collector 不配置会丢数据"是误读，真正受伤的是信任了远端策略的 SDK 端。
• all-in-one 是反直觉的：它出厂 file 策略 default_sampling_probability: 1 全采。本地开发"怎么都有数据"，上生产换独立 collector 忘了带策略，就是 1 → 0.001 的千倍落差。
• tail 不是打捞船：tail_sampling（decision_wait 默认 5s）只能对已经上报到 collector 的 span 做去留决策；head 处被 SDK 丢掉的 span 物理上到不了眼前。想"错误全保、正常降采"，正确组合是 head 保底比例 + 关键路径提额，tail 只做精挑。decision_wait 本身还有内存驻留成本，和 collector RSS 联动规划。
• 另外记住 ratelimiting 不支持 per-operation；官方 FAQ 原话 “Some, but not all, OpenTelemetry SDKs support remote sampling”——跨语言团队先验证自家 SDK 能不能拉策略，再决定这套架构。

5. localhost 绑定：容器化的头号网络坑

v2 出厂配置里的监听地址模板是 ${env:JAEGER_LISTEN_HOST:-localhost}——宿主机直跑一切正常，进容器就变成"端口映射在、连接被拒"。三类症状同源：receiver/扩展 endpoint 绑 127.0.0.1；all-in-one 的采样端口 5778/5779 同样只绑 localhost，跨容器拉策略不通；docker run 忘 -p 且走 UDP 时连报错都没有。统一解法：容器环境设 JAEGER_LISTEN_HOST=0.0.0.0（或逐 endpoint 覆盖），并用 Pod IP 实测一次 curl/nc，别信"端口映射存在"。

6. 全局 propagator 默认 no-op：Go 埋点最阴的静默坑

otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
    propagation.TraceContext{},
    propagation.Baggage{},
))

OTel Go 的全局 propagator 出厂是 no-op（internal/global/propagator.go 实测），这四行缺失的后果非常迷惑：单服务里 span 齐全、trace 完整，一到跨服务/跨进程边界就断，且没有任何错误日志——因为没注入就等于没携带。Java/Python 等 SDK 有默认 propagator，教程互抄时这行经常被当冗余删掉。相关地：baggage 不会自动变成 attributes；消息队列（franz-go 对 OTel 零依赖）要用 propagation.MapCarrier 手动把 traceparent 塞进消息 header，消费端再 extract 续链，跨异步边界用 link 而不是硬挂 child_of。

7. 错误率恒 0：SPM 只认 status

Monitor 页签和 SPM 指标的错误判定只数 STATUS_CODE_ERROR 的 calls_total。三个独立成因都会让曲线趴平：只 span.RecordError(err) 不 span.SetStatus(codes.Error, ...)（RecordError 仅加 exception 事件，不改 status）；exclude_dimensions: ['status.code'] 裁掉了判定依据；span 没设 kind（SPM 默认只聚合 server 侧）。埋点层成对写、配置层保维度、中间件层设 kind，三层各查一遍。

8. 毒丸与死信：存储侧的两种烂数据

被 ES 校验拒绝的文档（毒丸）在不同模式下落点完全不同：write_mode: sync 下才谈得上 poison_pill_handling（drop 或进死信），async 下只记日志、不重试；直连 OTLP 又开了 exporter retry_on_failure 的话，毒丸会无限重试堵死整条队列。系统性的兜底是 04 章给出的第三条路径：jaeger_storage_exporter 换成 connectors + traces/dead_letter 管道，存储保持 fail，死信 sink 必须关掉自身 sending_queue、整收整拒，否则死信通道自己先丢。

9. 指标体系换代：看板、告警、单位三处旧账

v2 的 collector 指标全面换到 OTel Collector 命名（otelcol_receiver_accepted_spans、receiver_refused_spans…），迁移不许猜名字：仓库内置 cmd/jaeger/docs/migration/{all-in-one,badger,cassandra,elasticsearch,opensearch}-metrics.md 五张对照表。两处特例：ES 写入指标 jaeger_bulk_index_* 同名保留；而 v1 调优页赖以判断存储健康的 jaeger_collector_save_latency_bucket 在 v2.22 尚未提供（官方页红框声明），过渡期盯 jaeger_bulk_index_latency_ok/err。告警侧，monitoring/jaeger-mixin 已删除 prometheus_alerts.yml（依赖 v1 指标、无法平移），改用 OTel 生态规则。未来还有一颗雷：feature gate useSecondAsDefaultMetricsUnit 计划把 duration 指标单位从毫秒切到秒——告警阈值写成变量。

10. 基数三连击：操作名、tag 长度、属性条数

同一类事故——“数据进不去/查不到，但不报错”——有三个独立闸门：operationName 写真实 URL/ID 使序列数按公式 status_code × span_kind × (1 + 桶数) × 操作数 线性爆炸（默认典型 72 条/操作）；tag 值超 256 字符不进 ES tag.* 索引（ignore_above）；单 span 属性/事件超 128 条被 SpanLimits 静默截断。治理动作都在埋点层：路由模板命名、tag 短小、大内容出事件、属性做减法。

旧教程纠偏清单

网上存量教程、博客与 AI 生成代码多写于 v1 时代或 Jaeger v2 早期，以下 23 条"旧 → 新"对照均可直接用于排错：

最佳实践清单

埋点（Go）

• initTracer 三件套缺一不可：SetTextMapPropagator、带 service.name 的 Resource（全小写）、defer Shutdown 配 1s 超时 ctx。
• 采样统一走 ParentBased；服务自己永远不做"裸 ratio"的决定。
• RecordError 与 SetStatus 成对；HTTP/gRPC 中间件设好 span kind（SPM 与错误率判定都靠它）。
• 操作名用路由模板，tag 短小（<256 字符）、属性条数克制（128 内），大内容进事件或外部关联。
• 异步/MQ 边界显式 inject-extract + link；goroutine 传递 ctx，不重新起 Background。

部署与配置

• 镜像、chart、手册版本三者对齐钉死（本基线 2.22.0 / chart 4.16.1）；升级前跑一遍出厂配置做校验预演。
• 容器化第一天就设 JAEGER_LISTEN_HOST=0.0.0.0，并把"端口可达"纳入部署验收（curl/nc 实测，不靠映射声明）。
• 配置改动默认按"要重启"设计运维流程；只有采样策略文件享受热更。
• K8s 存储配置写进 userconfig；ES 维护 CronJob（index-cleaner/rollover/lookback/spark-dependencies）默认全 disabled，按需显式开启并监控其执行结果。

采样与存储

• 生产采样策略显式成文（file 或 adaptive），环境间迁移时对照检查；all-in-one 的全采默认值绝不允许外溢到生产。
• 新配置一律用 rotation 新语法；jaeger-ilm-policy、策略预建、numeric_attributes 只作用新索引这三个约束写进 runbook。
• 留存期闭环：TTL/清理 CronJob 与 max_span_age/trace_ttl 对齐，磁盘水位有告警。
• badger 认清单机定位；ClickHouse 只在能承受实验性破坏变更时入场。

可靠性与可观测联动

• 对每条管道书面声明"是否要求 lossless”；要求的按三件套配方配置，并把 refused/send_failed 增速做进告警。
• 大流量、强可靠走 Kafka 缓冲层；分区数、ingester 副本、批大小按"批次受分区数约束"的模型规划，用 tracegen 压拐点（09）。
• SPM 序列数做预算公式核算；Monitor 排障固定走"Prometheus 查序列 → debug 看 PromQL → 核对 normalize 开关"三步。
• Grafana 集成（exemplars、derived fields、Trace to logs）把三处开关/转义/uid 写进 provisioning 模板，不手点。

生产上线自检清单

• SDK：propagator 已显式设置；service.name 全小写统一；Shutdown 挂进退出流程
• SDK：错误路径 RecordError + SetStatus 成对；中间件设 span kind
• SDK：属性/事件 ≤128、tag 值 ≤256、操作名用路由模板
• 采样：生产采样策略成文并版本化；不依赖任何"出厂默认"
• 部署：镜像/Chart 版本钉死；JAEGER_LISTEN_HOST=0.0.0.0；UDP/HTTP 端口逐个实测连通
• 部署：v1 环境变量与旧 flag 全部清零；配置进 config.yaml（K8s 走 userconfig）
• 存储：ES 配置用 rotation 新语法且启动校验通过；清理/滚动 CronJob 已开且最近一次执行成功
• 存储：磁盘水位、TTL、max_span_age 三者对齐留存方案
• 可靠性：管道 lossless 声明明确；batch 不在无损链路上；毒丸有 drop 或死信兜底
• 可靠性：直连模式知道 30s+60s 容灾窗口；超窗故障有 Kafka 缓冲层承接
• 监控：看板按 migration 对照表迁移；告警覆盖 refused/send_failed；单位 gate 变更阈值可参数化
• 查询：程序化查询走 16685 gRPC v3；UI /api/* 无集成依赖；搜索护栏已收紧
• SPM：序列基数在预算内；Monitor 三步排障路径演练过至少一次
• 文档：本手册 09 的故障演练（杀 collector / 打满磁盘 / 灌毒丸）做过一轮

调试速查表