可观测性与稳定性 / 系统课时
用 Exemplar 关联 Trace 与 Metric
用 Exemplar 关联 Trace 与 Metric
指标能告诉你“哪里变慢了”,Trace 能告诉你“这一次为什么慢”。Exemplar 把聚合指标中的代表性测量与产生它的 Trace 关联起来,让你从延迟或错误峰值直接下钻到具体请求,而不必把 trace_id 变成高基数指标标签。
学习目标
- 解释 Exemplar 与普通指标数据点、Trace 之间的关系。
- 说清
TraceBased过滤器和 Exemplar Reservoir 各自负责什么。 - 判断哪些指标值得保留 Exemplar,以及什么时候应关闭或收紧采样。
Exemplar 补上了哪条关联链
普通指标通常是聚合结果。例如请求延迟直方图只保留桶计数、总次数和总和,查询时看到的是某个时间窗口“整体变慢”,却不知道是哪一次请求造成了异常。把每个请求的 trace_id 直接放进指标标签虽然能关联 Trace,却会制造几乎每次请求都不同的高基数时间序列。
Exemplar 的做法不同:指标仍按低基数属性聚合,只在数据点旁保留少量代表性原始测量。一个 Exemplar 可以包含测量值、时间戳、可选的 trace_id 与 span_id,以及没有进入聚合时间序列的 filtered attributes。对直方图和 Sum 来说,Exemplar 的值已经包含在原聚合结果中,它不是额外增加的一次测量。
一条测量如何成为 Exemplar
当应用在活动 Span 的上下文中记录指标测量时,Metric SDK 先完成正常聚合,同时把测量交给 Exemplar 采样逻辑。ExemplarFilter 只决定“是否有资格成为候选样本”;候选进入 ExemplarReservoir 后,Reservoir 才决定本轮最终保留哪几个样本,因此启用 Exemplar 并不意味着每次测量都会被导出。
使用 TraceBased 时,只有处于 sampled parent Span 上下文中的测量才有资格成为 Exemplar。被保留下来的样本随指标导出,后端若支持 Exemplar,就可以从指标峰值上的样本读取 trace_id、span_id,再去 Trace 后端定位完整调用链。

这条链路的关键是“聚合和关联并行”:Metric 负责回答异常是否普遍,Exemplar 提供少量可追踪的具体样本,Trace 再解释这些样本为什么慢或为什么失败。
用 TraceBased 控制候选样本
OpenTelemetry SDK 的标准环境变量 OTEL_METRICS_EXEMPLAR_FILTER 可表达三种策略:trace_based、always_on 和 always_off。默认采用 trace_based 时,Exemplar 与现有 Trace 采样决策对齐,通常比让所有测量都成为候选更适合作为生产默认值。
export OTEL_METRICS_EXEMPLAR_FILTER=trace_based
printf 'exemplar_filter=%s\n' "$OTEL_METRICS_EXEMPLAR_FILTER"预期输出:
exemplar_filter=trace_based这条命令只验证进程环境变量已设置;真正的端到端验证还要确认所用语言 SDK、指标导出器和指标后端都保留并展示 Exemplar。若链路中的任一环节丢弃 Exemplar,即使应用侧已经采样,也无法从指标跳转到 Trace。
什么时候值得保留
Exemplar 最适合“先从聚合异常发现问题,再需要具体请求解释原因”的指标,例如 HTTP/RPC 延迟直方图、队列等待时长、数据库调用耗时等。此时少量代表样本可以显著缩短从 P95/P99 峰值到慢 Trace 的定位路径。
如果 Trace 本身几乎不采样、指标后端不支持 Exemplar,或团队没有从指标下钻 Trace 的排障流程,保留 Exemplar 的收益会很低。遇到敏感属性风险、额外传输与存储预算受限时,可以改用 always_off;always_on 则应在明确需要扩大候选范围并评估开销后再使用,而不是为了“采得更多”默认开启。
正确的心智模型是:Exemplar 不是新的指标维度,也不是完整 Trace 的副本,而是附着在聚合指标上的少量上下文锚点。只要 Trace 采样、Metric 导出和后端展示三端都连通,它就能把“这个时间窗口很慢”快速落到“这一次请求为什么慢”。