OpenTelemetry trace 传播

OpenTelemetry trace 传播

本节摘要:上一节讲了三路独立观测后端,本节讲贯通它们的「线索」——OpenTelemetry trace。trace 让一次请求在多个服务(代理层、核心服务、知识服务)间的旅程可串联,故障时能快速定位慢节点。本节讲清 trace 如何跨服务边界传播、它如何同时喂给三路后端、以及如何在故障时用它定位问题。

一、为什么需要 trace 传播:跨服务的旅程

一次请求不只经过一个服务——它在代理层、核心服务、知识服务之间跳转。没有 trace,这些跳转是「断的」,无法串联:

没有 trace 的问题
  请求:Agent → 代理层 → 核心服务 → 知识服务 → 核心服务 → 代理层 → Agent
  
  没有统一 trace:
    代理层日志:「我耗时 500ms」
    核心服务日志:「我耗时 800ms」
    知识服务日志:「我耗时 1200ms」
    → 谁慢?无法串联判断,各自看各自
  
  有 trace:
    一次请求一个 traceId,所有服务上报都带它
    → traceId 串联:代理层 50ms + 核心 200ms + 知识 1200ms + ...
    → 知识服务是慢节点,定位!
​

关键概念:trace 的价值在「串联」——让一次请求在多服务间的旅程可追踪。这在第 8 章八步管道跨核心服务/知识服务时尤其重要:召回要查核心服务、toolize 要查知识服务,没有 trace 就不知道「召回的 200ms 里,哪个服务慢」。

二、OpenTelemetry:trace 的标准

系统用 OpenTelemetry(OTel)作为 trace 标准。OTel 是可观测性的通用标准:

OpenTelemetry 的角色
  标准:定义 trace 的格式与传播方式
  SDK:各语言实现,埋点上报
  后端无关:可同时喂给多个后端(Langfuse/Opik/ClickHouse)
  
  → OTel 是「生产者」,三路后端是「消费者」
​

OTel 的「后端无关」是关键——它让「三路独立后端」成为可能。各服务只需用 OTel 埋点(一次),OTel 负责把 trace 同时导出给 Langfuse、Opik、ClickHouse。不必为每个后端单独埋点。

三、trace 如何跨服务传播

trace 跨服务传播靠的是「请求头里带 traceId」:

trace 传播机制
  代理层发起请求,生成 traceId = "abc123"
    ↓
  调用核心服务时,请求头带:traceparent: "abc123"
    ↓
  核心服务收到,从 traceparent 提取 traceId
    核心服务的上报都带 traceId = "abc123"
    ↓
  核心服务调知识服务,同样带 traceparent
    知识服务的上报也带 traceId = "abc123"
    ↓
  → 所有服务的上报共享同一 traceId → 串联
​

这种「请求头带 traceId」的传播,让一次请求无论经过多少服务,都能用同一 traceId 串联。OTel 定义了标准的传播头(traceparent),各服务的 OTel SDK 自动处理。

四、trace 如何喂给三路后端

OTel 的多后端导出,让 trace 同时喂给三路:

trace 喂给三路
  一次请求的 trace(带 traceId + 各 span)
    ↓ OTel 导出器
    ├─ 导出给 Langfuse → 看链路(各 span 串联)
    ├─ 导出给 Opik → 看评估(会话级)
    └─ 导出给 ClickHouse → 看成本(token 聚合)
  
  → 一次埋点,三路消费,互不影响
​

💡 技巧:这就是为什么三路后端能「互不干扰」——它们消费同一份 trace,但各自用适合自己的方式索引和查询。Langfuse 按 trace 树查链路,ClickHouse 按 team 聚合查成本。OTel 作为「生产者」解耦了埋点与后端,这是「三路独立」的技术基础。

五、用 trace 定位故障的实操

故障排查时,trace 是「定位神器」。典型流程:

trace 定位故障流程
  现象:某次请求特别慢(用户反馈)
    ↓
  拿到 traceId(从用户会话或日志)
    ↓
  在 Langfuse 按 traceId 查:
    → 看各 span 耗时
    → 定位:知识服务 span 1200ms(异常)
    ↓
  深入知识服务 span:
    → 是 Wiki 检索慢?CodeGraph 查询慢?
    ↓
  定位到具体慢点 → 优化
​

⚠️ 注意:trace 排查的前提是「各服务都正确埋点并传播 traceId」。如果某个服务漏了埋点(没上报 span),或没传播 traceId(断了链),trace 就不完整。生产部署要验证「trace 链完整」——这是可观测性的基础设施,漏了会让故障排查退回「瞎猜」状态。

本节要点回顾

1. trace 的价值:串联跨服务旅程,定位「谁慢」——无 trace 各服务日志独立,有 trace 精确定位。
2. OTel 是标准:定义格式 + 传播 + 多后端导出,后端无关,让三路独立成为可能。
3. 传播机制:请求头带 traceparent,各服务提取并上报,共享 traceId 串联。
4. 喂给三路:一次埋点,OTel 导出给 Langfuse/Opik/ClickHouse,互不影响。
5. 故障定位:traceId → 看 span 耗时 → 定位慢服务 → 深入慢操作 → 优化;前提是埋点链完整。

下一节看生产级的安全保障——v3 严格隔离四元组。