必须用 prometheus.NewHistogram 创建直方图，传 HistogramOpts（Name、Help 必填，Buckets 须按业务设），Observe 传秒级 float64 值（如 time.Since().Seconds()），用 promhttp.Handler 暴露指标，查询用 histogram_quantile(rate(..._bucket[...]))。
用 prometheus.NewHistogram 创建直方图指标，别直接 new struct
Go 里不能手动构造 Histogram 结构体——它没导出字段，也没公开的构造函数。必须用 prometheus.NewHistogram 或其带选项的变体，否则运行时 panic：panic: descriptor Desc{...} is inconsistent with previously registered descriptor。
常见错误是照着 Counter 的写法去“new”一个 Histogram，或者试图用匿名结构体赋值，这在编译期不报错，但注册时必崩。
-
prometheus.NewHistogram必须传prometheus.HistogramOpts，至少填Name和Help - 桶边界（
Buckets）不设默认值，漏掉会用prometheus.DefBuckets（0.005~10 秒），但生产环境通常要按业务延时特征重设 - 同一个
Register调用里不能重复注册同名指标，直方图对名字敏感，大小写、下划线都算不同指标
记录请求延时时调用 Observe，不是 Inc 或 Set
直方图不是计数器也不是仪表盘，Observe(float64) 是唯一合法的打点方式。传入单位必须是秒（Prometheus 官方约定），哪怕你原始数据是毫秒，也得自己除以 1000 —— 否则图表上看到的全是毫秒级数值，和监控大盘其他服务对不上。
典型错误：把 time.Since(start) 的 time.Duration 直接传给 Observe，结果单位是纳秒，数值大得离谱；或者忘了转成 float64，编译失败。
立即学习“go语言免费学习笔记（深入）”；
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 正确写法：
histogram.Observe(float64(time.Since(start).Seconds())) - 更安全写法：
histogram.Observe(time.Since(start).Seconds())（Go 1.19+ 支持Duration.Seconds()返回 float64） - 别在中间件里反复
Observe同一个请求多次，直方图每个样本只应代表一次完整请求
用 promhttp.Handler 暴露 /metrics，别手写响应头
直方图数据最终要被 Prometheus 抓取，必须走标准文本格式（text/plain; version=0.0.4）。如果自己拼字符串写 HTTP 响应，大概率格式错、换行乱、类型声明缺，导致 Prometheus 抓取失败并报错：expected a metric, got "" 或 invalid metric type "histogram"。
promhttp.Handler() 不只是个路由 handler，它内部做了指标快照、排序、格式化、Content-Type 设置、gzip 压缩（可选）等全套事情。绕过它等于重写 promhttp 的核心逻辑。
- 注册方式：
http.Handle("/metrics", promhttp.Handler()) - 如果用了 gorilla/mux 或 chi，确保路径匹配精确，不要加 trailing slash 导致 404
- 别在 handler 里调用
promhttp.HandlerFor并传自定义 registry——除非你真需要隔离指标，否则默认 registry 就够用
聚合查询时用 histogram_quantile，不是 quantile_over_time
直方图的分位数不是靠 PromQL 实时计算原始样本，而是依赖客户端预设的桶（buckets）做插值估算。所以必须用 histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[1h])) 这类写法，而不是对某个 label 的 raw duration 做 quantile_over_time —— 后者根本查不到直方图数据，因为原始 duration 样本压根没存。
容易忽略的点：rate 函数里的区间长度影响精度。太短（如 [5m]）可能因采样稀疏导致桶计数为 0；太长（如 [24h]）会让近期毛刺被平滑掉。一般从 [30m] 起步，根据 scrape interval（通常是 15s）和抖动容忍度调整。
- 确认指标名后缀是
_bucket，不是_sum或_count—— 只有_bucket才能用于histogram_quantile - 如果发现分位数恒为 0，先检查
rate(..._bucket[...])是否返回空向量，再查是否漏了_bucket标签（比如少了个le="0.1"） - 直方图无法精确计算中位数以下的极低延时（如 p50=2ms），因为桶边界不够密，这时得靠 Summary 类型，但代价是服务端不可聚合
