必须用gaugevec而非newgauge实现带标签的业务指标监控，标签名需合法、constlabels仅用于静态属性，须显式注册并避免defaultregisterer冲突，更新时校验标签、缓存label对象，暴露时确保路由与content-type正确。
用 prometheus.NewGaugeVec 定义带标签的业务指标
业务监控不能只扔一个数字上去，比如“订单数”得区分支付状态、渠道、地区才有意义。这时候必须用向量型指标（GaugeVec / CounterVec），而不是裸的 NewGauge。
常见错误是直接写 prometheus.NewGauge(prometheus.GaugeOpts{...})，结果所有维度混在一起，查不出“iOS端未支付订单暴涨”的原因。
- 标签名必须是合法标识符（小写字母/数字/下划线），不能含空格或短横线，比如
channel可以，pay-channel会 panic -
ConstLabels适合进程级固定属性（如instance,version），别往里塞请求级动态值（如user_id），否则 cardinality 爆炸 - 初始化后必须调用
MustRegister()，否则/metrics里完全看不到这个指标
var orderStatusGauge = prometheus.NewGaugeVec(
prometheus.GaugeOpts{
Name: "app_order_status_total",
Help: "Total orders by status and channel",
},
[]string{"status", "channel"},
)
func init() {
prometheus.MustRegister(orderStatusGauge)
}
在 HTTP handler 里安全更新 GaugeVec 值
别在 goroutine 里裸调 orderStatusGauge.WithLabelValues("paid", "ios").Set(123) —— 如果 handler 并发高，又没做 label 校验，容易传入非法值（比如空字符串、超长渠道名），触发 panic: inconsistent label cardinality。
更稳妥的做法是预定义合法 label 组合，或加一层校验：
立即学习“go语言免费学习笔记（深入）”；
- 用 map 做白名单检查：
if _, ok := validChannels[channel]; !ok { return } - 避免在循环里反复调用
WithLabelValues，它内部有 map 查找开销；高频场景建议缓存prometheus.Labels或子指标对象 - 不要用
Inc()/Dec()更新GaugeVec，它不是计数器；设绝对值用Set()，设差值才用Add()
func handleOrder(w http.ResponseWriter, r *http.Request) {
channel := r.URL.Query().Get("channel")
status := r.URL.Query().Get("status")
if channel == "" || status == "" {
http.Error(w, "missing channel or status", http.StatusBadRequest)
return
}
orderStatusGauge.WithLabelValues(status, channel).Set(float64(getOrderCount(status, channel)))
}
暴露指标时绕过 DefaultRegisterer 冲突
项目里如果用了 gin、echo 或其他框架，又自己调了 prometheus.MustRegister(...)，再挂 promhttp.Handler() 时可能报错：duplicate metrics collector registration attempted。
根本原因是多个包都往全局 DefaultRegisterer 注册了同名指标（比如都注册了 go_goroutines）。
- 解决方案：显式创建新 registry，把业务指标和第三方指标分开管：
reg := prometheus.NewRegistry() - 手动注册标准指标：
reg.MustRegister(prometheus.NewGoCollector())，再注册你的orderStatusGauge - 暴露时用
promhttp.HandlerFor(reg, promhttp.HandlerOpts{})，别用默认 handler
调试 promhttp 返回空或格式错乱
访问 /metrics 返回空内容，或者出现 text/plain; version=0.0.4; charset=utf-8 但实际是 HTML（比如 404 页面），基本是路由没对上或中间件拦截了。
- 确认 handler 确实挂到了正确路径：用
http.Handle("/metrics", promhttp.Handler())，不是http.HandleFunc漏掉Handler实例 - 检查是否被 gzip 中间件提前写了 header ——
promhttp要求Content-Type: text/plain，gzip 后可能被篡改 - 本地 curl 测试时加
-v看真实响应头：curl -v http://localhost:8080/metrics 2>&1 | grep "Content-Type"，如果不是text/plain就说明被覆盖了
指标导出本身不难，难的是 label 设计不埋雷、注册不打架、暴露不被劫持。这几个点漏一个，监控就变成盲区。
