必须用NewGaugeVec定义带标签的长连接监控指标，显式注册并在线程安全前提下于连接建立/关闭时调用Inc()/Dec()更新，避免使用默认注册器和非法标签。
go 服务暴露长连接（如 websocket、grpc streaming、http/2 server push）的监控指标，不能靠默认的 promhttp.handler() 自动采集——它只暴露 runtime 和进程基础指标，对连接生命周期、活跃数、异常断连等完全无感。必须手动定义并更新连接状态指标，且注册时机、更新线程安全、指标维度设计都容易出错。
为什么默认 metrics 端点看不到长连接数
Go 运行时指标（go_goroutines、process_open_fds 等）由 prometheus.DefaultRegisterer 自动注册，但它们不感知业务连接逻辑。长连接是应用层维持的状态，Prometheus 客户端库不会自动扫描 net.Conn 或 http.ResponseWriter.Hijack() 结果。你看到的“连接数”飙升，其实是 go_goroutines 上涨的副作用，无法区分是连接、定时器还是其他 goroutine。
- 直接访问
/metrics却查不到http_connections_active或ws_clients_total？说明没定义指标 - 用
prometheus.NewGaugeVec()定义了，但值始终为 0？大概率是没在连接建立/关闭时调用.Inc()/.Dec() - 多路复用场景（如 gRPC stream）下数值跳变或负数？缺少
sync.Mutex或使用了非原子操作
定义连接状态指标的正确姿势
用 prometheus.NewGaugeVec() 而不是 NewCounterVec()：连接数是瞬时值，需支持增减；Counter 只能递增，无法反映断连释放。
关键参数要带业务维度：
-
labelNames: []string{"protocol", "status", "path"}—— 区分ws/grpc，active/closed，以及路由路径（如/api/v1/stream） - 注册必须显式调用
reg.MustRegister()，其中reg是你自己的prometheus.NewRegistry()，避免和默认注册器冲突 - 不要在 handler 里每次请求都
NewGaugeVec—— 指标对象应全局唯一，初始化一次
示例：
var (
connGauge = prometheus.NewGaugeVec(
prometheus.GaugeOpts{
Name: "app_connections_active",
Help: "Current number of active long-lived connections",
},
[]string{"protocol", "status", "path"},
)
)
func init() {
reg := prometheus.NewRegistry()
reg.MustRegister(connGauge)
http.Handle("/metrics", promhttp.HandlerFor(reg, promhttp.HandlerOpts{}))
}
在连接生命周期中安全更新指标
长连接的建立和销毁常跨 goroutine，比如 WebSocket 的 conn.ReadMessage() 阻塞读、gRPC stream 的 Send() 异步写。更新指标必须保证原子性，否则出现负值或 panic。
- WebSocket 场景：在
upgrader.Upgrade()成功后立刻connGauge.WithLabelValues("ws", "active", path).Inc()；defer 中用.Dec()，但需加if !isClosed判断（避免重复 Dec） - gRPC streaming：在
stream.Context().Done()触发的 goroutine 里 Dec，不要在Recv()循环内直接 Dec - 务必用
sync.Once或atomic控制首次注册，避免热重载时重复注册 panic - 避免在
http.CloseNotify()（已弃用）或Request.Context().Done()中更新——这些不保证触发时机，尤其对 HTTP/2
排查连接数不准的三个典型漏点
指标值和实际连接数对不上，90% 出现在以下环节：
- 没捕获异常断连：网络闪断、客户端强制 kill 进程时，Go 不会自动触发
defer，需结合conn.SetReadDeadline()+ 心跳超时回调 Dec - HTTP/2 场景下复用连接但未按 stream 统计：一个 TCP 连接可承载多个 gRPC stream，此时应额外维护
stream_count_per_conn指标，而非只看连接层 - 指标 label 值含非法字符：如
path="/api/v1/user/123"中的数字 ID 导致 label cardinality 爆炸，应归一化为path="/api/v1/user/{id}"再打点
最易被忽略的是：长连接监控必须和业务错误日志联动。单看 app_connections_active 上升没意义，要同时查 app_connection_errors_total{error="timeout"} 是否同步上涨——否则可能只是连接堆积，而非健康连接。
