metrics

README

ekit-metrics

Prometheus 指标门面——framework-agnostic Registry 与弹性指标族。

本仓库是 ekit（git.enjoye.top/enjoydream/ekit v0.34.0） 拆分出的独立 Go module，属于 oekit ekit 子项目矩阵（Round-2 深拆粒度）。

安装

go get github.com/oekit/metrics@v0.1.0

包清单

• 根包 `metrics`（import `github.com/oekit/metrics`）— Registry、Init(service)、默认注册
• `resilience/` — 熔断/重试共享指标族（httpx/nns/kitex 共用，契约 §5.5）

矩阵总览（20 活跃仓 + 19 微库，自动生成）

仓库	内容	矩阵内依赖
ekit-bootstrap	（见 README）	ekit-bootstrap, ekit-concurrency, ekit-core, ekit-logx, ekit-metrics, ekit-nns, ekit-registry, ekit-tracing
ekit-cache	进程内缓存微库——LRU O(1)、TOCTOU 修复的 LocalCache	—
ekit-concurrency	（见 README）	ekit-concurrency
ekit-convert	类型转换微库——字符串/数字/布尔/切片的宽容转换	—
ekit-core	Go 后端基础工具库——应用基建件（governance 治理 schema / lifecycle 生命周期契约 / network IP 工具 / version）	ekit-core
ekit-data	（见 README）	ekit-concurrency, ekit-logx
ekit-encoding	编解码微库——JSON/msgpack 等序列化助手	—
ekit-enumx	枚举工具微库——确定性顺序的 All/Values/解析	—
ekit-errors	错误处理微库——Wrap/Cause 链、BizError（业务码/HTTP 码双轨）、sentinel 错误	—
ekit-gorm	（见 README）	ekit-errors, ekit-gorm, ekit-logx, ekit-pagination
ekit-handler	（见 README）	ekit-core, ekit-errors, ekit-gorm, ekit-handler, ekit-middleware, ekit-pagination, ekit-tracing, ekit-validator
ekit-hertz	（见 README）	ekit-concurrency, ekit-core, ekit-hertz, ekit-logx, ekit-metrics, ekit-nns, ekit-registry, ekit-tracing
ekit-httpjson	HTTP JSON 微库——DoJSON 带 retry 语义与 Retry-After 尊重	ekit-stringx
ekit-httpx	（见 README）	ekit-concurrency, ekit-httpx, ekit-logx, ekit-metrics, ekit-registry
ekit-istio	（见 README）	—
ekit-jsonrepair	JSON 修复微库——宽容修复链：截断/尾逗号/单引号/非标准值归一	—
ekit-kitex	（见 README）	ekit-concurrency, ekit-core, ekit-errors, ekit-kitex, ekit-logx, ekit-metrics, ekit-nns, ekit-registry, ekit-tracing
ekit-kitex-examples	（见 README）	ekit-bootstrap, ekit-kitex, ekit-kitex-examples, ekit-logx, ekit-registry, ekit-tracing
ekit-logx	（见 README）	ekit-logx
ekit-mathx	数学工具微库——安全随机、区间、平均值等评测统计助手	—
ekit-metrics	（见 README）	ekit-core, ekit-metrics
ekit-middleware	（见 README）	ekit-concurrency, ekit-errors, ekit-logx, ekit-metrics, ekit-middleware, ekit-pathx, ekit-registry, ekit-tracing
ekit-network	（见 README）	ekit-concurrency, ekit-logx, ekit-tracing
ekit-nns	（见 README）	ekit-concurrency, ekit-core, ekit-logx, ekit-nns, ekit-registry
ekit-nns-endpoint	NNS 端点工厂——per-service 熔断（4xx 不计失败）、HTTP 换实例重试、gRPC 连接池、弹性指标	ekit-httpx, ekit-logx, ekit-metrics, ekit-nns, ekit-registry
ekit-pagination	分页微库——PageRequest/PageResponse 与换算	—
ekit-pathx	路径匹配微库——glob（vendor/**、*.test）匹配	—
ekit-ptrx	指针工具微库——To/From/安全解引用	—
ekit-redis	（见 README）	ekit-concurrency, ekit-data, ekit-logx, ekit-redis
ekit-registry	（见 README）	ekit-core, ekit-logx, ekit-registry
ekit-slicex	切片工具微库——Partition 二分组、GroupBy、去重与映射	—
ekit-stringx	字符串工具微库——ID 生成、关键词匹配、缩进、复数化、模板替换	—
ekit-timertask	定时任务微库——分片定时任务（FNV-1a hash、心跳续约）	ekit-concurrency, ekit-logx
ekit-timex	时间工具微库——格式化/解析/时间戳 + cron 表达式	—
ekit-tracing	（见 README）	ekit-logx
ekit-uidgen	ID 生成微库——UUID、雪花、随机串	—
ekit-validator	参数校验微库——go-playground/validator 封装，ValidationError 归一为 BizError(400)	ekit-errors
ekit-workflow	（见 README）	ekit-concurrency, ekit-logx

ekit-observability 已在 Round-2 解散归档；本表由源码 import 自动生成。 依赖严格单向：工具微库/L0 → 可观测门面 → registry → data/httpx/middleware → nns/bootstrap → hertz/kitex。

当前仓库依赖

详见上方矩阵表中本仓库行。

与 ekit 单体仓库的关系

• 代码与 ekit v0.34.0 等价，module 路径 git.enjoye.top/enjoydream/ekit/... → github.com/oekit/metrics/...
• 各子仓库独立发版（SemVer）；开发规范沿用 ekit AGENTS.md 约定

License

见 LICENSE

Documentation

Overview

Package metrics 提供通用的 Prometheus 指标注册和初始化（framework-agnostic）。

所有 enjoydream 后端服务共享此包，保持指标命名和标签的一致性。 本包只暴露 Registry 与指标类型，不绑定任何 HTTP 框架； HTTP 适配器位于 hertz.MetricsHandler / hertz.MetricsHandlerFor / hertz.InitAndRegister。

提供的指标

• app_build_info{service, commit, branch, build_time, go_version} — 构建信息
• app_start_time_seconds — 进程启动时间戳

快速接入

在 main.go 中：

metrics.Init("my-service")
// Hertz 适配器：
r.GET("/metrics", hertz.MetricsHandler())
// 或使用自定义 Registry（推荐与 middleware.PrometheusMetrics 共享）：
r.GET("/metrics", hertz.MetricsHandlerFor(metrics.Registry))

build.sh 改动

所有服务改为注入 ekit/version 包的变量：

MOD="github.com/oekit/metrics"
LDFLAGS="-X ${MOD}/version.BuildCommit=${GIT_COMMIT} ..."

自定义 Registry

使用独立的 Registry 避免与全局 prometheus.DefaultRegistry 冲突：

registry := metrics.Registry
// 传给 middleware.NewPrometheusMetrics 或 hertz.MetricsHandlerFor

Index

• Variables
• func Init(serviceName string)

Variables

var (
	// BuildInfo 暴露构建元数据（commit、branch、build_time、go_version）。
	BuildInfo = prometheus.NewGaugeVec(prometheus.GaugeOpts{
		Name: "app_build_info",
		Help: "Build information about the service",
	}, []string{"service", "commit", "branch", "build_time", "go_version"})

	// StartTimeSeconds 记录进程启动的 Unix 时间戳。
	StartTimeSeconds = prometheus.NewGauge(prometheus.GaugeOpts{
		Name: "app_start_time_seconds",
		Help: "Unix timestamp of service start time",
	})
)

var Registry = prometheus.NewRegistry()

Registry 是自定义的 Prometheus 注册器。 传入 ekit/middleware 的 PrometheusMetrics 时使用，避免全局 Registry 冲突。

Functions

func Init

func Init(serviceName string)

Init 注册所有通用指标并设置初始值。 参数 serviceName 用于 app_build_info 的 service 标签，如 "fuxi_engine"、"moyu-server"。 必须在 main.go 中调用，且在启动 Hertz server 之前。 多次调用是安全的，只有第一次调用会注册指标。