必须先用 prometheus.MustRegister() 将自定义指标注册到默认收集器，否则 /metrics 不会暴露；注册须在 http.ListenAndServe() 前完成，且不可重复调用，否则 panic。
怎么注册自定义指标到Prometheus
必须先用 prometheus.MustRegister() 把指标注册进默认的收集器，否则 http://localhost:8080/metrics 里完全看不到它。没注册=没暴露，这是最常被跳过的一步。
常见错误现象：curl http://localhost:8080/metrics 返回空或只有 Go 运行时指标，你的业务指标压根不出现。
- 注册要在 HTTP handler 启动前完成，比如
http.ListenAndServe()之前 - 不能在 handler 里反复调用
prometheus.MustRegister()，会 panic：「duplicate metrics collector」 - 如果要用自定义注册器（非默认），得显式传给
promhttp.HandlerFor()，否则还是查不到
counter 和 gauge 哪个该用在什么场景
prometheus.NewCounter() 只增不减，适合统计请求数、错误总数这类累积值；prometheus.NewGauge() 可增可减，适合当前活跃连接数、内存使用量、任务队列长度等瞬时状态。
用错类型会导致 Prometheus 查询语义失效。比如把实时在线人数当 Counter，rate() 就算不出正确增速，还可能因重置产生负值。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- HTTP 请求计数 →
httpRequestsTotal（Counter） - 当前待处理任务数 →
taskQueueLength（Gauge） - 失败次数要单独建 Counter，别复用成功 Counter 减法计算
- Gauge 支持
Set()和Inc()/Dec()，但别在高并发下直接Set(x)覆盖，容易被覆盖丢失精度
怎么带 label 暴露指标又不爆炸
Label 是强大但也危险的特性——每个唯一 label 组合会生成一个独立时间序列。user_id="123" 这种维度一开，几万用户就几万个序列，Prometheus 很快 OOM。
真实业务中，label 应只保留高基数稳定、低 cardinality 的维度，比如 method="GET"、status="200"、endpoint="/api/user"。
- 绝对不要把请求 ID、手机号、邮箱、用户名塞进 label
- 想查单个用户行为？用日志 + traceID 关联，不是 metrics
- 需要聚合下钻？用
sum by (method, status)，而不是靠 label 拉取全量 - label 名称用小写加下划线，如
http_method，避免和 Prometheus 内置指标冲突
为什么 /metrics 接口返回 500 或指标乱码
典型原因是指标注册后又被重复创建，或者某个 Collector 的 Collect() 方法 panic 了。Prometheus 的 http.Handler 遇到 panic 就直接 500，且不输出具体错误。
另一个常见问题是没设正确的 Content-Type，浏览器访问看到乱码，其实是返回了二进制格式（text/plain; version=0.0.4），但没声明 charset。
- 加
promhttp.Handler()前，先跑一遍prometheus.Gatherers{prometheus.DefaultGatherer}.Gather()看是否 panic - 确保所有
WithLabelValues()的 label 数量和定义时一致，少传或多传都会 panic - handler 必须是
promhttp.Handler()或promhttp.HandlerFor(registry, opts)，别手写http.HandlerFunc直接调WriteTo - Content-Type 错误通常是因为用了旧版 client_golang（v1.12.0+ 已修复），升级到最新版即可
label 设计和注册时机是两个最容易出线上事故的点，前者影响存储和查询性能，后者让指标根本不出现在 targets 里——查不到比查得慢更让人抓狂。
