Prometheus指标需显式注册才能暴露：NewGaugeVec等创建后必须调用prometheus.MustRegister()挂载到默认注册器，否则/metrics不显示；自定义注册器需确保HandlerFor使用同一实例。
为什么 prometheus.NewGaugeVec 初始化后不显示在 /metrics？
因为注册器没注册。Prometheus 的指标对象（如 GaugeVec、CounterVec）创建后只是内存里的结构，必须显式调用 prometheus.MustRegister() 才会挂载到默认注册器，并在 HTTP handler 中暴露。
常见错误写法：
var reqDuration = prometheus.NewGaugeVec(
prometheus.GaugeOpts{
Name: "http_request_duration_seconds",
Help: "Duration of HTTP requests.",
},
[]string{"method", "status"},
)
// ❌ 忘了注册！reqDuration 不会出现在 /metrics正确做法：
- 在
init()或main()开头立即注册：prometheus.MustRegister(reqDuration) - 如果用了自定义注册器（比如测试隔离），要确保
http.Handle("/metrics", promhttp.HandlerFor(registry, promhttp.HandlerOpts{}))里传的是同一个 registry - 注意：重复注册会 panic，所以别在循环或多次初始化逻辑里反复调
MustRegister
怎么给 HTTP handler 打点并带 label（如 method、path）？
直接在 handler 里用 WithLabelValues() 记录，但 label 值不能含通配符或高频变动字符串（比如 UUID、用户 ID），否则导致指标 cardinality 爆炸。
立即学习“go语言免费学习笔记（深入）”；
推荐模式：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 对 path 做归一化：把
/users/123改成/users/:id再传给WithLabelValues("GET", "/users/:id") - label 名称用小写+下划线，符合 Prometheus 命名惯例（
http_method而非HTTPMethod） - 避免在 label 里塞错误详情（如
error="invalid_json"），改用单独的counter按 error_type 分类
示例：
func myHandler(w http.ResponseWriter, r *http.Request) {
route := normalizePath(r.URL.Path) // 自定义归一化函数
start := time.Now()
defer func() {
reqDuration.WithLabelValues(r.Method, route).Set(time.Since(start).Seconds())
}()
// ... 处理逻辑
}为什么 Counter 的 Inc() 和 Add(1) 行为不一样？
表面看都加 1，但语义和用途完全不同。
-
Inc()是原子自增 1，专用于计数器（如请求数、错误数），底层是int64原子操作，安全且轻量 -
Add(1)是通用浮点数加法，接受float64，性能略低；如果误用在高并发场景下，可能因浮点精度或竞争导致微小偏差（虽然概率极低） - 更关键的是：Prometheus 官方文档明确要求 Counter 只能单调增，而
Add(-1)是允许的语法但违反语义——监控系统会把它当异常（Stale marker 或 counter reset）
结论：该用 Inc() 就别用 Add(1)；需要加非整数或动态值时，先确认是否真该用 Counter —— 否则考虑 Gauge。
本地调试时怎么快速验证指标是否生效？
别等部署再查，三步终端直连：
- 启动服务后，执行
curl -s http://localhost:8080/metrics | grep your_metric_name，确认行存在且 label 格式正确 - 用
curl -s http://localhost:8080/metrics | head -20看开头是否有# HELP和# TYPE注释行，缺失说明注册失败或命名冲突 - 如果指标值始终为 0，检查是否真触发了打点逻辑（比如 handler 是否被调用、
defer是否被提前 return 绕过）
一个容易被忽略的点：Go 的 http.ServeMux 默认不处理 trailing slash 重定向，如果注册的是 /metrics，但浏览器访问 /metrics/，会 404 —— 导致你以为指标没暴露，其实是路径错了。
