应统一在 init() 或 main() 早期将指标注册到 prometheus.DefaultRegisterer，使用 prometheus.MustRegister() 避免重复注册；路径需归一化（如 /user/{id}）并按状态码一级分类（2xx/4xx/5xx）控制基数；业务逻辑通过 Metrics 接口注入，解耦监控实现；指标 endpoint 必须为 /metrics，不可与 pprof 路径混用。
如何用 Prometheus 客户端在 Go 模块中注册全局指标
Go 模块里埋点不是“每个函数都加一句 prometheus.NewCounter”，而是先建一套可复用、可复盖全模块生命周期的指标注册机制。核心是：所有指标必须在 init() 或 main() 早期统一注册到默认 prometheus.DefaultRegisterer，否则 http.Handler 暴露时会漏掉。
常见错误是分散定义——比如某个 handler 里临时 new 一个 prometheus.CounterVec 却没显式 Register()，结果 metrics endpoint 返回空或 panic 报 “duplicate metric registration”。
- 用
prometheus.MustRegister()替代裸Register()，它会在注册失败时 panic，便于早期发现重名或类型冲突 - 避免在 struct 初始化字段时直接 new 指标（如
counter: prometheus.NewCounter(...)），这会导致多个实例重复注册；应统一在包级变量定义 +init()中注册 - 如果模块需支持多实例（如插件化服务），改用自定义
prometheus.Registry，并通过promhttp.HandlerFor(reg, opts)暴露
HTTP 请求指标怎么区分路径与状态码而不爆炸式增长
直接对每个 r.URL.Path 做 label 会因动态路径（如 /user/123、/user/456）导致指标 cardinality 爆炸，Prometheus 内存和查询性能迅速恶化。
正确做法是预定义路由模式，在中间件中做路径归一化：
立即学习“go语言免费学习笔记（深入）”；
func normalizePath(path string) string {
switch {
case strings.HasPrefix(path, "/api/v1/users/"): return "/api/v1/users/{id}"
case strings.HasPrefix(path, "/api/v1/orders/"): return "/api/v1/orders/{id}"
default: return path
}
再用这个归一化后的路径作为 path label 值，配合 status_code label 构建 http_request_duration_seconds_bucket 等指标。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 别把 query 参数、JWT sub、IP 地址塞进 label——它们天然高基数，极易拖垮 Prometheus
- 状态码 label 推荐只保留一级分类：如
"2xx"、"4xx"、"5xx"，而不是具体"404"或"503"，除非业务强依赖细分 - 使用
promhttp.InstrumentHandlerDuration()时，务必传入已归一化的pathlabel，否则中间件外层的 Instrument 就白做了
如何让业务逻辑代码不感知监控 SDK
业务函数（如 ProcessOrder()）不该出现 metrics.OrderProcessed.Inc() 这类调用——这违反关注点分离，也导致单元测试难 mock、分支逻辑漏埋点。
可行方案是定义清晰的埋点契约，并通过 interface + 静态注入解耦：
type Metrics interface {
IncOrderProcessed(status string)
ObserveDBLatency(method string, dur time.Duration)
}
// 在 main.go 中构造 concrete 实现并传入 service 层
这样业务代码只依赖 Metrics 接口，测试时可注入 dummy 实现，上线时才绑定真实 Prometheus 指标。
- 避免用全局变量（如
var GlobalMetrics Metrics）传递，容易引发 init 顺序问题或并发写 panic - 若用 Wire/DI 框架，把
Metrics当作 provider 注入，而非让 service 自己 import prometheus 包 - 日志打点（如 zap field）和指标埋点不要混用：log 是事后排查，metric 是实时观测，二者 schema 和生命周期完全不同
为什么 pprof 和 metrics 共用 /debug/metrics 路径会冲突
Go 默认 net/http/pprof 把 profile 数据挂到 /debug/pprof/，而很多人误把 Prometheus metrics 也挂在 /debug/metrics——看似合理，但实际造成两个问题：一是路径语义混乱（debug ≠ metrics），二是某些运维工具（如 kube-prometheus）默认只 scrape /metrics，导致指标采集失败。
标准做法是严格遵循 Prometheus 社区约定：指标 endpoint 必须是 /metrics（无前缀），且仅返回 text/plain 格式指标数据。
- 别用
http.Handle("/debug/metrics", promhttp.Handler())，改成http.Handle("/metrics", promhttp.Handler()) - 若需共存 pprof 和 metrics，保留
/debug/pprof/和/metrics两个独立路径，不要合并或重命名 - Kubernetes readiness probe 若指向
/metrics，需确认该 endpoint 不做 heavy 计算（如实时聚合），否则影响探针稳定性
真正麻烦的不是怎么加指标，而是指标一旦上线就很难下线——label 设计错、cardinality 控制不住、命名不符合规范，后续改成本远高于初期多花十分钟想清楚。
