把 Metrics、Logs、Traces 串成证据链:Trace Context、Exemplar 与 Service Graph

Hello,我是小兔大白糖。 Prometheus、Loki 和 Tempo 都有数据,不代表三类信号已经关联。值班时如果仍要先抄时间,再猜服务名,最后从几百条日志里找请求,这套系统只是把数据放在了三个地方。
真正可用的关联,要让同一次调查沿着证据自然前进:
P99 告警 → 异常时间桶 → 代表性 Trace → 慢 Span → 同一执行上下文的日志
这篇把这条路径拆成一组可验证的合同:W3C Trace Context 怎样传播,HTTP、Kafka 和 WebSocket 为什么不能套同一种模型,Resource 属性怎样统一,日志怎样注入 trace_id,Exemplar 与 Service Graph 又会怎样受到 Sampling 影响。
【示例场景·合成数据】
文中的服务名、链路、日志、Trace ID、配置和故障均为教学示例,不对应任何组织、产品或真实事件。文章不包含账号、区域、域名、资源规格、真实业务字段或容量数据。
估计阅读时间:20 分钟
目录
先沿“传播、命名、关联、采样、验证”阅读,能避免只会配置跳转,却解释不清数据边界。
- 先定目标:关联不是把三个数据源放进 Grafana
- W3C Trace Context:先把一次执行认成同一条链
- HTTP、Kafka、WebSocket:传播规则不能一刀切
- 统一 Resource:服务与环境名称是一份跨信号合同
- 日志关联:trace_id 是字段,不是 Loki Label
- Exemplar:指标只跳到一条代表性 Trace
- Service Graph:观测拓扑不是部署全图
- Sampling:先说明样本,再解释 Trace 派生指标
- Grafana:六处配置合成双向调查路径
- 安全:传播上下文不等于信任上下文
- 合成验证:把关联能力变成可重复测试
- 常见失败
- 小结
- 落地前按版本核对
- 公开参考
先定目标:关联不是把三个数据源放进 Grafana
Metrics 用来缩小时间与影响面,Traces 用来拆开单次执行,Logs 用来补充离散细节;关联的目标是缩短证据路径,不是把三类数据混成一种。
三类信号各有不可替代的职责:
| 信号 | 最适合回答 | 不能天然保证 |
|---|---|---|
| Metrics | 什么时候异常、范围多大、趋势是否持续 | 某一次请求为什么慢 |
| Traces | 一次执行经过哪里、耗时落在哪个 Span | 采样后仍代表全流量 |
| Logs | 某一步发生了什么、错误与状态细节 | 低成本计算长期全局分位 |
理想路径从指标开始,但不要求每次都依赖 Exemplar。如果面板没有可用 Exemplar,还可以按 service、route 和时间范围筛选 Trace,再用 trace_id 查日志。区别只是调查步骤更多,不代表系统完全不可用。
【目标设计】
关联能力的验收标准不是“Grafana 有三个 Data Source”,而是值班者不复制 ID、不手调时间范围,也能从异常指标进入一条相关 Trace,再从 Span 进入对应日志,并返回到服务指标。
W3C Trace Context:先把一次执行认成同一条链
同步调用要在每一跳提取并注入同一份 Trace Context;只创建 Span、不传播上下文,会得到多个互不相干的 Trace。
W3C Trace Context 定义两个核心传播字段:
traceparent:携带版本、Trace ID、父 Span ID 和 Trace Flags;tracestate:携带厂商扩展的 Trace 状态,可选。
OpenTelemetry 的 Propagator 负责把这些字段写入 Carrier,并在下游提取。Carrier 是承载上下文的协议容器:HTTP 使用 Header,Kafka 通常使用 Record Header,其他协议则需要自己的映射。
traceparent 的 sampled flag 只表示上游的记录决定,不是授权结果,也不代表请求可信。服务仍要独立完成认证、鉴权、限流和输入校验。
W3C Baggage 是另一套传播规范。它可以携带跨服务业务上下文,但不会因为与 Trace Context 一起传播就自动安全。Baggage 只应放低敏、短小、受控的字段,不能塞 Token、Cookie、邮箱、手机号、原始用户 ID 或消息正文。
HTTP、Kafka、WebSocket:传播规则不能一刀切
HTTP 适合父子 Span,消息系统常需要 Span Link,WebSocket 则必须区分握手、长连接和单条消息。
HTTP:入口提取,出口注入
HTTP 服务端从入站 Header 提取 Context,再创建 Server Span;客户端在发出下游请求前,把当前 Context 注入 Header 并创建 Client Span。
自动埋点可以完成大部分工作,但反向代理、自定义 HTTP Client、重试封装和异步回调仍可能切断上下文。验证时不要只看“有 Span”,还要确认上下游 Span 的父子关系和 Trace ID 符合预期。
Kafka:传播消息创建上下文
Kafka Producer 应把消息创建上下文写入 Record Header,Consumer 提取后再创建 Receive 或 Process Span。当前 OpenTelemetry Messaging 语义约定优先使用 Span Link 关联 Producer 与 Consumer,原因是消息可能被批量处理、重试、扇出,或在另一个活动 Context 中消费,而一个 Span 只能有一个 Parent。
这带来一个重要区别:关联完整不等于所有异步 Span 必须共享同一个 Trace ID。 如果 Consumer 创建新 Trace,并通过 Span Link 指向消息创建上下文,证据链仍然成立。强行把跨越数小时或数天的任务拖成一个超长 Trace,反而会降低查询和保留体验。
Producer 重试、中间库转发和死信处理都要保留或明确重建传播字段。不能让某一层把业务 Header 整体覆盖,也不能把未经验证的消息 Header 当成可信身份。
WebSocket:握手之后没有通用 Header
WebSocket 握手仍是 HTTP,可以产生正常的 Server Span。协议升级后,单条 Frame 没有可随意添加 W3C HTTP Header 的通用位置;如果业务需要跨端关联,只能在受控的消息信封或子协议中定义 Context 字段。
不要让一个连接 Span 存活几小时,再把所有消息都挂在下面。更稳妥的做法是:
- 握手记录连接建立结果;
- 关键命令或业务消息创建短 Span;
- 必要时用 Link 关联握手、入站请求或异步任务;
connection_id只进入受控日志或 Trace 属性,不进入 Metrics Label。
统一 Resource:服务与环境名称是一份跨信号合同
传播解决“是不是同一次执行”,Resource 解决“这些数据来自哪个服务和环境”;两者缺一不可。
OpenTelemetry Resource 描述产生遥测数据的实体。至少应统一下面这些属性:
| 属性 | 用途 | 约束 |
|---|---|---|
service.name | 逻辑服务身份 | 同一横向扩容服务保持一致 |
service.version | 发布版本 | 使用可追溯但不含敏感信息的版本值 |
deployment.environment.name | 开发、测试、预发布、生产等环境 | 不能替代 service.name 的唯一性 |
service.instance.id | 区分同时运行的实例 | 高基数,只用于需要实例级定位的信号 |
k8s.namespace.name | Kubernetes 命名空间 | 统一映射到日志与查询标签 |
k8s.pod.name | Pod 级定位 | 适合 Trace/日志上下文,不默认进入应用指标标签 |
service.name 在 OpenTelemetry Resource 语义中是必填逻辑身份。若 SDK 最终退回 unknown_service,Service Graph、Trace 搜索和 Trace-to-Logs 都会变得不稳定。
【经验建议】
给服务名建一份小型注册表或 CI 白名单。
core-api、core_api和core-api-service看似相近,在查询和 Service Graph 中却是三个服务。采集层可以补 Kubernetes 元数据,但不应替应用猜测业务服务名。
跨信号不一定使用同一个字段拼写。Resource 中可能是 service.name,Loki 稳定标签可能映射成 service_name,Prometheus 则可能使用 service。这没有问题,但映射必须明确、版本化,并被 Grafana 关联配置复用。
日志关联:trace_id 是字段,不是 Loki Label
结构化日志应自动带上当前 trace_id 和 span_id,但不能把每个 ID 都变成 Loki 索引标签。
一个脱敏 JSON 日志可以长这样:
{
"level": "error",
"service_name": "core-api",
"message": "dependency request failed",
"dependency": "event-bus",
"trace_id": "7f3a9c1e4b2d48f6a0c3e5d7b9f10234",
"span_id": "2a4c6e8f0b1d3f57"
}日志库应从当前执行 Context 自动读取 ID。让每个调用点手工传 trace_id,很容易在异步回调或错误分支里漏掉。没有活动 Span 时,字段可以为空或不输出,不要生成一个与 Trace 后端无关的随机 ID。
在 Loki 中,trace_id 应留在 JSON 字段或 Structured Metadata,不作为 Stream Label。Grafana Loki Data Source 再通过 Derived Fields 提取它,并建立指向 Tempo 的 Internal Link。
从 Tempo 返回日志时,优先用 service.name、命名空间、Pod 与 Span 时间范围构造 LogQL。时间窗口要在 Span 前后留出余量,以容忍时钟偏差、日志批处理和写入延迟。
Exemplar:指标只跳到一条代表性 Trace
Exemplar 是聚合指标旁的一条代表性测量,不是“每个指标样本都有一条 Trace”。
当 Histogram 或 Counter 在活动 Span 中记录测量时,支持 Exemplar 的 SDK 和导出链可以把 Trace ID 附在部分测量旁。Prometheus 保存 Exemplar 后,Grafana 能在曲线上显示可点击标记,并跳转到对应 Trace。
这条链要同时满足:
- 指标 SDK 或客户端能从当前 Context 附加 Exemplar;
- 指标导出、接收和存储链保留 Exemplar;
- Grafana Prometheus Data Source 把 Exemplar 字段链接到 Tempo;
- 对应 Trace 被采样并在保留期内可查询。
以 client_golang 为例,普通 Observe() 不会自动读取 OpenTelemetry Context。应用必须显式使用 ExemplarObserver 一类 API 附加 Trace ID,promhttp Handler 还要启用 OpenMetrics;系列第 02 篇给出了最小实现。没有这两步,“应用正在 Trace”并不会自动让 Histogram 带上 Exemplar。
Exemplar 很适合从 P95/P99 时延分布进入一条慢请求,但它有三条边界:
- 只代表一个具体测量,不能证明整个时间桶都具有相同根因;
- 不保证每个异常桶都存在 Exemplar;
- Trace 被采样丢弃或过期后,跳转会失效。
因此,Exemplar 是快捷入口,不是完整索引。面板仍要保留按服务、路由和时间范围搜索 Trace 的备用路径。
Service Graph:观测拓扑不是部署全图
Service Graph 根据到达生成器的 Span 关系推导调用边,只能展示“被埋点并被观察到的通信”。
Tempo Metrics Generator、Grafana Alloy 或 OpenTelemetry Collector 可以检查 Client/Server、Producer/Consumer 等 Span 关系,生成 Prometheus 兼容的调用边、请求量、失败和时延指标。
生成质量依赖以下合同:
- Context 或消息创建上下文确实传播;
service.name稳定;- Span Kind 与语义约定大致正确;
- 两端 Span 保留生成器能够配对的父子关系;
- Span 在生成之前没有被丢弃;
- 生成结果成功写入指标后端。
这里必须把 Trace 关联和 Service Graph 配对分开。当前 OpenTelemetry Messaging 语义默认使用 Span Link 关联 Producer 与 Consumer,而 Tempo、Alloy 和 OpenTelemetry Collector 的常见 Service Graph Processor 依赖 Parent-Child 关系配对两端。只有 Link、甚至 Consumer 位于新 Trace 时,Trace 调查仍能成立,但不能据此期待自动生成消息调用边。
没有流量、没有埋点、被过滤或在采样前丢弃的依赖都不会出现。一个数据库如果只产生 Client Span,可能以虚拟节点出现;一条部署存在但近期没有请求的边,也可能不在图上。
所以 Service Graph 是观测拓扑,不是 CMDB、网络策略或部署清单。它适合发现真实调用关系与相对变化,不适合证明“系统中不存在其他依赖”。
Sampling:先说明样本,再解释 Trace 派生指标
只要派生指标的输入已经被采样,它描述的就是样本;除非完整证明生成位置、采样概率和修正方法,否则不能称为全流量事实。
两种常见采样方式各有代价:
| 策略 | 决策时机 | 优点 | 代价 |
|---|---|---|---|
| Head Sampling | Trace 开始时 | 简单、开销低、容易保持一致决定 | 无法预知最终错误和整条链耗时 |
| Tail Sampling | 收集到全部或大部分 Span 后 | 可优先保留错误、慢请求和关键路径 | 需要等待、内存、队列和按 Trace 一致路由 |
派生指标的解释取决于生成位置:
- 应用原生 RED:直接在请求路径计数,通常最适合作为全量告警事实源;
- Collector 采样前生成:Collector/Alloy 在自身的概率采样或 Tail Sampling 之前生成 Span Metrics,覆盖的是成功到达该连接器的已埋点 Span 流;
- Tempo ingestion 派生:Tempo Metrics Generator 从进入 ingestion path 的 Span 派生指标,原始计数和拓扑受所有上游采样与丢弃影响。
即使在采样前生成,也只能称为“已埋点且成功到达生成器的观测流量”,不能自动等同于业务账本。SDK 丢 Span、传播中断、连接器过载和未埋点协议仍会制造缺口。
SDK Head Sampling 在 Span 导出之前发生。被 SDK 丢弃的 Span 不会到达 Collector,任何下游 Connector 都无法补回。因此,图中的“Connector 后采样”只表示 Collector 侧概率采样或 Tail Sampling;若要让 Connector 看到完整的已埋点流量,SDK 必须先导出这些 Span。
固定概率采样可以在满足条件时做比例修正,但 Tail Sampling 会偏向错误、慢请求或特定属性,不能用一个统一倍数还原。告警和 Dashboard 必须标明指标来源、生成位置与采样策略。
Sampling 还直接影响关联体验:Exemplar 指向的 Trace 必须被保留;Tail Sampler 必须把同一 Trace 的 Span 路由到能共同做决定的位置;健康检查和高频噪声可以降采样,但错误与慢请求的保留规则也会增加采集层状态和成本。
Grafana:六处配置合成双向调查路径
Grafana 的关联能力来自多个 Data Source 之间的显式合同,不会因为 Prometheus、Loki 和 Tempo 同时在线就自动出现。
| 配置位置 | 方向 | 关键合同 |
|---|---|---|
| Prometheus Exemplar | Metrics → Trace | Exemplar 中的 Trace ID 链到 Tempo |
| Loki Derived Fields | Logs → Trace | 从统一 trace_id 字段提取并建立 Internal Link |
| Tempo Trace to Logs | Trace → Logs | Resource 到 Loki 标签的映射、时间余量、可选 Trace/Span ID 过滤 |
| Tempo Trace to Metrics | Trace → Metrics | 用服务、环境、Span 属性构造已有指标查询 |
| Tempo Service Graph | Trace 拓扑 → Metrics | 指向包含 Service Graph 指标的 Prometheus Data Source |
| Dashboard Data Links | Metrics → 调查入口 | 保留服务、环境、路由和时间范围 |
Trace to Metrics 不要求指标必须由 Tempo 生成。它可以链接应用原生 RED,只要两边共享稳定的服务、环境和路由语义。反过来,Service Graph 需要链接到真正保存对应派生指标的 Prometheus 兼容数据源。
【目标设计】
把 Data Source Provisioning、字段映射、时间余量和 Dashboard Data Link 纳入版本管理。每次改服务名、日志字段或标签映射时,同时运行合成关联测试,而不是等值班时发现链接返回空结果。
关联查询还要控制范围。Trace-to-Logs 如果只按时间查全环境日志,既慢又容易越权;如果只按 Pod 精确匹配,Pod 已重建或标签缺失时又可能漏查。更稳的顺序是先用环境与服务缩小范围,再按 Trace ID 精确过滤。
安全:传播上下文不等于信任上下文
外部传入的 traceparent、tracestate 和 Baggage 都是不可信输入,只能用于可观测关联,不能参与授权或业务决策。
安全边界至少包括:
- 使用标准 Propagator 解析并拒绝非法长度与格式,不手写宽松解析器;
- 在公网或跨组织边界清理不允许的
tracestate与 Baggage; - 对 Baggage 建白名单、大小上限和下游传播范围;
- 不把 Token、Cookie、个人信息、消息正文或自由文本放进传播字段;
- 不允许外部 Header 强制生产环境 Always Sample;
- 对 Trace、日志和关联链接实施租户隔离、访问控制与保留策略;
- 对认证等高敏边界,按威胁模型决定是否重启 Trace,而不是机械透传。
Trace ID 虽然不是用户身份,但它能把多个系统中的记录关联起来。导出、工单和截图仍要脱敏,Grafana 跨数据源链接也必须继承正确权限,不能让一次跳转绕过日志或 Trace 后端的访问边界。
合成验证:把关联能力变成可重复测试
用一条受控合成链路反复验证传播、命名、存储和跳转,比人工点开几张 Dashboard 更可靠。
【示例场景·合成数据】
一条教学链路从
edge-gateway进入core-api,发布到event-bus,由task-worker处理,再通过realtime-gateway发送状态。测试只使用固定的合成场景名,不携带真实用户、租户、任务或消息内容。
可以把验收拆成十步:
- 由受信测试客户端创建根 Span,并向 HTTP 入口发送请求;
- 入口与下游 HTTP Span 共享预期 Trace Context;
- Producer Record Header 中存在合法消息创建上下文;
- Consumer Span 与 Producer 通过约定的 Parent 或 Span Link 关联;
- WebSocket 握手与关键消息按约定建立短 Span 或 Link;
- 所有服务都带统一
service.name与环境 Resource; - 结构化日志能查到对应
trace_id,且没有敏感字段; - RED Histogram 出现可查询的 Exemplar;
- Grafana 的 Metrics、Trace、Logs 双向链接都返回结果;
- HTTP/RPC 父子 Span 形成预期 Service Graph 边;Link-only 消息链单独验证可检索关系,并允许图中缺边。
预发布环境可以给合成场景独立的保留策略,确保测试 Trace 不被随机丢弃。生产环境不要接受客户端传来的“强制采样”开关;如需生产合成监测,应由受控入口、内部签名或采集层策略识别,并限制比例和权限。
自动化结果不必比较整份 Trace JSON。更稳定的断言是:关键服务存在、HTTP 父子关系正确、消息 Link 存在、Resource 值符合白名单、日志可反查、Exemplar 目标可查询、敏感字段扫描为零。消息 Link 验证通过与 Service Graph 出边是两项独立断言。
常见失败
关联失败通常不是某个后端完全不可用,而是传播、命名、采样或字段映射在接缝处断开。
| 现象 | 常见原因 | 下一步 |
|---|---|---|
| Tempo 中出现多个孤立 Trace | 下游没有提取或注入 Context | 检查客户端、中间件和代理传播 |
| Kafka Consumer 找不到 Producer | Header 被覆盖,或 Parent/Link 模型不一致 | 检查消息创建上下文和语义约定版本 |
| 日志能看见 ID,却不能跳 Trace | 字段名、正则、大小写或 Data Source Link 不一致 | 统一 trace_id 并测试 Derived Field |
| Trace-to-Logs 返回空结果 | Resource 与 Loki 标签映射错误,或时间窗口太窄 | 核对服务映射并增加前后余量 |
| Exemplar 点开后 Trace 不存在 | Trace 未保留、已过期或 ID 字段映射错误 | 对照采样和保留周期 |
| Service Graph 缺边 | 传播断开、Span Kind 不匹配、Link-only 消息关系、无流量或已采样 | 从父子关系和生成器输入逐跳验证 |
| 派生 QPS 明显偏低 | 指标在采样后生成 | 标注样本口径,改到采样前生成或使用应用 RED |
| Loki 时序或索引膨胀 | 把 trace_id、连接 ID 或实体 ID 做成 Label | 移到日志字段或 Structured Metadata |
| Tail Sampling 丢失完整 Trace | 同一 Trace 的 Span 没有一致路由 | 检查负载均衡、等待时间、队列与内存 |
小结
三信号关联的根基是传播合同、命名合同和采样解释,Grafana 跳转只是把这些合同呈现出来。
- HTTP 逐跳提取与注入 W3C Trace Context;Kafka 优先传播消息创建上下文,并按语义使用 Span Link;
- WebSocket 握手与消息要分开建模,长连接不能机械变成超长 Trace;
service.name和环境 Resource 必须稳定,跨信号字段映射要显式版本化;- 日志自动注入
trace_id与span_id,但高基数 ID 不进入 Loki 或 Prometheus Label; - Exemplar 只提供代表性 Trace,不保证每个异常桶都有可用样本;
- Service Graph 是受埋点、父子关系、生成位置和 Sampling 影响的观测拓扑;Link-only 消息关联可能不出边;
- Trace 派生指标只有在证明输入覆盖后才能解释,不能默认当作全流量事实;
- 用合成请求同时验证传播、日志、Exemplar、Grafana 跳转和敏感字段,才能把关联能力变成工程合同。
落地前按版本核对
以下细节依赖 OpenTelemetry、Grafana、客户端库和部署版本,正文保留了稳定原则,没有把版本相关字段写成永远不变的事实。
- 核对目标语言与 Kafka 客户端使用的 OpenTelemetry Messaging Semantic Conventions 版本,以及 Producer、Receive、Process Span 的 Parent/Link 关系;Kafka 语义约定仍可能演进。
- 核对目标 WebSocket 库是否自动创建握手或消息 Span;升级后的消息 Context 信封属于应用协议,必须单独定义兼容和安全规则。
- 核对当前 Grafana 版本中 Prometheus Exemplar、Loki Derived Fields、Tempo Trace to Logs/Trace to Metrics 和 Service Graph 的 Provisioning 字段名;界面能力稳定,但配置 Schema 可能变化。
- 验证 Exemplar 在所用 Metrics SDK、OTLP/Prometheus 导出链和指标后端中的保留行为,以及对应 Trace Sampling 策略能否保证链接可查询。
- 确认 Span Metrics 与 Service Graph 的实际生成位置是否早于任何 Head/Tail Sampling、过滤或丢弃;未核对这条路径前,不得把派生计数用于全流量告警或对账。
公开参考
以下公开规范和文档用于核对传播、日志关联、采样、Exemplar 与 Grafana 配置边界。
- W3C Trace Context
- W3C Baggage
- OpenTelemetry Context Propagation
- OpenTelemetry Service Resource Semantic Conventions
- OpenTelemetry Deployment Resource Semantic Conventions
- OpenTelemetry Messaging Spans
- OpenTelemetry Kafka Semantic Conventions
- OpenTelemetry Trace Context in non-OTLP Logs
- OpenTelemetry Sampling
- Prometheus Exemplars
- Grafana Tempo Data Source
- Grafana Trace to Logs
- Grafana Trace to Metrics
- Grafana Tempo Service Graphs
- Grafana:Choose where to generate metrics from traces