Exemplar 是什么
Exemplar 是附加在样本上的标注元数据，典型做法是携带 trace_id：看到延迟毛刺时从指标直接跳到对应链路，把指标与追踪两支柱串起来。它常用在延迟直方图上，价值在于把「这里慢了」与「慢在哪一步」之间的距离缩短成一次点击。要让它工作，链路上三处必须同时具备条件：服务端开启 exemplar 存储、抓取侧协商到 OpenMetrics 格式、展示侧开启 Exemplars 显示。
基本信息
| 服务端开关 | --enable-feature=exemplar-storage，默认关闭 |
|---|---|
| 抓取侧条件 | 需协商到 OpenMetrics 格式 |
| 应用侧来源 | OpenTelemetry 客户端观测直方图时可自动携带 trace_id |
| 展示侧 | Grafana 面板开启 Exemplars 开关 |
| 存储特点 | 容量单独限制，与常规样本相互独立 |
典型使用场景
- 延迟毛刺定位：从直方图上的 exemplar 点跳到对应链路，看清慢在哪一步
- 失败请求排查：错误计数器附带出错请求的 trace_id，快速捞到具体调用
- 指标链路闭环：指标侧发现问题、链路侧定位原因，减少中间猜测
- 采样抽查：抽看 exemplar 对应的链路，确认采样策略没有漏掉关键路径
- 团队演示：用联查路径降低新人对工具链的使用门槛
使用要点
- 只给关键延迟直方图附带 exemplar，控制存储开销并保持信噪比
- 确认抓取走的是 OpenMetrics 格式，否则收不到 exemplar
- exemplar 不会出现在普通查询结果里，只能在支持它的界面中查看
- 存储容量独立且有限，海量直方图都带 exemplar 会互相挤占
- 应用侧要保证 trace_id 与链路后端使用的是同一个标识
启用与使用
启用与使用
# 服务端开启 exemplar 存储（默认关闭）
prometheus --enable-feature=exemplar-storage
# 抓取侧：协商到 OpenMetrics 格式才会收到 exemplar
# 应用侧：观测直方图时附带当前 trace_id（OpenTelemetry 客户端可自动携带）
# 展示侧：Grafana 面板开启 Exemplars 开关，毛刺点可跳转到链路后端四处条件
| 环节 | 需要做什么 | 不满足时的表现 |
|---|---|---|
| 服务端 | 开启 exemplar 存储 | 接收后丢弃，界面看不到标记 |
| 抓取侧 | 协商 OpenMetrics 格式 | 样本里根本没有 exemplar |
| 应用侧 | 观测时附带 trace_id | 有标记但无法跳转链路 |
| 展示侧 | 面板开启 Exemplars | 数据在但看不到入口 |
| 链路后端 | 标识保持一致 | 跳转过去查不到对应链路 |
通常只给关键延迟直方图附带 exemplar：既能覆盖主要排查路径，又能把存储开销控制在可接受范围内。