Go语言Echo框架Prometheus监控-Golang-PHP中文网

echo框架本身不内置监控中间件，echo.new()创建的是干净实例，必须显式注册prometheus中间件并挂载/metrics路由，否则curl该路径返回404；漏注册、错用wraphandler、未调mustregister或registry为空均导致指标缺失。

go语言echo框架prometheus监控

为什么 `echo.New()` 默认不带 Prometheus 中间件

Echo 框架本身不内置任何监控中间件，echo.New() 创建的实例是“干净”的，没有任何指标采集逻辑。Prometheus 监控必须显式注册中间件，否则 /metrics 路由根本不存在，curl localhost:8080/metrics 会直接返回 404。

常见错误现象：启动服务后 Prometheus 抓不到数据，curl 返回 404 或空响应，但日志里又没报错——大概率是漏了中间件注册或路由挂载。

必须手动引入 github.com/prometheus/client_golang/prometheus/promhttp 提供的 HTTP handler
必须用 e.Use() 注册指标收集中间件（如 prometheus.New(echo.WrapHandler(promhttp.Handler())) 不行，这是错的）
推荐使用社区维护的 github.com/itsjamie/echo-prometheus，它提供 prometheus.NewMetrics() 中间件，自动记录请求延迟、状态码、方法等基础指标

如何正确挂载 `/metrics` 路由并暴露指标

不能只加中间件，还要确保 /metrics 这个路径被明确注册为 handler，否则 Prometheus 抓取端点不存在。

实操建议：

用 github.com/itsjamie/echo-prometheus 时，先调用 prometheus.NewMetrics() 创建中间件，再 e.Use(mw)
然后单独注册路由：e.GET("/metrics", echo.WrapHandler(promhttp.Handler()))
注意：不要用 echo.WrapHandler 包裹中间件本身——中间件是给 e.Use() 的，/metrics 是独立 endpoint，必须用 promhttp.Handler() 直接响应
如果用了自定义 registry（比如传入 prometheus.NewRegistry()），记得把 promhttp.HandlerFor(reg, promhttp.HandlerOpts{}) 作为 handler 传给 GET("/metrics")

示例关键片段：

Echo框架 5.1.0

Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。

下载

import (
  "github.com/itsjamie/echo-prometheus"
  "github.com/prometheus/client_golang/prometheus/promhttp"
)

mw := prometheus.NewMetrics()
e.Use(mw)
e.GET("/metrics", echo.WrapHandler(promhttp.Handler()))

`echo-prometheus` 中间件默认统计哪些指标

它默认导出三类核心指标，全部以 echo_ 为前缀，符合 Prometheus 命名惯例：

echo_http_request_duration_seconds_bucket：按状态码、方法、路径标签分组的请求延迟直方图（含 _sum 和 _count）
echo_http_request_total：按状态码、方法、路径计数的 Counter
echo_go_goroutines：Go runtime 当前 goroutine 数（无需额外配置）

注意路径标签（path）默认是原始 URL 路径，不是 Echo 的路由 pattern。例如访问 /api/users/:id 会被记为 /api/users/123，容易导致 label 爆炸。如需按 pattern 统计，得自己实现 LabelFunc 并传给 NewMetricsWithOptions()。

为什么 `curl /metrics` 返回空或格式错误

最常见原因是 Content-Type 不对或 handler 被其他中间件拦截。Prometheus 抓取要求响应头必须是 Content-Type: text/plain; version=0.0.4; charset=utf-8。

检查是否误用了 echo.HTTPErrorHandler 拦截了 /metrics 请求（比如全局 error handler 对 200 也做了重写）
确认没在 /metrics 路由上挂载其他中间件（如 JWT 鉴权），这会导致 handler 被跳过或 panic
用 curl -v http://localhost:8080/metrics 看响应头，若 Content-Type 不是 text/plain，说明 handler 没走 promhttp.Handler()
若返回空但状态码是 200，可能是 registry 为空——检查是否真的有请求触发过指标打点（首次请求后指标才初始化）