Go服务中暴露Prometheus指标需要引入promhttp Handler
不手动实现/metrics端点，而是直接复用官方promhttp.Handler()——它自动聚合所有已注册的prometheus.Collector（如Gauge、Counter等），并按文本格式输出。自行拼接字符串或JSON会导致格式不兼容，Prometheus Server拉取失败。
常见错误是只调用prometheus.MustRegister()却没挂载HTTP handler，结果请求/metrics返回404；或者用http.HandleFunc写死响应体，导致Content-Type错为text/plain; charset=utf-8但内容不符合OpenMetrics规范。
- 必须使用
http.Handle("/metrics", promhttp.Handler())（或http.ServeMux等效方式） - 若用
gorilla/mux，需写成r.Handle("/metrics", promhttp.Handler()).Methods("GET") - 不要在handler里加额外中间件（如JWT鉴权），Prometheus Server默认无认证，加了反而拉不到
自定义指标要先声明再注册，且类型不能混用
比如想监控HTTP请求耗时，得先定义prometheus.HistogramVec，再通过prometheus.MustRegister()注册到默认注册表。声明和注册必须成对出现，否则Handler()里查不到该指标。
容易踩的坑：把Counter当Gauge用（比如用Inc()记录当前活跃连接数），或在goroutine里反复prometheus.NewCounter()却不注册——新对象不会被采集，旧对象还可能泄漏。
立即学习“go语言免费学习笔记（深入）”；
- 指标变量应定义为包级全局变量（如
var httpReqDuration = prometheus.NewHistogramVec(...)） - 注册只做一次，在
init()或main()开头调用prometheus.MustRegister(httpReqDuration) - 直方图（
Histogram）和摘要（Summary）都可统计分布，但Histogram服务端计算分位数更轻量，推荐优先用
HTTP中间件中打点需注意goroutine安全与标签一致性
在HTTP handler中间件里调用Observe()或Inc()是常规操作，但要注意两点：一是prometheus.HistogramVec的WithLabelValues()返回值不是线程安全的，每次都要重新获取；二是标签值不能含非法字符（如空格、斜杠），否则指标上报后会被Prometheus Server静默丢弃。
func metricsMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
next.ServeHTTP(w, r)
statusCode := w.Header().Get("status") // 实际需用ResponseWriter装饰器捕获状态码
httpReqDuration.WithLabelValues(r.Method, r.URL.Path, statusCode).Observe(time.Since(start).Seconds())
})
}- 避免在
WithLabelValues()中传入用户输入的原始r.URL.Path，应先正则替换为固定路由模式（如/user/{id}） -
状态码建议统一用
strconv.Itoa(statusCode)，防止"200 OK"这类带空格的值污染指标名 - 如果用了
net/http/pprof，它的/debug/pprof/路径不应被指标中间件统计，需显式跳过
本地验证指标格式是否合法只需curl + 检查响应头和body
启动服务后，直接curl -v http://localhost:8080/metrics，重点看三点：响应状态码是否200、Content-Type是否为text/plain; version=0.0.4; charset=utf-8、body里是否有以# HELP和# TYPE开头的注释行，以及指标行是否符合name{label="value"} value timestamp格式。
- 若看到
invalid metric type "xxx"，说明某指标注册时类型名非法（如含大写字母或下划线） - 若指标值全是
NaN或+Inf，可能是Observe()传入了负数或非数值 - 用
promtool check metrics可批量校验：curl -s localhost:8080/metrics | promtool check metrics
真正上线前，别只信日志里“registered metric”，得亲眼看到/metrics返回有效文本——格式错一点，整个job就变DOWN。
