iris-prometheus默认中间件不可上生产，因其直方图分桶不合理导致p99失真、原始路径生成海量指标致内存溢出、缺失service_name/env等关键标签无法下钻。
为什么 iris-prometheus 默认中间件不能上生产
它暴露的指标看着全，但三个硬伤直接卡死可观测性：http_request_duration_seconds 直方图用的是 prometheus.DefBuckets（[0.005, 0.01, 0.025, ...] 秒），而你的 API 95% 耗时在 100ms 内，结果 P99 显示为 0.005s，实际可能是 2.8s；所有原始路径（如 /api/v1/users/123）直接当 path 标签值写入，user_id=123 这种动态值会无限生成新指标实例，几分钟吃光内存；不支持加 service_name、env 等关键标签，Grafana 下钻时没法按服务或环境切片。
iris-contrib/prometheus 手动注册才是唯一可行路径
iris 没有官方维护的 iris-contrib/prometheus，但社区实践已收敛出稳定模式：必须自己定义指标 + 显式注册 + 中间件只负责打点，不自动注册。关键不是“挂中间件”，而是“怎么注册+怎么打点”：
- 导入
github.com/prometheus/client_golang/prometheus和github.com/prometheus/client_golang/prometheus/promhttp - 在应用启动早期（
app.Run()前）注册核心指标，例如：prometheus.MustRegister(requestCounter)，绝不能在 handler 里重复调用 - 自定义直方图时显式传入合理分桶，比如
Buckets: []float64{0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5}（单位秒） - 路径标签必须做截断：把
/api/v1/users/:id归一化为/api/v1/users/{id}，再传给WithLabelValues()
如何实现路径归一化和标签白名单
这是线上事故最高频原因。Iris 的路由参数（:id、*path）不会自动映射到 Prometheus 标签，必须手动提取并替换。别依赖 c.Request().URL.Path —— 它返回的是原始路径，含真实 ID 值。
- 用
c.Params遍历参数名，结合c.Route().Path（返回带占位符的模板路径）构造归一化 path - 对敏感字段（如
auth_token、callback_url）做白名单过滤，不在白名单里的 query key 全部丢弃，避免 label 爆炸 - 建议封装一个
normalizePath(c *iris.Context)工具函数，统一处理所有 handler - 示例：
customCounter.WithLabelValues(c.Method(), normalizePath(c), strconv.Itoa(c.GetStatusCode())).Inc()
暴露 /metrics 端点并配置 Prometheus 抓取
不要用 iris.StaticWeb 或 iris.Get 暴露指标——它绕过中间件链，且不设 Content-Type。必须用 promhttp.Handler()：
- 注册路由：
app.Get("/metrics", func(c iris.Context) { promhttp.Handler().ServeHTTP(c.ResponseWriter(), c.Request()) }) - 确保该路由无其他中间件（如 JWT 鉴权），否则可能拦截或污染响应头
- Prometheus 配置中
scrape_interval建议设为15s，太频繁会增加 GC 压力；timeout不要低于10s，防止指标采集超时失败 - 若部署多实例，务必在 Prometheus job 配置中启用
honor_labels: true，避免instance标签被覆盖
