promhttp.handler()需精确匹配/metrics路径，自定义指标必须显式注册到默认注册器，且网络配置、label设计、生命周期管理不当会导致grafana查不到数据。
为什么 promhttp.Handler() 不能直接注册到 http.DefaultServeMux？
因为 promhttp.Handler() 返回的是一个标准 http.Handler，但默认 mux 对路径匹配是前缀式（prefix-match），而 Prometheus 客户端要求精确匹配 /metrics。如果用 http.Handle("/metrics", promhttp.Handler()) 却没加结尾斜杠或路径冲突，就可能返回 404 或被其他路由劫持。
- 务必使用
http.Handle("/metrics", promhttp.Handler())，而不是http.HandleFunc - 避免在路径末尾加多余斜杠（如
"/metrics/"），否则采集器会 404 - 如果你用了
gorilla/mux或chi，要确保路由定义为r.Get("/metrics", promhttp.Handler())这类显式方法限制 - 启动服务后，手动 curl
curl http://localhost:8080/metrics验证是否返回文本格式指标（以# HELP开头）
如何让自定义指标在 Grafana 里可查，又不被 promhttp.Handler() 漏掉？
Go 的 Prometheus 客户端默认只暴露 go_* 和 process_* 这类运行时指标；你写的 prometheus.NewCounterVec 之类，必须显式注册到全局注册器（prometheus.DefaultRegisterer），否则 promhttp.Handler() 根本看不到它们。
- 注册必须在 handler 启动前完成：
prometheus.MustRegister(yourCounter) - 不要自己 new 一个
prometheus.Registry后忘了传给promhttp.HandlerFor，除非你明确要隔离指标 - 命名要符合规范：小写字母、下划线分隔、带应用前缀（如
myapp_http_request_total），否则 Grafana 查询时容易和其他指标混淆 - 注意指标生命周期 —— 在 HTTP handler 里反复调用
NewCounterVec而不复用，会导致内存泄漏和重复注册 panic
Grafana 查不到数据？先检查 scrape_configs 里的 job_name 和 target 是否匹配
Prometheus 不会自动发现你的 Go 服务；它靠配置里的 scrape_configs 主动拉取。常见问题是 job 名写成 go-app，但 Grafana 数据源里选了 prometheus，或者 target 地址写成 localhost:8080，而 Prometheus 容器根本访问不到宿主机的 localhost。
- target 必须是 Prometheus 可达的地址：Docker 网络内用
host.docker.internal:8080（Mac/Win），Linux 用宿主机真实 IP 或network_mode: host -
job_name建议和你的服务名一致（如job_name: "auth-service"），后续 Grafana 查询时用{job="auth-service"}过滤更稳 - 加个
metrics_path: "/metrics"显式声明，别依赖默认值 - 在 Prometheus UI 的
Status > Targets页面确认该 target 是 UP 状态，且 Last Scrape 是几秒前，不是 “context deadline exceeded”
HTTP 中间件里埋点，为什么 counter 值总为 0？
因为很多中间件示例把 counter.Inc() 放在 defer 或 response 写完之后，但 handler panic、超时、连接中断时，那行代码根本不会执行；更隐蔽的问题是，用 http.ResponseWriter 包装后没正确透传 WriteHeader，导致状态码永远是 200，status_code label 全是 200。
立即学习“go语言免费学习笔记（深入）”；
- 计数器应在进入 handler 时就
Inc()，而不是等响应结束 —— 请求来了就得记一笔 - 状态码统计要用
responseWriter.Status()（需包装实现http.ResponseWriter接口），不能读w.Header().Get("Status") - 路径聚合建议用正则归一化（如
/user/123→/user/:id），否则每个 ID 都生成独立时间序列，cardinality 爆炸 - 别在中间件里做耗时操作（如打日志到磁盘），会影响
promhttp.Handler()的 /metrics 响应延迟，进而触发 Prometheus 抓取超时
Golang 指标集成里最麻烦的从来不是写几行注册代码，而是指标生命周期管理、网络可达性判断、以及 label 维度设计是否真的支撑后续查询 —— 这些地方一错，Grafana 里就只剩空面板。
