必须显式调用 prometheus.MustRegister() 注册指标，否则 /metrics 中不可见；自定义注册器需用 promhttp.HandlerFor()；标签名全小写下划线，避免高基数；HPA 需 rate() 而非原始 Counter；seriesQuery 必须与代码中 Name 完全一致；直方图需按真实延迟设 Buckets。
必须显式注册，否则 /metrics 里根本看不到你的指标
很多人跑通了 http.Handle("/metrics", promhttp.Handler())，一访问 http://localhost:8080/metrics 却只看到 go_* 和 process_*，自己的 http_requests_total 消失得无影无踪——这不是 Prometheus 没抓到，是你压根没把它“交出去”。promhttp.Handler() 只暴露注册在默认注册器上的指标，而 Go SDK 创建的指标对象（比如 prometheus.NewCounterVec）只是个空壳，不调 prometheus.MustRegister() 就等于没申报。
- 别在
init()里定义指标又忘了注册；更糟的是在多个包里 import 同一个 metrics 包，导致重复MustRegister，直接 panic：duplicate metrics collector - 如果用了自定义注册器（比如
reg := prometheus.NewRegistry()），就一定用promhttp.HandlerFor(reg, ...)，而不是默认的promhttp.Handler() - 标签名必须全小写、下划线分隔、不以数字开头；值里别塞
user_id="12345"这种高基数字段，否则 Prometheus 存储会爆炸
Counter 不能直接给 HPA 用，rate() 才是真实速率
你在 Go 里定义了 my_app_http_requests_total，Prometheus 能采到，但一旦想让 Kubernetes HPA 基于它自动扩缩容，就会发现 HPA 一直不触发——因为 HPA 需要的是“每秒请求数”，而 Counter 是累计值。Adapter 规则里若写 metricQuery: "my_app_http_requests_total"，查出来的是 127489 这种不断增长的大整数，HPA 完全无法理解。
- Adapter 的
rules.yaml中，metricQuery必须包装函数：比如rate(my_app_http_requests_total[2m]) -
seriesQuery必须和你 Go 代码中定义的Name字段**完全一致**，包括大小写和下划线，少一个字符 Adapter 就查不到 -
resources字段不能空着，必须指定template: "pod{{.Resource}}"或overrides，否则 Adapter 启动直接报错：resource mapping not defined
别手写 /metrics handler，也别用框架“套壳”
有人为了加鉴权或日志，在 promhttp.Handler() 外再包一层 http.HandleFunc，或者在 Gin/Echo 里写 router.GET("/metrics", gin.WrapH(promhttp.Handler()))——这会导致 Accept 头协商失败、gzip 不生效、甚至返回 406 Not Acceptable。Prometheus 的文本格式有版本协商机制（如 Accept: application/openmetrics-text; version=1.0.0），手写的 handler 根本不处理。
- 坚持用
promhttp.Handler()或promhttp.HandlerFor(reg, opts)，这是唯一能正确响应各种 Content-Type 和错误码的方式 - 需要 Basic Auth？在 mux 层拦截，比如
mux.Handle("/metrics", withAuth(promhttp.Handler()))，不要侵入 Handler 内部逻辑 - 别把
/metrics挂在带参数的路由下（如/api/v1/:id/metrics），Adapter 和 Prometheus 的 scrape 都依赖固定路径匹配
直方图 Buckets 设错，P99 就永远不准
HTTP 延迟监控最常用 prometheus.NewHistogramVec，但很多人直接用默认 DefBuckets（最大才 10 秒），结果线上 P99 显示是 10s，实际接口早超 30s 了——因为所有 ≥10s 的样本全被塞进最后一个桶，分位数计算彻底失真。
立即学习“go语言免费学习笔记（深入）”；
- 根据你服务真实的延迟分布设
Buckets，比如：[]float64{0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30} - 别用
Gauge模拟 P99：有人定时算一次 p99 再Set()，这既不是实时的，也无法做跨实例聚合，是反模式 - 直方图的
Observe()必须传秒为单位的float64，别传毫秒再除 1000 时丢精度，建议统一用time.Since(start).Seconds()
最难的从来不是写对一行 MustRegister，而是让指标从 Go 进程里出来、被 Prometheus 抓到、再经 Adapter “翻译”成 HPA 能懂的语言——中间任何一环的命名、标签、函数、配置错一位，整条链就断在黑盒里。调试时先盯紧 Prometheus Targets 页面是否 UP，再查 Graph 里能不能 rate(your_metric_name[1m]) 出来数值，最后看 Adapter logs 有没有 no series found。顺序不能乱。
