Prometheus 中 Summary 是客户端本地滑动分位数估算，不存原始样本；必须显式配置 Objectives、MaxAge 和 AgeBuckets，Observe 应在业务完成路径调用，高基数场景适用但不支持多维聚合。
Summary 类型在 Prometheus 客户端库中的定位
Go 里用 prometheus.NewSummary 创建的指标，本质是客户端本地聚合——它不存原始样本，只在内存里维护分位数（如 0.5、0.9、0.99）的滑动估算值。这意味着：你不能像 Gauge 或 Counter 那样查“某个时间点的值”，而只能查“过去一段时间内请求耗时的 P99 是多少”。如果你需要精确回溯单次调用耗时，Summary 不适合，得换 Histogram 或日志采样。
初始化 Summary 必须传入 Objectives 和 MaxAge
漏设 Objectives 会导致默认只暴露 0.5/0.9/0.99 分位，但更关键的是：不设 MaxAge 和 AgeBuckets 会让滑动窗口失效，分位数统计逐渐漂移甚至卡死。常见错误写法：
prometheus.NewSummary(prometheus.SummaryOpts{
Name: "http_request_duration_seconds",
Help: "HTTP request duration in seconds",
})正确做法要显式控制窗口和精度：
prometheus.NewSummary(prometheus.SummaryOpts{
Name: "http_request_duration_seconds",
Help: "HTTP request duration in seconds",
Objectives: map[float64]float64{
0.5: 0.05, // P50 允许误差 ±5%
0.9: 0.01, // P90 允许误差 ±1%
0.99: 0.001, // P99 允许误差 ±0.1%
},
MaxAge: 10 * time.Minute,
AgeBuckets: 5,
BufCap: 1000,
})-
MaxAge决定滑动窗口时长，太短（如 30s）会让低频服务统计失真；太长（如 24h）会拖慢内存回收 -
BufCap是采样缓冲区大小，突增流量可能丢点，但设太大又吃内存 - 误差值（
0.05等）不是百分比，而是绝对误差范围，单位与观测值一致
Observe 调用必须在业务逻辑完成之后
最常踩的坑是把 Observe 放在 handler 开头或 defer 里，结果统计的是“从开始到 panic 的耗时”，而非真实处理耗时。正确姿势是确保值来自实际完成的业务路径：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
func handler(w http.ResponseWriter, r *http.Request) {
start := time.Now()
defer func() {
// ❌ 错误：panic 时也会触发，且无法获取真实耗时
summaryVec.WithLabelValues("get_user").Observe(time.Since(start).Seconds())
}()
// ... 业务逻辑
if err := doSomething(); err != nil {
http.Error(w, err.Error(), 500)
return // ✅ 必须在这里 return，否则 defer 仍执行
}
// ✅ 正确：只在成功路径 Observe
summaryVec.WithLabelValues("get_user").Observe(time.Since(start).Seconds())
}- 避免在
defer中直接Observe，除非你能保证所有分支都明确控制流程 - 如果 handler 有多个出口（如重定向、提前返回），每个出口前都要
Observe，或统一用middleware封装 - 注意
time.Since返回的是time.Duration，传给Observe前必须转成秒级float64
Summary 与 Histogram 在高基数场景下的取舍
当 label 组合爆炸（比如带 user_id 或 request_id），Summary 比 Histogram 更省内存，因为它不维护桶（buckets），但代价是：无法在 PromQL 里做多维度聚合（如 sum by (path) (http_request_duration_seconds)）。而 Histogram 虽然占内存多，却支持 rate()、histogram_quantile() 等灵活计算。
- 高频低基数（如 API path、status code）→ 优先
Histogram - 低频或超高基数（如 trace_id、client_ip）→ 只能用
Summary，且建议限制 label 值数量 - 如果用
SummaryVec，务必检查label_values是否可控，否则 OOM 风险极高
真正难的不是怎么写这行 Observe，而是想清楚你要回答的问题到底是什么：是要看“整体 P99”，还是“某个用户群的 P99”，或是“对比两个版本的延迟分布”——选错类型，后面所有查询和告警都会跑偏。
