Go服务/metrics接口必须被Prometheus成功抓取，否则Grafana无法显示长连接质量指标；需正确注册Gauge/Histogram指标、配置scrape targets、避免中间件拦截，并用_le_标签聚合直方图查询。
Go 服务暴露的 /metrics 接口必须能被 Prometheus 抓到，Grafana 才可能画出长连接质量指标——否则所有面板都是空的。这不是 Grafana 配置问题，而是监控链路最前端就断了。
确保 Go 服务正确暴露长连接相关指标
长连接质量不能只靠 http_requests_total 这类通用指标判断。你需要显式定义并打点连接生命周期指标，且注册时机和路径必须严格满足 Prometheus 抓取要求：
-
http.Handle("/metrics", promhttp.Handler())必须在http.ListenAndServe()之前调用；否则curl http://localhost:8080/metrics返回 200 但内容为空 - 连接数要用
Gauge（可增可减），不是Counter：比如conn_active_total{proto="websocket"}，每次新连接.Set(1)，断开时.Dec() - 连接建立耗时、心跳超时次数、消息丢包率等，必须用
Histogram并配合理 buckets：例如conn_handshake_duration_seconds_bucket{le="0.5"}，le值建议覆盖 0.1/0.3/0.5/1.0/3.0 秒 - 所有自定义指标必须调用
prometheus.MustRegister()；漏注册 = Prometheus 查不到 = Grafana 画不出 - 避免中间件拦截
/metrics：JWT、CORS、日志中间件若对这个路径生效，Prometheus 抓取会返回 401/403 或直接超时
Prometheus targets 必须真实可达且状态为 UP
Grafana 不连 Go 服务，它只读 Prometheus 的数据。所以即使你的 Go 服务跑着，只要 Prometheus 抓不到，Grafana 就永远显示 “No data”：
- Docker 环境下，
scrape_configs.targets不能写localhost:8080—— Prometheus 容器里没有这个 localhost，得写宿主机 IP（如172.17.0.1:8080）或容器网络别名（如go-app:8080） - 检查 Prometheus UI 的 Status → Targets 页面：目标状态必须是
UP，Last Scrape 时间距现在不能超过scrape_interval（默认 15s） - 如果状态是
DOWN，点开右侧的scrape error字段看具体报错：常见是网络不通、Go 服务只监听了127.0.0.1而非0.0.0.0、TLS 证书不匹配（若启用了 HTTPS） - job_name 必须唯一：两个 job 都叫
long-conn，后者会覆盖前者，导致部分指标丢失
Grafana 查询长连接分位数必须带 _bucket 和 by (le)
直方图类指标（如握手延迟、心跳间隔）在 PromQL 中不能直接查原始值。漏掉关键语法，查询结果永远为空：
- 正确写法：
histogram_quantile(0.95, sum(rate(conn_handshake_duration_seconds_bucket[5m])) by (le, proto)) - 错误写法：
histogram_quantile(0.95, rate(conn_handshake_duration_seconds_sum[5m]))（用_sum替代_bucket） - 错误写法：
histogram_quantile(0.95, sum(rate(conn_handshake_duration_seconds_bucket[5m])) by (proto))（漏掉le标签聚合） - 业务指标命名建议加前缀，比如
myapp_conn_active_total，避免和 Go 运行时指标（如go_goroutines）冲突或混淆
长连接场景下容易被忽略的指标维度
单纯看“总连接数”或“平均延迟”掩盖了真实问题。必须通过标签做细粒度切分，否则无法定位是哪类客户端、哪个协议或哪个节点出了问题：
- 连接协议类型：用
proto="websocket"、proto="quic"、proto="tcp"区分，不同协议的超时策略和重连行为差异极大 - 客户端版本或 SDK 来源：加
client="ios-2.3.1"、client="web-vue3"，便于发现某版本存在批量断连 - 后端节点标识：用
instance="node-01"或region="shanghai"，排查是否单点故障或区域网络抖动 - 连接状态标签：不要只用一个
Gauge表示总数，额外加conn_state="connected"、conn_state="reconnecting"、conn_state="failed"，方便统计失败率
长连接监控最难的不是画图，而是指标设计本身——打点位置错了、标签维度缺了、buckets 设宽了，后面所有 Grafana 面板都只是假象。先在 Prometheus 表达式浏览器里确认 rate(myapp_conn_handshake_duration_seconds_bucket[5m]) 能查出带 le 的多条时间序列，再进 Grafana 配面板。
