go中gauge是瞬时值指标容器，需用prometheus/client_golang创建、注册并由业务事件驱动更新，而非前端图表库或手动拼接；错误注册、未驱动更新或grafana配置不当均会导致监控失效。
Go 里用 Gauge 做仪表盘监控，核心就一条：它不是“画图工具”，而是“瞬时值指标容器”——你要的不是渲染一个带指针的圆盘，而是让 Prometheus 正确采集并暴露一个可增、可减、可设值的浮点数，再由 Grafana 渲染成仪表盘。
为什么不能直接用 go-echarts 的 Gauge 做监控指标？
go-echarts 的 Gauge 是前端图表库，数据只在内存里、不持久、不暴露给 Prometheus、无法被远程抓取。它适合做独立的管理后台页面，但不属于可观测性链路中的一环。
真正用于监控系统的 Gauge 来自 prometheus/client_golang，它是线程安全的原子浮点变量，注册后自动出现在 /metrics 输出里。
- 错误做法：new 一个 struct 存当前连接数，再手动拼字符串输出到 HTTP handler —— Prometheus 完全识别不了
- 正确路径：用
prometheus.NewGauge创建实例 →prometheus.MustRegister注册 → 在业务逻辑中调用.Set()、.Inc()或.Dec() - 零值默认是 0，注册即生效，无需首次手动上报
Gauge 的典型使用场景和更新时机
在线人数、活跃连接数、缓存命中数、队列积压长度——所有“此刻是多少”的值，都该用 Gauge，且必须由业务事件驱动更新，而不是定时轮询。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 登录成功 →
onlineUsers.Inc() - WebSocket 连接断开 →
onlineUsers.Dec() - 定时心跳检测发现失效连接 →
onlineUsers.Set(activeCount) - 避免在每个 HTTP 请求 handler 里查 Redis 再
.Set()，这会放大延迟；只在状态变更点同步更新 - 如果底层用 Redis 维护连接列表，建议用 Pub/Sub 或过期回调触发
Gauge更新，而非轮询 SCAN
注册失败或 /metrics 不返回指标的常见原因
curl http://localhost:8080/metrics | grep 你的指标名，没输出基本就卡在这几个环节：
- 没调用
prometheus.MustRegister(yourGauge)—— 创建了但没注册，等于白写 - 用了
http.DefaultServeMux，但项目实际用的是 Gin/Echo/Chi，导致http.Handle("/metrics", ...)没生效 - 注册器不是默认的（比如用了自定义
prometheus.NewRegistry()），但promhttp.Handler()没传入它 - 指标名含非法字符：允许下划线
_，禁止空格、点号.、斜杠/、破折号- - HTTP server 启动前没完成注册（比如
init()里注册，但main()里启动 server 太快）
Grafana 里怎么把 Gauge 渲染成仪表盘？
Prometheus 本身不绘图，Grafana 才负责可视化。关键在于 PromQL 查询写法和面板类型选择：
- 选面板类型为 Gauge（不是 Bar gauge 或 Stat）
- PromQL 写
online_users即可，不需要加rate()或sum()——Gauge本身就是瞬时值 - 如果服务有多个实例，用
max by(instance)(online_users)避免重复叠加 - 设置阈值颜色：比如
0 → 100显示绿色，100 → 200黄色，200+红色，对应 Grafana 面板里的Thresholds配置 - 注意时间范围：Gauge 类型面板默认显示“最新值”，别误设成 Last 5m 平均 —— 那会掩盖突刺
最易被忽略的点：Gauge 的更新必须紧贴真实状态变更，而不是“看起来差不多”。一次漏掉 .Dec() 可能导致监控值持续偏高，而你很难从 metrics 日志里察觉——它不会报错，只会安静地撒谎。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
