这类问题的核心不是把重试次数堆到一个计数器上,而是让日志和指标表达同一个重试事件。retry_total 适合回答“重试发生了多少次”,retry_duration 适合回答“重试过程花了多久、分布在哪一段”。先确认当前重试逻辑发生在哪个服务、哪一层,再决定怎么埋点;如果两者口径不一致,之后所有告警和 dashboard 都会失真。
先确认重试发生在哪一层
重试可能出现在 HTTP 客户端、RPC 拦截器、数据库连接池、消息消费逻辑里。不同位置的埋点成本不同:
- HTTP/RPC 客户端:通常在拦截器或中间件统一处理,适合给请求加重试计数和耗时统计。
- 消息消费:重试往往写在业务代码里,需要手动埋点,否则日志里看到重试但指标没有。
- 数据库/缓存客户端:部分客户端自带重试参数,不会输出结构化日志;需要单独记录是否发生重试。
建议先查最近的重试日志,找到具体的重试调用点,再开始加指标。
检查点:日志和指标为什么对不上
现象是 retry_total 在涨,但 retry_duration 没有数据;或者日志有 retry 事件,但 Prometheus 里查不到对应指标。按下面分支排查:
- 如果 retry_total 有值而 retry_duration 恒为 0:检查 Observe/记录是否只在最后一次成功时执行;如果重试最终失败,这段路径可能没有走到埋点。
- 如果 retry_duration 是 0 但明显有 sleep:检查记录的数值单位。秒和毫秒混用会让 duration 在 dashboard 上几乎不可见。
- 如果日志和指标数量对不上:检查日志模块与指标采集是否共用同一个重试函数;有时候日志写在调用方,指标写在重试工具内部,导致事件错过。
处理动作是统一从重试函数返回结果,而不是在多个业务分支里各自打点。日志和指标使用同一个 reason、target、attempt 字段,便于后续把 trace_id 拼回去。结构化日志字段至少包含 event、target、reason、attempt、max_attempts、delay_ms;不要只写一句 “retrying again”。
埋点口径与一个最小示例
retry_duration 建议定义为 histogram,并且单位固定为秒。一个简化示例:
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" 标签。需要结合环境确认告警阈值,不建议直接写死在文章里。