根本原因是业务指标未注册到Prometheus实际抓取的注册器；默认promhttp.Handler()只暴露DefaultRegisterer中的指标，而自定义指标必须显式调用MustRegister()才能被采集。
业务指标在 /metrics 里能看到，但 Prometheus 抓不到——根本不是网络或配置问题，而是指标没注册进它实际抓取的那个注册器。
为什么 promhttp.Handler() 返回数据却查不到自定义指标
默认的 promhttp.Handler() 只暴露 prometheus.DefaultRegisterer 里的指标。Go 运行时指标（如 go_goroutines、process_cpu_seconds_total）是自动注册的；但你用 prometheus.NewCounter() 或 promauto.NewCounter() 创建的业务指标，如果不显式调用 MustRegister()，就完全不在这个注册器里。
- 直接 new 一个 Counter 但漏掉
MustRegister()→ 指标压根不生效，/metrics里都看不到 - 多个包各自调用
promauto.NewCounter("http_requests_total")→ 启动 panic：duplicate metrics collector registration attempted - 热重载或 fork 子进程后复用
DefaultRegisterer→ 指标状态被覆盖，数值跳变或归零
长连接场景必须用 GaugeVec，且注册和更新要线程安全
WebSocket、gRPC streaming 等长连接服务，连接数是瞬时值，会增会减，不能用只增不减的 CounterVec。必须用 prometheus.NewGaugeVec()，并确保：
- 指标对象全局唯一，在
init()或服务启动时创建一次，**不要在 handler 里反复 new** - 注册时传入自定义
Registry：reg.MustRegister(gaugeVec)，其中reg := prometheus.NewRegistry() - HTTP handler 要显式用
promhttp.HandlerFor(reg, promhttp.HandlerOpts{})，否则还是走默认注册器 - 连接建立/关闭时调用
.WithLabelValues("ws", "active", "/stream").Inc()/.Dec()，避免非原子操作或裸写gauge.Set()
海量标签组合下性能会断崖下跌，得控制爆炸点
高频长连接 + 多维度标签（如 {"protocol","status","path","user_id"}）极易触发 label 组合爆炸。单个 GaugeVec 超过 10k series 时，/metrics 渲染和 Prometheus 抓取都可能超时甚至失败。
- 标签值不宜含高基数字段（如
user_id、request_id），优先聚合到低基数维度（如region、service_version） - 高频打点（如每毫秒更新）需加本地缓存层：按秒聚合后批量
.Inc()，避免GaugeVec内部 mutex 成瓶颈 - 多实例部署必须每个实例用独立
Registry，否则所有实例共用DefaultRegisterer，Prometheus 抓到的是混合态指标，无法区分实例粒度
最常被忽略的一点：你以为改了 instance 标签就能区分实例，其实只要没换 Registry，所有实例的指标都在同一个内存对象里打架——数值不准、重启丢失、抓取超时，全由此起。
