Go服务/metrics端点数据缺失、冲突等问题主因是注册时机错误、注册器复用及网络不可达；需在main/init中显式注册业务指标，用独立Registry避免多实例冲突，并确保Prometheus配置正确指向服务地址。
Go 服务暴露 /metrics 端点本身不难，难在 Prometheus 拉不到数据、指标查不到、重启后丢失、多实例冲突——这些问题几乎都出在注册时机、注册器选择和网络可达性上，而不是代码写错。
为什么 promhttp.Handler() 返回空或只有 runtime 指标？
因为默认注册器（prometheus.DefaultRegisterer）只自动注册 Go 运行时指标（如 go_goroutines），业务指标必须显式调用 MustRegister() 才会生效。很多人写了 http.Handle("/metrics", promhttp.Handler()) 就以为完事，结果 curl 一看只有几行，http_requests_total 根本不出现。
- 确认自定义指标（如
CounterVec）是否在init()或main()开头就注册：prometheus.MustRegister(httpRequestsTotal) - 别在 handler 里注册——注册是初始化动作，不是每次请求都做
- 如果用了
promauto.NewCounter()，确保没跨包重复定义同名指标，否则启动 panic 报duplicate metrics collector registration attempted - 计数器（
Counter）初始值为 0，Prometheus 不返回零值指标，得真发起一次请求触发.Inc()才会在/metrics里看到它
多实例/热重载场景下怎么避免指标冲突？
复用 prometheus.DefaultRegisterer 是高危操作，尤其在插件化、子模块动态加载、或 fork 子进程的场景中，会导致注册器状态混乱、指标覆盖甚至 panic。正确做法是每个实例独占一个注册器。
- 创建独立注册器：
reg := prometheus.NewRegistry() - 手动注册运行时指标：
reg.MustRegister(prometheus.NewGoCollector()) - 注册业务指标：
reg.MustRegister(httpRequestsTotal) - 绑定到 handler：
promhttp.HandlerFor(reg, promhttp.HandlerOpts{}) - 不要把
reg传给其他包直接调用MustRegister——统一由主应用控制注册入口
容器或 K8s 中 Prometheus 抓不到指标？先看这三处
90% 的“Target DOWN”不是 Go 代码问题，而是网络或配置硬伤。Prometheus 容器根本访问不到你的服务，再准的指标也没用。
立即学习“go语言免费学习笔记（深入）”；
-
scrape_configs.targets别写localhost:9091：Docker 容器内localhost指自己，应改用宿主机 IP、host.docker.internal（Mac/Win）、或 K8s Service 名（如my-app:9091） - Go 服务监听地址必须是
:9091（即绑定""），不能是127.0.0.1:9091，否则外部无法连接 - 检查响应头：
Content-Type必须是text/plain; version=0.0.4（promhttp默认满足），但若你套了反向代理（如 Nginx），可能被改写，需显式设置proxy_set_header Content-Type "text/plain; version=0.0.4";
用 promauto 还是原生 prometheus.NewXXX()？
promauto 简洁，但隐含强依赖全局注册器，适合单包小项目；一旦项目变大、引入中间件或插件，就容易失控。
- 单包脚本或 demo：用
promauto.With(prometheus.DefaultRegisterer)没问题，写起来快 - 中大型项目：放弃
promauto，统一走prometheus.NewCounterVec(...)+ 显式reg.MustRegister()，把指标生命周期收归主应用 - 需要按 URL 路径、租户 ID 等动态生成指标名？
promauto不支持，必须用CounterVec+WithLabelValues()管理 label 组合
最容易被忽略的是：指标注册不是“写完就跑”，它必须发生在 HTTP server 启动前，且注册器实例不能被多个 goroutine 并发修改。哪怕只是加个中间件或换了个框架（比如 yoyogo），也要确认它是否接管了注册逻辑——别让监控在你以为它工作的时候，其实已经静默失效了。
