metricsx —— Prometheus 指标 + /metrics 端点
框架自带 4 类 HTTP 基础指标,业务方再挂自己的业务指标,全部从同一个端点暴露。
功能
metricsx 干三件事:
- 一个 registry(
prometheus.Registry,不是全局 default registry)- Go runtime / process collector + 应用元信息
app_info{app,version,env}
- Go runtime / process collector + 应用元信息
4 类 HTTP 基础指标(数据由
middleware.Metrics()上报,业务代码不用管):| 指标 | 类型 | 标签 | |---|---|---| |
<ns>_http_requests_total| counter |method,path,status| |<ns>_http_request_duration_seconds| histogram |method,path,status| |<ns>_http_requests_in_flight| gauge | — | |<ns>_http_response_size_bytes| histogram |method,path,status|业务埋点:
BusinessCounter/BusinessGauge/BusinessHistogram/ObserveDuration,指标名统一加app_biz_前缀。/metrics端点:Handler()返回 Hertz handler,Mount()一行挂上。
不解决什么:不做告警、不做看板、不管采集端。告警规则在 Prometheus 侧 (见 slowquery 的做法)。
配置
yaml 侧(metrics: 块)
metrics:
enabled: true # 总开关
path: /metrics # 暴露路径(默认 /metrics)
namespace: app # 指标前缀(默认 app)→ app_http_requests_total
subsystem: "" # ⚠️ 当前**没有任何代码读它**(见下)
metrics.namespace 决定 HTTP 指标的命名前缀:namespace: app ⇒
app_http_requests_total;namespace: demo ⇒ demo_http_requests_total。
代码侧
metricsx.Init(cfg.Metrics, appName, version, env string)
metricsx.Mount(h *server.Hertz, cfg config.MetricsConfig)
metricsx.Handler() app.HandlerFunc
Init 的四个参数里,appName / version / env 落到 app_info 标签上
(恒为 1 的 gauge),方便 PromQL 关联。
使用方法
启动时装配
// cmd/server/main.go
metricsx.Init(cfg.Metrics, cfg.System.AppName, cfg.System.AppVersion, cfg.OTel.Env)
// router.go
h.Use(middleware.Metrics()) // 4 类 HTTP 指标的采集点
metricsx.Mount(h, cfg.Metrics) // 挂 /metrics
业务埋点
metricsx.BusinessCounter("order_paid_total", "channel").WithLabelValues("wechat").Inc()
metricsx.BusinessGauge("login_online_total").WithLabelValues().Set(42)
metricsx.BusinessHistogram("order_amount_yuan",
[]float64{1, 10, 100, 1000}, "channel").
WithLabelValues("wechat").Observe(99.5)
// 无标签的耗时快捷方式
metricsx.ObserveDuration("order_process_seconds", 150*time.Millisecond)
注册自定义 collector
metricsx.MustRegister(myCollector) // Init 之后才能用
reg := metricsx.Registry() // 也能拿到 registry 自己注册
命名约定
| 指标 | 实际暴露的名字 |
|---|---|
BusinessCounter("order_paid_total", ...) |
app_biz_order_paid_total |
BusinessGauge("login_online_total") |
app_biz_login_online_total |
HTTP 基础指标(namespace: app) |
app_http_requests_total 等 |
即:HTTP 指标走 namespace,业务指标走固定的 app_biz_ —— 两套前缀,
业务指标不受 metrics.namespace 影响。
注意事项
- ⚠️
Init是sync.Once—— 一个进程只能初始化一次。 第二次调是 no-op:换namespace不会生效,想重置 registry 必须换进程 (测试里尤其要注意)。 - ⚠️
metrics.enabled: false并不停止采集。Init里没有读cfg.Enabled—— 它照样建 registry、注册全部 collector;只有Mount读Enabled并因此不挂/metrics端点。而middleware.Metrics()在 router 里是无条件挂的,它只看metricsx.HTTPRequestsTotal() != nil(Init 过了就非 nil)⇒enabled: false时指标照样在采,只是没人能 scrape 到。 yaml 里"Init 内部空实现、中间件也 no-op"那句注释与实现对不上。 - ⚠️
metrics.subsystem是死配置 ——MetricsConfig里有这个字段, 但metricsx里没有任何代码读它。填什么都不会生效。 - ⚠️
Registry()在Init之前返nil;MustRegister在Init之前 直接 panic(metricsx: Init must be called before MustRegister), 这是有意的 —— 早期暴露配置问题,而不是让指标悄悄丢。 - ⚠️
BusinessGauge/BusinessCounter/BusinessHistogram返回的是*Vec类型,取值必须先WithLabelValues(...)。*prometheus.GaugeVec没有Set方法 —— 写.Set(42)编译不过。 - ⚠️ 同名指标的"种类"和"标签集"必须完全一致,否则 panic。
BusinessCounter("x", "a")之后再调BusinessGauge("x", "a")或BusinessCounter("x", "b")都会 panic(消息是人话,不是 Prometheus 的裸 panic)。 标签名集合进缓存键就是为了拦这个 —— Prometheus 那边会直接inconsistent label cardinality。 - ⚠️
ObserveDuration(name, d)没有标签。要带标签请直接用BusinessHistogram(name, nil, "channel").WithLabelValues("wechat").Observe(d.Seconds())。 (旧版ObserveDuration带labelNames ...string,但Observe要的是 标签值不是标签名,接口本身就不可用 —— 那一版每次调用都 panic。) - ⚠️ label 里不要放高基数值(用户 id / 订单 id)—— Prometheus 会被撑爆。 要放就放可枚举的维度(渠道 / 状态)。
- ⚠️
path标签用的是路由模板(c.FullPath(),如/rapid-admin/v1/biz/orders/:id),不是实际 URL;未匹配到路由时固定用/unmatched,不用原始 path —— 否则扫描器每打一个随机 URL 就多一条 series。 - ⚠️
/metrics的内容协商必须写# EOF。OpenMetrics 报文要以# EOF收尾,否则客户端判定报文非法。实现用的是 prometheus 官方同款的expfmt.NegotiateIncludingOpenMetrics(早期版本是精确匹配Accept头, 真实 Prometheus 发的是复合头,永远协商不中)。 - ⚠️ 在当前 router 的挂载顺序下,
/metrics的抓取请求本身会被记一条path="/metrics"的 series。Hertz 是在路由注册时把全局中间件拼进 路由链的,而metricsx.Mount在h.Use(middleware.Metrics())之后执行 —— 所以源码注释里"绕过 Metrics 中间件(self-reporting 循环)"这句在当前装配下 并没有兑现。这不是死循环(只多一条 series),但看板里会多出一个指标项。 - ⚠️
ErrNoRegistry这个导出变量当前无人使用(声明了但没有任何返回它的地方)。