适用场景

链路追踪解决的是「一次请求慢在哪一段」。落地难点不在装组件，而在采样与关联：全量采样成本高、采样率低了抓不到故障、trace_id 不进日志等于白装。

配置步骤（接入方式与埋点）

# 1) 无侵入接入（Java 示例：OpenTelemetry Java Agent）
java -javaagent:/opt/otel/opentelemetry-javaagent.jar \
  -Dotel.service.name=order-api \
  -Dotel.exporter.otlp.endpoint=http://otel-collector:4317 \
  -Dotel.traces.sampler=parentbased_traceidratio \
  -Dotel.traces.sampler.arg=0.05 \
  -jar order-api.jar

# 2) 网关生成 trace_id（Nginx/Lua 思路）
# 若上游没带 traceparent，则生成并透传

# 3) 消息队列上下文传播：生产端注入 traceparent 到消息头，消费端读取继续

# 4) 应用日志带上 trace_id（PHP 示例字段）
# log: {"ts":"...","level":"error","svc":"order","trace_id":"4bf92f...","msg":"pay timeout"}

关键参数与建议

  • 接入方式：优先无侵入（Agent/Sidecar），改代码成本高且容易漏埋点
  • trace_id 贯穿：网关生成或透传，应用日志必须打 trace_id，否则排障时无法串联
  • 采样策略：平时 1%-10% 尾采样，故障期或错误请求 100% 采样
  • 上下文传播：HTTP header（traceparent）、消息队列、定时任务都要透传
  • 数据保留：明细保留 7-15 天，聚合指标长期保留
  • 性能开销：Agent 采样与上报要限速，避免把业务拖慢
  • 验收：能对一次真实慢请求还原出完整调用链，含每段耗时与依赖

容易踩的坑

  • 只在部分服务埋点，链路在中间断掉，看不到全貌
  • trace_id 不进日志，排障时只能靠时间猜
  • 采样率设 100%，Collector 与存储被打爆
  • 采样率设 0.1%，故障请求根本没采到
  • 异步任务与消息消费没透传上下文，链路断裂
  • Agent 版本与业务框架不兼容，出现偶发超时

验证与巡检

# Collector 与采样检查
curl -s localhost:13133/ | head -3              # Collector 健康
# 在 trace 系统里按 trace_id 检索，确认有多段 span

# 日志关联抽样：随机取 5 条报错日志，看是否都有 trace_id
  • 巡检：链路完整率、采样率配置与实际一致、错误请求 100% 采样、日志 trace_id 覆盖率 > 95%

小结

链路追踪验收：随机挑一条用户投诉的慢请求，能在 3 分钟内指认慢在哪一段（应用、数据库、缓存、第三方），而不是「感觉都慢」。

> 说明：文中命令为通用写法，不同型号/版本可能略有差异，落地前请对照设备实际版本的官方文档；带外管理与安全设备变更建议先在测试设备验证。