重试日志结构化记录与指标监控:Prometheus中retry_total与retry_duration

文章导读
这类问题的核心不是把重试次数堆到一个计数器上,而是让日志和指标表达同一个重试事件。retry_total 适合回答“重试发生了多少次”,retry_duration 适合回答“重试过程花了多久、分布在哪一段”。先确认当前重试逻辑发生在哪个服务、哪一层,再决定怎么埋点;如果两者口径不一致,之后所有告警和 dashboard 都会失真。
📋 目录
  1. 壹 先确认重试发生在哪一层
  2. 贰 检查点:日志和指标为什么对不上
  3. 叁 埋点口径与一个最小示例
  4. 肆 验证信号
  5. 伍 保留可排查性的边界
A A

这类问题的核心不是把重试次数堆到一个计数器上,而是让日志和指标表达同一个重试事件。retry_total 适合回答“重试发生了多少次”,retry_duration 适合回答“重试过程花了多久、分布在哪一段”。先确认当前重试逻辑发生在哪个服务、哪一层,再决定怎么埋点;如果两者口径不一致,之后所有告警和 dashboard 都会失真。

先确认重试发生在哪一层

重试可能出现在 HTTP 客户端、RPC 拦截器、数据库连接池、消息消费逻辑里。不同位置的埋点成本不同:

  • HTTP/RPC 客户端:通常在拦截器或中间件统一处理,适合给请求加重试计数和耗时统计。
  • 消息消费:重试往往写在业务代码里,需要手动埋点,否则日志里看到重试但指标没有。
  • 数据库/缓存客户端:部分客户端自带重试参数,不会输出结构化日志;需要单独记录是否发生重试。

建议先查最近的重试日志,找到具体的重试调用点,再开始加指标。

检查点:日志和指标为什么对不上

现象是 retry_total 在涨,但 retry_duration 没有数据;或者日志有 retry 事件,但 Prometheus 里查不到对应指标。按下面分支排查:

  1. 如果 retry_total 有值而 retry_duration 恒为 0:检查 Observe/记录是否只在最后一次成功时执行;如果重试最终失败,这段路径可能没有走到埋点。
  2. 如果 retry_duration 是 0 但明显有 sleep:检查记录的数值单位。秒和毫秒混用会让 duration 在 dashboard 上几乎不可见。
  3. 如果日志和指标数量对不上:检查日志模块与指标采集是否共用同一个重试函数;有时候日志写在调用方,指标写在重试工具内部,导致事件错过。

处理动作是统一从重试函数返回结果,而不是在多个业务分支里各自打点。日志和指标使用同一个 reason、target、attempt 字段,便于后续把 trace_id 拼回去。结构化日志字段至少包含 event、target、reason、attempt、max_attempts、delay_ms;不要只写一句 “retrying again”。

埋点口径与一个最小示例

retry_duration 建议定义为 histogram,并且单位固定为秒。一个简化示例:

重试日志结构化记录与指标监控:Prometheus中retry_total与retry_duration
from prometheus_client import Counter, Histogram

retry_total = Counter(
    "retry_total",
    "累计重试次数",
    ["service", "target", "reason"]
)
retry_duration = Histogram(
    "retry_duration_seconds",
    "重试决策耗时",
    ["service", "target", "reason"],
    buckets=(0.05, 0.25, 0.5, 1, 2.5, 5)
)

def record_retry(service, target, reason, delay_seconds):
    retry_total.labels(service, target, reason).inc()
    retry_duration.labels(service, target, reason).observe(delay_seconds)

关键位置在于 record_retry 只接受 delay_seconds,不接收毫秒值;调用方在写入前完成单位转换。如果把整个重试周期算为 duration,需要改成记录开始时间,并在最终成功或失败时计算差值,不能只记录 sleep 时间。

验证信号

配置完成后,先确认真实请求能触发重试,再在 Prometheus 中验证:

# 重试速率
sum(rate(retry_total[5m])) by (service)

# 重试耗时 P90
histogram_quantile(0.9, sum(rate(retry_duration_seconds_bucket[5m])) by (le))

如果看到 histogram_quantile 返回 NaN,通常是 sum by(le) 里混入了非 le 标签,或桶的边界没有覆盖到实际耗时。此时先观察 retry_duration_seconds_count 是否大于 0,再检查 bucket 上界。

保留可排查性的边界

不要把所有重试相关标签都放进指标。trace_id、request_id、url 中的动态参数一旦成为 label,会快速推高基数,最终拖垮 Prometheus。建议只保留 service、target、reason 这类有限集合;trace_id 只放到结构化日志里。日志和指标靠 event 发生时间、service、target、reason 关联,而不是靠完全相同的标签集合。

另外,retry_total 是 counter,适合只增不减;如果业务需要按结果区分,可以增加 result="success|give_up" 标签。需要结合环境确认告警阈值,不建议直接写死在文章里。