根本原因是自定义指标未注册到正确的注册器；默认promhttp.Handler()仅暴露DefaultRegisterer中的指标，而业务指标需显式调用prometheus.MustRegister()注册，否则不会出现在/metrics中。
为什么/metrics端点返回数据但Prometheus查不到业务指标？
根本原因不是网络或配置错误，而是自定义指标没注册进正确的注册器。默认的 promhttp.Handler() 只暴露 prometheus.DefaultRegisterer 里的指标，而 Go 运行时指标（go_goroutines、process_cpu_seconds_total 等）是自动注册的，业务指标不会自动出现。
- 直接写
prometheus.NewCounter(...)但漏掉prometheus.MustRegister()→ 指标完全不生效 - 多个包都用
promauto.NewCounter()初始化同名指标（如http_requests_total）→ 启动 panic 报duplicate metrics collector registration attempted - 热重载或 fork 子进程场景复用
DefaultRegisterer→ 指标状态被覆盖或冲突
如何安全注册海量业务指标并支持动态维度？
高频长连接服务（如 WebSocket、gRPC 流）会产生大量带标签的指标，必须用 CounterVec / GaugeVec，且注册逻辑要收敛到一处，避免跨包隐式注册。
- 不要在 handler 函数里反复调用
NewCounterVec()，它应只在 init 或 startup 阶段创建一次 - 用
WithLabelValues("GET", "/api/user", "200")写入，而不是拼接字符串构造 metric name - 标签值不宜过多：单个
CounterVec的 label 组合爆炸后会显著拖慢/metrics渲染和 Prometheus 抓取（>10k series 就可能超时） - 高频打点场景加本地缓存层（如每秒聚合后批量
Inc()），避免锁竞争（CounterVec内部有 mutex）
多实例部署下如何避免指标混淆？
长连接服务常做滚动发布或蓝绿部署，若所有实例共用默认注册器，Prometheus 抓到的是混合态指标，无法区分实例粒度。
- 每个实例必须使用独立
prometheus.NewRegistry()，而非prometheus.DefaultRegisterer - HTTP handler 要显式传 registry：
promhttp.HandlerFor(reg, promhttp.HandlerOpts{}) - 务必在
scrape_configs中配honor_labels: true，否则 Prometheus 会强制覆盖instance标签 - 若用服务发现（如 Consul、K8s Endpoints），确保 target 的
__address__唯一且可路由；Docker 容器内不能写localhost:8080
长连接场景下指标延迟高、/metrics卡顿怎么办？
/metrics 是纯文本同步生成，当指标量大（尤其含高基数 label）时，一次响应可能耗时数百毫秒甚至秒级，导致 Prometheus 抓取超时（默认 10s）或触发告警。
- 禁用低价值 label：比如把用户 ID 当 label → 改为记录日志 + 关联 traceID，用 Grafana Loki 查
- 对非核心路径降采样：用
rand.Float64() 控制 1% 请求打点 - 启用压缩：
promhttp.HandlerFor(reg, promhttp.HandlerOpts{EnableOpenMetrics: true})并在 Prometheus 配置中设enable_open_metrics: true（更紧凑格式） - 关键指标单独拆 endpoint（如
/metrics/basic）供 Prometheus 快速抓取健康态
真正难的不是写几行 Inc()，是 label 设计边界、registry 生命周期管理、以及当单机承载数万连接时，如何不让指标本身成为性能瓶颈。这些地方没压测过，上线就容易翻车。
