GORM SQL耗时指标必须用Histogram，因其支持分桶与分位数计算（如95%延迟），多实例可聚合；Summary客户端聚合不可加总，Gauge仅存瞬时值无法反映长尾分布。
为什么 GORM 的 SQL 耗时指标必须用 Histogram，不能用 Summary 或 Gauge
因为你要分析的是延迟分布——比如 95% 的 SQL 执行都在 300ms 内，而不是“当前最慢那条花了多久”。Histogram 支持分桶 + histogram_quantile() 计算分位数，Prometheus 多实例抓取后仍能合并统计；Summary 是客户端聚合，各副本算出的 p95 不可加总；Gauge 只存最后一次值，历史毛刺全丢，完全无法反映长尾。
常见错误是写成：prometheus.NewGaugeVec(...) 存单次耗时，结果 /metrics 里只看到一个浮动数字，查不出哪类 SQL 拖慢了整体。
怎么在 GORM v2+ 中正确注册 SQL 耗时 Histogram 指标
必须用 callbacks 或 plugin 机制，在 SQL 执行路径中埋点，不能靠日志解析或中间件（GORM 中间件不覆盖 db.Raw()）。
- 注册点要具体：用
callback.Query().After("gorm:query")、callback.Update().After("gorm:update")等，避免用泛用的callback.Process()导致重复计时 -
Buckets要覆盖真实业务延迟：OLTP 场景推荐[]float64{0.01, 0.05, 0.1, 0.3, 0.5, 1.0, 3.0, 10.0}（单位秒） - Label 必须归一化：至少含
"sql_type"（如"select"）、"table_name"；禁止用原始 SQL 文本（如"WHERE id = 123"），否则引发高基数问题
示例片段：
sqlDuration := prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "gorm_sql_duration_seconds",
Help: "SQL execution duration in seconds",
Buckets: []float64{0.01, 0.05, 0.1, 0.3, 0.5, 1.0, 3.0, 10.0},
},
[]string{"sql_type", "table_name"},
)
prometheus.MustRegister(sqlDuration)
db.Callback().Query().After("gorm:query").Register("metrics:query_duration", func(db *gorm.DB) {
if db.Statement != nil && db.Statement.Table != "" {
sqlType := "select"
if db.Statement.SQL.String() != "" && strings.HasPrefix(db.Statement.SQL.String(), "UPDATE") {
sqlType = "update"
}
sqlDuration.WithLabelValues(sqlType, db.Statement.Table).Observe(db.Statement.Duration.Seconds())
}
})
为什么 /metrics 端点看不到 GORM 的 SQL 指标
最常见原因是指标注册到了自定义 registry，但 promhttp.Handler() 默认只暴露 prometheus.DefaultRegisterer 里的指标。
如果你用了 GORM 插件（如 gorm.io/plugin/prometheus）或自己 new 了一个 registry，必须显式传给 handler：
- 错：直接用
http.Handle("/metrics", promhttp.Handler()) - 对：用
http.Handle("/metrics", promhttp.HandlerFor(yourRegistry, promhttp.HandlerOpts{}))
另外检查是否漏掉 prometheus.MustRegister(...) —— 没注册的指标永远不会出现在 /metrics 中。
GORM 连接池指标怎么暴露给 Prometheus
GORM 本身不直接暴露连接池指标，但底层 *sql.DB 提供了 Stats() 方法。你需要手动拉取并转为 Prometheus 指标：
- 定义
GaugeVec：如gorm_db_open_connections、gorm_db_idle_connections - 启动 goroutine 定期调用
db.DB().Stats()，更新对应 gauge 值 - 注意并发安全：
Stats()返回的是快照，无需锁，但更新 gauge 时要用.Set()非原子操作
别依赖 GORM 的 prometheus plugin 自带的连接池指标——它只暴露极简字段，且默认不启用，需额外配置 EnableDBStats 并手动触发采集。
真正难的不是注册几个指标，而是 label 设计和 bucket 划分是否贴合你的业务延迟水位。跑一天真实流量后，先看 histogram 的 _bucket 分布，再调 histogram_quantile(0.95, ...)，如果大部分请求都堆在最大 bucket 之外，说明 bucket 设置太窄，得扩容；如果 99% 都挤在头两个 bucket 里，说明太宽，浪费精度。
