Go服务暴露Prometheus指标需用promhttp.Handler()注册/metrics路由，避免手写响应；正确选型Counter/Gauge/Histogram，防重复注册panic，确保HTTP服务启动前完成指标注册与挂载。
Go服务怎么暴露Prometheus指标端点
直接在HTTP服务里加一个/metrics路由，用promhttp.Handler()就行，别自己拼字符串或写JSON。这个Handler会自动处理Content-Type、gzip压缩、HEAD请求，还能跟Prometheus的scrape timeout和sample limit配合好。
常见错误是手写http.HandleFunc("/metrics", ...)然后用fmt.Fprintln(w, "# HELP...")——这样既不兼容Prometheus的文本格式版本协商（如Accept: application/openmetrics-text; version=1.0.0），又没法正确响应406或503。
- 必须用
promhttp.Handler()或promhttp.HandlerFor(reg, opts)，注册前确保prometheus.DefaultRegisterer或自定义Registry已初始化 - 如果用了Gin/Echo等框架，别用
gin.WrapH(promhttp.Handler())这种“套壳”方式，而是走中间件或显式路由，避免路径匹配冲突（比如/metrics/xxx被意外匹配） - 生产环境建议加简单认证（如Basic Auth），但不要在
promhttp.Handler()外再套一层鉴权逻辑——它本身不处理auth，得由上层HTTP handler统一拦截
哪些指标该用Counter、Gauge还是Histogram
选错类型会导致查询结果完全失真，而且后期改类型要重打所有历史数据（Prometheus不支持类型变更）。
Counter只增不减，适合总请求数、错误总数；Gauge可升可降，适合当前并发数、内存使用量；Histogram不是“直方图”而是分桶计数器，适合响应时间、队列长度这类带分布特征的指标——别用Gauge去模拟P99，那是反模式。
立即学习“go语言免费学习笔记（深入）”；
- HTTP请求总量用
prometheus.NewCounterVec，标签至少含method和status - 活跃goroutine数用
prometheus.NewGaugeFunc包装runtime.NumGoroutine()，避免采样时锁竞争 - API响应时间必须用
prometheus.NewHistogramVec，且Buckets要按实际P99预估设（比如[]float64{0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10}秒），别直接用默认的DefBuckets（最大才10秒，线上服务早超了）
Go SDK注册指标时为什么总panic: "duplicate metrics collector"
根本原因是同一个指标名（包括label名和值组合）被多次MustRegister，最常见于：全局变量+init函数重复执行、单元测试里没清理registry、微服务多实例共用同一份metric定义但没做命名隔离。
比如在pkg/metrics/metrics.go里写var ReqCounter = prometheus.NewCounterVec(...); init() { prometheus.MustRegister(ReqCounter) }，当这个包被两个不同子模块import，就注册两次。
- 所有
NewXXX指标对象应定义为私有变量（小写开头），暴露Register(r prometheus.Registerer)方法，由主程序统一调用 - 单元测试用
prometheus.NewPedanticRegistry()替代DefaultRegisterer，它会在重复注册时panic并给出完整调用栈 - 如果服务启多个HTTP server（如admin port + api port），别让两个server都注册同一组指标——指标是进程级的，注册一次就够了
Prometheus拉取Go服务指标超时或返回空数据
不是网络问题，大概率是Go服务没真正监听/metrics，或者监听了但没启动HTTP server，又或者promhttp.Handler()挂载到了错误的mux上。
典型现象：curl http://localhost:8080/metrics返回404，但curl http://localhost:8080/healthz能通；或者返回200但内容为空（只有# HELP没有# TYPE和样本行）。
- 检查
http.ListenAndServe(":8080", nil)是否传了nil——这会用http.DefaultServeMux，而你的promhttp.Handler()可能挂到了自定义mux上 - 确认
prometheus.MustRegister()在http.ListenAndServe之前执行，否则指标还没注册就被拉取了 - 用
curl -v http://localhost:8080/metrics 2>&1 | head -20看响应头，如果Content-Length: 0或Transfer-Encoding: chunked但body为空，基本是registry里没指标（比如忘记调Register()，或指标对象没被任何代码引用导致GC）
最麻烦的是指标注册了但值一直是0——这时候得查instrumentation代码里有没有漏掉.Inc()或.Observe()调用，尤其是error handling分支里常被遗忘。
