Go中注册自定义Counter指标需先用prometheus.NewCounterVec定义(带标签)或NewCounter(无标签),再调用prometheus.MustRegister()显式注册,且必须在init()或main()开头完成;未注册则/metrics不可见,重复注册会panic。

Go里怎么注册一个自定义Counter指标?
直接用 prometheus.NewCounter 创建,但必须调用 prometheus.MustRegister 才能被暴露出去,否则 /metrics 里根本看不到。
常见错误是只声明不注册,或者重复注册同名指标导致 panic(Prometheus 不允许重名)。
- 指标名称必须全小写、用下划线分隔,比如
http_request_total,不能含空格或大写字母 - 推荐在
init()或main()开头一次性注册,避免热重载时出问题 - 如果需要带标签(label),用
prometheus.NewCounterVec,然后通过WithLabelValues("api", "200")打点
var httpRequestTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "http_request_total",
Help: "Total number of HTTP requests",
},
[]string{"method", "status"},
)
func init() {
prometheus.MustRegister(httpRequestTotal)
}
// 使用
httpRequestTotal.WithLabelValues("GET", "200").Inc()
Gauge 和 Counter 的核心区别在哪?什么时候该用Gauge?
Counter 只能增、不能减、不能设值;Gauge 支持增、减、设任意值。别用 Counter 去统计当前活跃连接数——它没法反映连接断开后数量下降的事实。
典型误用场景:把在线用户数、内存使用量、goroutine 数量用 Counter 上报,结果曲线只升不降,监控完全失真。
-
Inc()/Dec()适合变化频繁的瞬时状态,比如 goroutine 数量波动 -
Set(123.4)适合从外部采集的绝对值,比如当前 RSS 内存字节数 - Gauge 同样要
MustRegister,且命名习惯加_current或_in_bytes后缀,比如go_goroutines_current
Histogram 怎么配 buckets 才不算瞎写?
默认的 prometheus.DefBuckets(0.005~10秒)对 HTTP 延迟可能合适,但对数据库查询或本地函数耗时往往完全不匹配——大部分打点落在第一个 bucket 或全挤在最后一个,直方图失去分析价值。
关键不是“多配几个 bucket”,而是根据实际 P90/P99 延迟分布来定。先用临时 Gauge 打几分钟延迟样本,看分布再反推 bucket 边界。
- bucket 边界必须严格递增,且类型为
[]float64,例如[]float64{0.01, 0.025, 0.05, 0.1, 0.25, 0.5} - 别漏掉
+Inf,它是必需的,否则histogram_quantile()在 PromQL 里会计算失败 - Histogram 自带
_sum和_count指标,不用额外定义;但要注意_bucket是累积计数,不是每个区间的独立值
var httpLatency = prometheus.NewHistogram(prometheus.HistogramOpts{
Name: "http_request_duration_seconds",
Help: "HTTP request duration in seconds",
Buckets: []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10},
})
为什么指标注册后还是不出现在 /metrics?
最常被忽略的是:没把 promhttp.Handler() 挂到 HTTP 路由上。Prometheus client 不会自动起服务,你得手动暴露端点。
另一个隐蔽问题是:多个包各自定义同名指标(比如都叫 http_requests_total),MustRegister 会 panic;而用 Register 则静默失败(返回 error 但没人检查)。
- 确保
http.Handle("/metrics", promhttp.Handler())已调用,且端口已监听 - 启动时加
log.Fatal(http.ListenAndServe(":2112", nil))这类语句,别只写路由没跑服务 - 调试时 curl 一下
curl localhost:2112/metrics,看是否返回文本格式指标,以及有没有你的指标名 - 如果用了模块化初始化(如按 handler 分文件),确认所有
init()函数都被执行到了——Go 不会自动加载未引用的包
真正麻烦的从来不是写几行指标代码,而是让指标在正确的时间、以正确的维度、稳定地出现在 Prometheus 里。尤其是 label 组合爆炸、bucket 设置偏离实际、或注册时机错乱,这些问题在线上压测时才突然暴露,但日志里连 warning 都没有。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











