如何使用Python prometheus-client为指标添加Exemplars并在Grafana可视化

问题核心原因 #

• 你将trace、span id作为普通指标标签添加的逻辑是错误的：Exemplars是绑定在指标采样点上的独立附加数据，不属于指标的标签集合，不需要定义在Counter的labelnames中
• 你调用inc()计数时没有传入Exemplars参数，底层不会生成对应的Exemplars数据
• 首先需确认你的prometheus-client库版本≥0.16.0，低于该版本没有原生Exemplars支持

修正后的埋点实现 #

无需修改原有Counter的标签定义，只需在调用inc()方法时追加Exemplars参数即可：

from prometheus_client import Counter

tasks_counter = Counter(
    name='outgoing_x_http_requests',
    documentation='counter for http requests from server x',
    labelnames=['status_code', 'method', 'path']
)

def send_X():
    # 发送请求到目标服务逻辑
    # response_object = 服务返回的响应对象
    # 此处为示例，实际需从链路上下文获取真实的trace_id和span_id
    trace_id = "实际链路trace_id值"
    span_id = "实际链路span_id值"

    tasks_counter.labels(
        status_code="200", # 替换为实际响应状态码
        method="GET", # 替换为实际请求方法
        path="/api/xxx", # 替换为实际请求路径
    ).inc(
        1, 
        # 核心配置：传入exemplars字典绑定链路数据
        exemplars={"trace_id": trace_id, "span_id": span_id}
    )

额外配置确认项 #

• Prometheus侧需开启Exemplars采集：Prometheus版本≥2.26.0，且对应抓取任务的配置中添加enable_exemplars: true
• Grafana侧配置：对应的Prometheus数据源需勾选开启Exemplars开关，指标面板的查询项要开启Exemplars展示选项
• 注意Exemplars仅会在指标值发生变化时附带生成，不会在每次Prometheus拉取时重复返回

内容的提问来源于stack exchange，提问作者hashguard