golang如何集成Prometheus自定义指标_golang Prometheus自定义指标集成指南-Golang-PHP中文网

必须显式调用 prometheus.mustregister() 注册指标，否则 /metrics 中不可见；自定义注册器需用 promhttp.handlerfor()；标签名全小写下划线，避免高基数；hpa 需 rate() 而非原始 counter；seriesquery 必须与代码中 name 完全一致；直方图需按真实延迟设 buckets。

golang如何集成prometheus自定义指标_golang prometheus自定义指标集成指南

必须显式注册，否则 `/metrics` 里根本看不到你的指标

很多人跑通了 http.Handle("/metrics", promhttp.Handler())，一访问 http://localhost:8080/metrics 却只看到 go_* 和 process_*，自己的 http_requests_total 消失得无影无踪——这不是 Prometheus 没抓到，是你压根没把它“交出去”。promhttp.Handler() 只暴露注册在默认注册器上的指标，而 Go SDK 创建的指标对象（比如 prometheus.NewCounterVec）只是个空壳，不调 prometheus.MustRegister() 就等于没申报。

别在 init() 里定义指标又忘了注册；更糟的是在多个包里 import 同一个 metrics 包，导致重复 MustRegister，直接 panic：duplicate metrics collector
如果用了自定义注册器（比如 reg := prometheus.NewRegistry()），就一定用 promhttp.HandlerFor(reg, ...)，而不是默认的 promhttp.Handler()
标签名必须全小写、下划线分隔、不以数字开头；值里别塞 user_id="12345" 这种高基数字段，否则 Prometheus 存储会爆炸

`Counter` 不能直接给 HPA 用，`rate()` 才是真实速率

你在 Go 里定义了 my_app_http_requests_total，Prometheus 能采到，但一旦想让 Kubernetes HPA 基于它自动扩缩容，就会发现 HPA 一直不触发——因为 HPA 需要的是“每秒请求数”，而 Counter 是累计值。Adapter 规则里若写 metricQuery: "my_app_http_requests_total"，查出来的是 127489 这种不断增长的大整数，HPA 完全无法理解。

Adapter 的 rules.yaml 中，metricQuery 必须包装函数：比如 rate(my_app_http_requests_total[2m])
seriesQuery 必须和你 Go 代码中定义的 Name 字段**完全一致**，包括大小写和下划线，少一个字符 Adapter 就查不到
resources 字段不能空着，必须指定 template: "pod{{.Resource}}" 或 overrides，否则 Adapter 启动直接报错：resource mapping not defined

别手写 `/metrics` handler，也别用框架“套壳”

有人为了加鉴权或日志，在 promhttp.Handler() 外再包一层 http.HandleFunc，或者在 Gin/Echo 里写 router.GET("/metrics", gin.WrapH(promhttp.Handler()))——这会导致 Accept 头协商失败、gzip 不生效、甚至返回 406 Not Acceptable。Prometheus 的文本格式有版本协商机制（如 Accept: application/openmetrics-text; version=1.0.0），手写的 handler 根本不处理。

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

坚持用 promhttp.Handler() 或 promhttp.HandlerFor(reg, opts)，这是唯一能正确响应各种 Content-Type 和错误码的方式
需要 Basic Auth？在 mux 层拦截，比如 mux.Handle("/metrics", withAuth(promhttp.Handler()))，不要侵入 Handler 内部逻辑
别把 /metrics 挂在带参数的路由下（如 /api/v1/:id/metrics），Adapter 和 Prometheus 的 scrape 都依赖固定路径匹配

直方图 `Buckets` 设错，P99 就永远不准

HTTP 延迟监控最常用 prometheus.NewHistogramVec，但很多人直接用默认 DefBuckets（最大才 10 秒），结果线上 P99 显示是 10s，实际接口早超 30s 了——因为所有 ≥10s 的样本全被塞进最后一个桶，分位数计算彻底失真。

根据你服务真实的延迟分布设 Buckets，比如：[]float64{0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30}
别用 Gauge 模拟 P99：有人定时算一次 p99 再 Set()，这既不是实时的，也无法做跨实例聚合，是反模式
直方图的 Observe() 必须传秒为单位的 float64，别传毫秒再除 1000 时丢精度，建议统一用 time.Since(start).Seconds()

最难的从来不是写对一行 MustRegister，而是让指标从 Go 进程里出来、被 Prometheus 抓到、再经 Adapter “翻译”成 HPA 能懂的语言——中间任何一环的命名、标签、函数、配置错一位，整条链就断在黑盒里。调试时先盯紧 Prometheus Targets 页面是否 UP，再查 Graph 里能不能 rate(your_metric_name[1m]) 出来数值，最后看 Adapter logs 有没有 no series found。顺序不能乱。