最直接可靠的方式是用 prometheus/client_golang 启动独立 HTTP metrics 端点，通过 promhttp.Handler() 暴露 /metrics，避免手动拼接或混入业务路由；自定义指标须按语义选 Counter/Gauge/Histogram；禁用 Pushgateway 于长服务。
Go 程序想暴露指标供 Prometheus 抓取，最直接可靠的方式是用 prometheus/client_golang 官方库启动一个 HTTP metrics 端点——不是手动拼接文本格式，也不是自己实现 /metrics 路由逻辑。
用 promhttp.Handler() 暴露标准 metrics 端点
这是最常见也最推荐的做法。Prometheus 官方客户端已内置符合规范的文本格式生成器和 HTTP handler，只需注册到 HTTP server 即可。
关键点：
- 必须使用
promhttp.Handler()（不是http.HandlerFunc自己写）——它自动处理 Accept 头、gzip 压缩、Content-Type 和指标格式校验 - 不要把 metrics handler 和业务路由混在同一个
http.ServeMux里再用http.ListenAndServe；建议单独开一个监听地址（如:9091），避免干扰主服务 - 若程序已用
gin/echo等框架，需调用其Use或GET注册时，仍应包裹promhttp.Handler()实例，而非裸写 handler 函数
package main
import (
"log"
"net/http"
"github.com/prometheus/client_golang/prometheus"
"github.com/prometheus/client_golang/prometheus/promhttp"
)
func main() {
// 注册自定义指标
httpRequestsTotal := prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "http_requests_total",
Help: "Total number of HTTP requests.",
},
[]string{"method", "status"},
)
prometheus.MustRegister(httpRequestsTotal)
// 单独启动 metrics server
go func() {
http.Handle("/metrics", promhttp.Handler())
log.Println("Metrics server started on :9091")
log.Fatal(http.ListenAndServe(":9091", nil))
}()
// 主业务逻辑（略）
select {}
}
自定义指标类型选 Counter、Gauge 还是 Histogram？
选错类型会导致 PromQL 查询结果异常或聚合语义错误，比如用 Gauge 记请求计数，会导致 rate() 计算失败。
立即学习“go语言免费学习笔记（深入）”；
典型场景对应关系：
-
Counter：只增不减的累计值，如http_requests_total、db_queries_total—— 必须用Inc()或Add() -
Gauge：可升可降的瞬时值，如go_goroutines、memory_usage_bytes—— 可用Set()、Inc()、Dec() -
Histogram：观测分布（如请求耗时），自动分桶并提供_sum/_count/_bucket—— 用Observe(float64)，别手写分桶逻辑
注意：Summary 不适合服务端监控（client-side only），且无法被 rate() 正确聚合，生产环境优先用 Histogram。
上报延迟高或抓取失败？检查 scrape_timeout 和 handler 阻塞
Prometheus 默认 scrape_timeout 是 10s，但若你的 /metrics handler 执行超过该时间，就会报 context deadline exceeded 错误。
常见诱因：
- 指标收集逻辑中做了同步 IO（如查 DB、调外部 API）——必须移出 handler，改用定时采集+缓存（如用
prometheus.NewGaugeFunc） - 大量指标未做
WithLabelValues预分配，每次调用都新建 label map —— 触发 GC 压力，拖慢响应 - 多个 goroutine 并发写同一
Counter但没用prometheus.NewCounterVec分离维度，导致锁竞争
验证方式：用 curl -v http://localhost:9091/metrics 测延时；加 log.Printf("metrics handler start") / end 看是否卡住。
需要推送到 Pushgateway？仅限批处理/短生命周期任务
Pushgateway 是反模式，仅适用于无法长期运行的服务（如 Cron Job、CI 脚本）。长期运行的 Go 服务必须走 Pull 模型（即暴露 /metrics 端点）。
若真要用：
- 必须设置
job+ 唯一instance标签，否则多次推送会覆盖前值 - 避免用
PushAdd，改用PushCollectors显式管理 collector 生命周期 - 推送后记得调
pusher.Delete()清理过期指标，否则 Pushgateway 内存泄漏
绝大多数 Web 服务不需要 Pushgateway，强行用只会让监控链路变脆弱、数据时效性下降、调试更困难。
真正容易被忽略的是：指标命名必须带单位（如 _seconds、_bytes）、label 维度不宜过多（超过 5 个 label 组合易爆炸）、以及所有自定义指标必须显式 MustRegister——漏注册等于没上报。
