必须引入 prometheus/client_golang，它提供注册器、指标封装和 http handler；需用 v1.19.0+ 版本避免并发 panic；指标须单次注册到同一 registry，挂载 /metrics 路径并确保反向代理透传 accept 头。
Go服务暴露/metrics端点需要什么基础依赖
必须引入 prometheus/client_golang，这是官方维护的 Go 客户端库。它提供注册器（prometheus.Registry）、指标类型封装和 HTTP handler。别用第三方轻量实现——它们常缺失注册冲突检测、Goroutine 指标自动采集等关键能力。
最小依赖声明示例：
go get github.com/prometheus/client_golang/prometheus@v1.19.0 go get github.com/prometheus/client_golang/prometheus/promhttp@v1.19.0
- 版本建议锁定 v1.19.0 或更高（修复了 1.17 前的
CounterVec并发 panic） - 不需要手动
import _ "net/http/pprof"——promhttp.Handler()不依赖 pprof - 避免混用
prometheus.DefaultRegisterer和自定义Registry，否则指标重复注册报错：duplicate metrics collector registration attempted
如何正确注册自定义指标并避免goroutine泄漏
所有指标（Gauge、Counter、Histogram）必须通过同一个 Registry 注册，且**只注册一次**。反复调用 MustRegister() 会 panic；用 Register() 则返回 error，但容易被忽略。
典型安全写法：
立即学习“go语言免费学习笔记（深入）”；
var (
httpReqTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "http_requests_total",
Help: "Total number of HTTP requests.",
},
[]string{"method", "status_code"},
)
)
<p>func init() {
// 必须在 init 或 main 开头注册，且仅一次
if err := prometheus.Register(httpReqTotal); err != nil {
// 检查是否已被注册（比如被测试代码提前注册过）
if _, ok := err.(prometheus.AlreadyRegisteredError); !ok {
panic(err)
}
}
}- 不要在 HTTP handler 里创建新指标（如每次请求 new 一个
Histogram），会导致内存持续增长 - 若需按动态标签打点（如用户 ID），用
WithLabelValues("GET", "200")，而非拼接字符串构造新指标 - 全局变量声明指标时加
var，别用:=，否则测试中重载包可能造成注册器状态混乱
HTTP handler 配置常见错误与路径选择
标准做法是挂载 promhttp.Handler() 到 /metrics，但实际部署中常因路径配置翻车：
- 反向代理（Nginx / ALB）默认不透传
Accept: application/openmetrics-text，导致 Prometheus 抓取失败：检查响应头是否含Content-Type: text/plain; version=0.0.4 - 误将 handler 挂到
/api/metrics等带前缀路径，而 Prometheus 配置的metrics_path仍是默认/metrics→ 抓取 404 - 用
http.Handle("/metrics", promhttp.Handler())时，若前面有中间件（如 JWT 鉴权），需确保该路径放行，否则返回 401 - Kubernetes 中 Service 的 readiness probe 若指向
/metrics，可能因采集耗时触发重启——应单独开/healthz
推荐启动时显式绑定：
http.Handle("/metrics", promhttp.Handler())
log.Println("Metrics server listening on :9090")
log.Fatal(http.ListenAndServe(":9090", nil))本地验证与生产环境抓取调试要点
别等 Prometheus 上线才验证——用 curl 直接看原始输出最可靠：
curl -H 'Accept: text/plain' http://localhost:9090/metrics | head -20
重点关注：
- 首行是否为
# HELP http_requests_total Total number of HTTP requests.（无 HELP 行说明指标未注册） - 是否有
go_开头的运行时指标（如go_goroutines），没有说明prometheus.MustRegister(prometheus.NewGoCollector())漏了 - 自定义指标值是否随请求变化（如刷新几次后
http_requests_total{method="GET",status_code="200"} 5变成6） - Prometheus 抓取日志中若出现
server returned HTTP status 503 Service Unavailable，大概率是 handler 被其他中间件拦截或超时
真实问题往往藏在细节：比如 Counter 在 goroutine 中异步更新却没加锁，导致数值跳变；或者 Histogram 的 Buckets 设得太窄，99% 的样本全挤进最后一个 bucket。这些不会报错，但会让监控失去意义。
