直接暴露/metrics端点不等于完成监控；必须显式注册Go运行时指标（如go_goroutines）、合理设计标签维度（如用c.FullPath()标准化路径）、设置符合业务延迟分布的HistogramVec分桶，否则将导致指标缺失、序列爆炸或告警失真。
直接暴露 /metrics 端点不等于完成监控 —— Gin 应用要真正产出可用、可聚合、可告警的指标，必须解决标签维度缺失、直方图分桶不合理、中间件注册顺序错误这三类高频问题。
为什么 promhttp.Handler() 单独挂载会丢指标？
Gin 默认不自动注册 Go 运行时指标（如 go_goroutines、go_memstats_alloc_bytes），仅挂载 promhttp.Handler() 只能返回空或极简数据。Prometheus 客户端默认不会自动收集运行时指标，需显式调用 prometheus.MustRegister() 或使用 promauto 包初始化。
- 错误写法：
http.Handle("/metrics", promhttp.Handler())—— 无任何自定义指标，且 Go 运行时指标未注册 - 正确做法：在应用启动时注册基础指标，例如：
prometheus.MustRegister(prometheus.NewGoCollector()) - 更推荐用
promauto：它会在首次访问时自动注册，避免手动MustRegister时机错乱（比如在 goroutine 中提前调用）
CounterVec 和 HistogramVec 的标签设计陷阱
标签（[]string{"method","path","status"}）不是越全越好，滥用会导致时间序列爆炸，尤其当 path 含动态参数（如 /user/123、/order/abc-def）时，每个 ID 都生成独立序列，内存和查询压力陡增。
- 路径应做标准化：用正则或 Gin 的
c.FullPath()替换动态段，例如将/api/v1/user/:id统一为/api/v1/user/{id} - 避免在
status标签里包含 500+ 具体错误码（如500_internal_error），优先归类为5xx；否则一个异常 panic 就可能刷出几十个新序列 -
HistogramVec的Buckets必须覆盖真实业务延迟分布：若 99% 请求耗时 []float64{0.005,0.01,...,10}，前几个桶长期为 0，P99 计算失真
Gin 中间件里埋点的执行时机与 panic 处理
监控中间件必须包裹整个请求生命周期，包括 recover 流程，否则 panic 会导致耗时统计中断、状态码未记录、Counter 漏加。
- 中间件必须在
defer中调用observe()，且recover()后仍要更新指标（比如 status 标为500） - 不要在中间件里直接调用
http.Error()或c.Abort()后就 return —— 这会跳过后续指标上报逻辑 - 示例关键结构：
func PrometheusMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
c.Next() // 执行后续 handler，含 panic 可能
status := c.Writer.Status()
duration := time.Since(start).Seconds()
httpRequestsTotal.WithLabelValues(
c.Request.Method,
strings.ReplaceAll(c.FullPath(), "/", "_"), // 标准化 path
strconv.Itoa(status),
).Inc()
httpRequestDuration.WithLabelValues(c.Request.Method, c.FullPath()).Observe(duration)
}
}
注意：c.Next() 后才获取 status 和 duration，这才是真实响应结果。
生产环境必须关闭的调试行为
本地开发时习惯开启 gin.DebugMode，但它会注入额外中间件（如重定向、日志），干扰耗时统计；同时 promhttp.Handler() 默认不压缩响应，大指标集传输慢，易触发 Prometheus 抓取超时。
- 上线前确认：
gin.SetMode(gin.ReleaseMode) - 对
/metrics路由启用 gzip：用gzip.Gzip(gzip.BestSpeed)包裹promhttp.Handler() - 限制抓取频率：Prometheus 配置中
scrape_interval不建议低于15s，太密会压垮小内存 Gin 实例 - 别把
/metrics暴露在公网 —— 至少加 Basic Auth 或 IP 白名单，指标里可能含路径特征、错误率等敏感模式
最常被忽略的一点：Gin 的 c.FullPath() 在路由未匹配时返回空字符串，导致所有 404 请求挤进同一个 "" 标签，掩盖真实问题。务必在中间件开头判断 c.IsAborted() == false 再采集，或单独为 404 做 fallback 标签。
