Gauge适用于监控队列长度，因其支持增减操作，能真实反映瞬时堆积量；Counter只增不减，误用会导致数据失真或panic。
为什么用 Gauge 而不是 Counter 监控队列长度
队列长度是瞬时值，会随入队/出队动态增减，Counter 只能递增，强行用它会导致数据完全失真。Gauge 才是唯一正确选择——它支持 Set()、Inc()、Dec()，能真实反映当前堆积量。
常见错误是把“已处理请求数”和“当前排队数”混为一谈：前者用 Counter，后者必须用 Gauge。如果误用 Counter 模拟长度（比如每出队一次就 Dec()），会触发 panic: counter cannot decrease。
- 定义方式必须带
Name和非空Help字段，否则prometheus.MustRegister()会直接 panic - 标签（labels）只保留必要维度，例如
queue_name，避免加worker_id或request_id导致高基数 - 初始化建议放在
func init()中，确保在 HTTP server 启动前完成注册
/metrics 端点返回空或 404 的典型原因
访问 /metrics 看不到队列指标，大概率不是代码没写，而是注册时机或路由挂载出了问题。
最常踩的坑是：指标变量声明了、WithLabelValues 也调用了，但漏掉了 prometheus.MustRegister()；或者注册发生在 http.ListenAndServe() 之后，Prometheus 第一次抓取时指标根本不存在，它不会报错，只会静默跳过。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 确认是否用了新版
promhttp.HandlerFor()：旧写法promhttp.Handler()已废弃，v1.0+ 会 panic - 若用了自定义注册器（如
reg := prometheus.NewRegistry()），必须把指标注册到它上面，再传给HandlerFor()，否则/metrics返回空 - 检查 HTTP 路由是否被中间件拦截（比如 JWT 鉴权、CORS），
/metrics应绕过所有业务逻辑中间件
如何安全暴露高并发队列的实时指标
队列监控的核心矛盾在于：采集要快，但不能拖慢入队/出队路径。直接在 Enqueue() 或 Dequeue() 里调用 gauge.Inc() / gauge.Dec() 是安全的，但要注意两点。
一是避免在热路径反复调用 WithLabelValues() 创建新指标实例——虽然开销小，但在万级 QPS 下仍会增加 map 查找和内存分配；二是别在多个 goroutine 并发调用 MustRegister()，会 panic：duplicate metrics collector registration。
- 推荐在结构体初始化时缓存常用 label 组合的 Gauge 实例，例如：
queueLengthGauge = queueLengthVec.WithLabelValues("payment_task") - 入队时
queueLengthGauge.Inc()，出队时queueLengthGauge.Dec()，无需锁（Gauge 内部已用原子操作保证线程安全） - 如果队列本身有状态机（如 pending → processing → done），可额外用一个 Gauge 记录 processing 中的数量，辅助判断消费瓶颈
延迟采集和聚合要不要用 Histogram
监控队列不只是看长度，还要看任务在队列里等了多久。这时候别急着上 Histogram —— 它会为每个 bucket 生成独立时间序列，若按 queue_name + priority 多维分桶，极易引发高基数爆炸。
更轻量的做法是：用一个 Gauge 记录「当前最长等待时间（秒）」，或用 Counter 统计「超时未出队的任务数」。需要百分位分析时，再考虑 Histogram，且必须预设合理 buckets（比如 []float64{0.1, 0.5, 1, 5, 10, 30}），禁用默认 buckets。
- 不要对每个任务单独打点延迟，应在出队瞬间计算耗时并更新指标
- 若用
Histogram，务必搭配promauto包自动注册，避免手动管理生命周期 - 生产环境建议限制活跃序列总数，可通过 Prometheus 的
scrape_limits或服务端限流控制
真正难的不是定义几个指标，而是在高并发下让指标采集不成为性能瓶颈，也不因标签失控导致 Prometheus OOM。队列监控的本质，是用最少的维度讲清最危险的状态：积压、延迟、阻塞。其他都算锦上添花。
