从一次超时排查谈起：给 HTTP 客户端加上统一的可观测性与重试边界

背景

线上偶发的接口超时，往往不是“再加一次重试”就能解决。最近排查一组内部 HTTP 调用时，我把超时、重试、熔断和埋点重新收了一遍边界，记录成这篇笔记，方便后续复用。

先把超时拆开看

很多客户端只配置了一个 timeout，但实际至少有三层：

1. 连接超时：TCP/TLS 握手是否卡住
2. 请求超时：写完请求后等多久响应头
3. 整体截止时间：包含重试在内的总预算

如果只设“读超时 3 秒”，再配“失败重试 3 次”，最坏情况可能拖到十几秒，上游网关早就断开了。更稳妥的做法是：给单次尝试设短超时，再给整条调用链设一个更短的 deadline，重试只能在 deadline 内发生。

重试要有条件

并非所有错误都该重试：

• 可重试：连接失败、限流 429（配合退避）、幂等读接口的 5xx
• 不可重试：4xx（除 408/429）、带副作用且无幂等键的写操作

实践里我会要求：

• 写操作必须带 Idempotency-Key，否则禁止自动重试
• 退避使用抖动（full jitter），避免雷群
• 把重试次数、最终错误码打进日志与指标，而不是只打“失败”

最小可观测性清单

对每个出站 HTTP 客户端，至少暴露：

• client_request_duration_seconds（直方图，带 method/host/status/outcome）
• client_retries_total
• client_timeouts_total
• trace 中的 http.client span，并传播 W3C traceparent

排查超时时，先看 p99 耗时分布在连接还是等待响应，再看重试是否把故障放大。没有这几条指标，讨论“要不要加超时”基本靠猜。

一个可落地的默认策略

小结

超时不是一个魔法数字，而是 单次尝试预算 + 总 deadline + 可重试错误集合 的组合。把这三件事和指标、链路追踪一起固化到公共 HTTP 客户端里，比在每个业务里临时 sleep + retry 要可靠得多。

（本文为个人实践笔记，示例参数请按业务 SLA 调整。）