echo-prometheus 默认指标不适合生产，因其耗时直方图分桶不合理、path标签未归一化致内存泄漏、缺乏自定义标签支持；应改用echo-contrib/prometheus手动注册并严格控制标签维度与路径截断。
直接用 echo-prometheus 中间件是最省事的方案，但默认配置下指标粒度粗、标签失控、分桶不合理，上线后容易查不到真实瓶颈，甚至引发内存泄漏。
为什么 echo-prometheus 默认 metrics 不适合生产
它暴露的 /metrics 端点只统计基础 HTTP 指标（如总请求数、状态码分布、响应时间直方图），但存在三个硬伤：
- 耗时直方图用的是
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 多维下钻联动
用 echo-contrib/prometheus 手动注册更可控
它把指标注册和采集逻辑拆开，允许你精确控制标签维度和分桶策略。关键步骤如下：
- 导入包：
"github.com/labstack/echo-contrib/prometheus"（注意不是echo-prometheus） - 初始化时显式传入
prometheus.NewPrometheus("myapp", nil)，第二个参数可设Registry或留nil用默认注册器 - 调用
p.Use(e)挂载中间件，它会在每个 handler 入口计数、出口记录耗时 - 手动注册自定义指标前，先调用
prometheus.MustRegister()确保不重复注册
示例片段：
Echo框架 5.1.0
下载
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
import (
"github.com/labstack/echo-contrib/prometheus"
"github.com/prometheus/client_golang/prometheus"
)
p := prometheus.NewPrometheus("myapp", nil)
p.Use(e)
// 自定义 QPS 计数器，带 method 和 path 标签（注意：path 要截断）
customCounter := prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "myapp_custom_requests_total",
Help: "Total custom requests",
},
[]string{"method", "path"},
)
prometheus.MustRegister(customCounter)
// 在 handler 里：
customCounter.WithLabelValues(c.Request().Method, "/api/v1/users").Inc()
必须做路径截断和标签白名单
避免因 URL 参数或 ID 导致标签爆炸，这是线上事故高频原因。不要依赖中间件自动提取 r.URL.Path，自己处理：
- 用正则或
strings.Split提取稳定路径段，例如将/api/v1/users/123归一化为/api/v1/users/{id} - 只允许以下字段进标签：
method、status_code、path_template（归一化后）、env（从环境变量读） - 禁止使用：
r.RemoteAddr、r.URL.Query().Get("token")、r.Header.Get("X-Request-ID") - 若需追踪单次请求，走 Jaeger 或 OpenTelemetry，别塞进 Prometheus metrics
暴露端点与 Prometheus server 抓取配置
/metrics 默认监听在应用同端口，无需额外 HTTP server。但 Prometheus server 的 scrape_configs 必须匹配：
- 确保
job_name唯一且语义清晰，比如echo-app-prod -
static_configs.targets指向你的 Echo 服务地址，如["echo-svc:8080"]（K8s Service 名）或["10.0.1.23:8080"] - 加
metrics_path配置（如果改过路径）：metrics_path: "/metrics"（默认就是这个，显式写更安全） - 建议加
sample_limit防止指标暴增拖垮抓取：sample_limit: 10000
真正难的不是挂中间件，而是让每条指标都有明确业务含义、可控生命周期、可聚合维度 —— 否则 Grafana 画出来的图，只是数据幻觉。
