Go服务需用promhttp.Handler()暴露/metrics端点,禁用手拼文本;Counter只增不减,Gauge表瞬时值,Histogram按P99设桶;防重复注册用独立Registry;/metrics应独立端口暴露;高基数字段不可作label。

Go 服务要被 Prometheus 正确抓到指标,核心就一条:暴露一个符合规范的 /metrics 端点,且必须用 promhttp.Handler() 或 promhttp.HandlerFor(),不能手拼文本。
为什么直接写 http.HandleFunc("/metrics", ...) 会出错
常见错误是自己用 fmt.Fprintln 输出指标文本。这会导致:
- Prometheus 抓取时返回
406 Not Acceptable或503 Service Unavailable,因为没处理Accept: application/openmetrics-text; version=1.0.0等协商头 - 响应缺少
Content-Encoding: gzip支持,大指标集传输慢甚至超时 - HEAD 请求返回 200 而不是 204,违反 Prometheus 协议要求
- 无法配合
sample_limit或scrape_timeout做安全控制
正确做法永远是:http.Handle("/metrics", promhttp.Handler()),它内部已处理全部协议细节。
Counter、Gauge、Histogram 到底怎么选
选错类型不是“效果差”,而是“数据不可用”——Prometheus 不允许改类型,历史数据全作废。
-
Counter:只增不减。适合http_requests_total、errors_total。别用它记“当前失败数”,那是反模式 -
Gauge:瞬时值。适合go_goroutines、memory_usage_bytes。可用prometheus.NewGaugeFunc包装runtime.NumGoroutine()实现自动采集 -
Histogram:不是画图用的,是分桶计数器。API 延迟必须用它,且Buckets要按实际 P99 设(比如[]float64{0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5}),别用DefBuckets(最大才 10 秒,线上早超)
注册指标时 panic: "duplicate metrics collector"
这个 panic 几乎全是重复注册导致的,根本原因就三个:
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
- 全局变量 +
init()在多个包里被 import 触发多次(比如pkg/metrics被两个不同子模块 import) - 单元测试没清理 registry,跑完 test 后指标还在默认注册器里,下次 test 再注册就冲突
-
微服务多实例共用同一份指标定义文件,但没做命名隔离(比如都叫
http_requests_total,没加 service name label)
解法很直接:用 prometheus.NewRegistry() 创建独立注册器,再传给 promhttp.HandlerFor(reg, opts);测试里用 prometheus.Unregister() 或直接 new 一个干净 registry。
框架里挂 /metrics 的坑
用 Gin/Echo/Chi 时,别用 gin.WrapH(promhttp.Handler()) 这类“套壳”方式,容易因路由匹配顺序出问题(比如 /metrics/xxx 被主路由捕获,返回 404)。
- 推荐显式注册:
r.GET("/metrics", func(c *gin.Context) { c.Status(200); c.Header("Content-Type", "text/plain; version=0.0.4"); promhttp.Handler().ServeHTTP(c.Writer, c.Request) }) - 或更稳妥:起一个独立的 HTTP server 专跑
/metrics,和业务端口分开(比如 8080 处理业务,8081 暴露指标),彻底规避中间件干扰 - 生产环境加 Basic Auth 必须在
promhttp.Handler()外层统一拦截,它本身不处理鉴权
最常被忽略的其实是标签设计——method、status 这类低基数标签没问题,但把用户 ID、订单号当 label 加进去,几小时就能撑爆 Prometheus 内存。高基数字段只能放 metric value 或 log,别进 label。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!










