Go语言需借助prometheus/client_golang实现Metrics上报，关键在于指标设计贴合真实学习行为；应使用GaugeVec而非Counter跟踪会重置的进度指标，并通过label（如user_id、deck_id）避免cardinality爆炸。
Go 语言本身不内置 Metrics 上报能力，但通过 prometheus/client_golang 可以快速构建符合可观测性规范的指标采集端点；关键不在“能不能做”，而在于指标设计是否贴合真实语言学习行为——比如用户背单词频次、遗忘率计算、练习响应延迟，这些才是值得暴露的 Counter 或 Histogram。
用 prometheus.NewGaugeVec 跟踪用户学习状态变化
语言学习场景中，静态计数器（Counter）容易误用：比如“今日完成单词数”不能简单用 Counter 累加，因为服务重启后会归零，而业务上需要的是“当前有效学习 session 中的累计值”。这时更适合用 Gauge，配合 label 区分 user_id 和 deck_id：
var learningProgress = prometheus.NewGaugeVec(
prometheus.GaugeOpts{
Name: "language_learning_progress",
Help: "Current progress percentage per user and deck",
},
[]string{"user_id", "deck_id"},
)
常见错误是把 user_id 当作 label 值直接拼进 metric name（如 progress_user_123），这会导致指标 cardinality 爆炸，Prometheus 查询变慢甚至 OOM。必须用 vector + label，且提前预估 label 组合上限（比如用户量
用 prometheus.NewHistogramVec 记录练习响应时间分布
语言学习 App 的核心交互（如点击“显示释义”“提交拼写”）对延迟敏感，单纯记录平均耗时没意义，必须看 P90/P99 分位。用 Histogram 比 Summary 更合适，因为前者服务端聚合，后者客户端计算分位数不可靠：
立即学习“go语言免费学习笔记（深入）”；
-
Buckets设置要贴合实际：学外语的用户网络环境差异大，建议从[]float64{0.05, 0.1, 0.2, 0.5, 1.0, 2.0, 5.0}开始，覆盖 50ms 到 5s 区间 - label 至少包含
action（如"show_definition"、"check_spelling"）和language（如"en"、"ja"），避免把word_text这类高基数字段当 label - 务必在 defer 中调用
histogram.WithLabelValues(...).Observe(time.Since(start))，否则 panic 时漏埋点
避免 prometheus.MustRegister 导致重复注册 panic
Go 项目常把 metrics 初始化分散在多个包里，比如 auth/metrics.go、study/metrics.go，各自调用 prometheus.MustRegister 就会触发 duplicate metric descriptor 错误。根本解法是集中注册：
- 只在
main()或启动入口处调用一次prometheus.MustRegister - 各模块定义自己的
var指标变量，但不自行注册 - 如果使用 wire/di 框架，把
prometheus.Registerer注入到各模块，由模块调用registerer.MustRegister(...)，但 registerer 实例必须全局唯一
另一个坑是测试时反复调用 prometheus.Unregister 后又重注册，导致指标残留——应改用 prometheus.NewRegistry() 隔离测试环境。
HTTP handler 中暴露 /metrics 时别忽略中间件顺序
很多 Go Web 框架（如 Gin、Echo）默认把 Prometheus handler 放在路由最后，结果被 auth 中间件拦截，返回 401；或者放在最前，导致所有请求（包括健康检查）都打点，污染指标。正确做法是：
- 单独起一个无认证的 HTTP server（如
:9090/metrics），专用于暴露指标 - 若必须复用主 server，确保
/metrics路由在所有中间件之前注册（Gin 中用router.Any("/metrics", promhttp.Handler())并放在最顶部） - 不要用
promhttp.HandlerFor(prometheus.DefaultGatherer, ...)，而是显式传入自定义 registry，防止第三方库悄悄注册干扰指标
真正难的不是写几行指标代码，而是判断哪些行为值得量化、哪些 label 会拖垮 Prometheus、以及如何让运维能一眼看出“今天日语听力练习卡顿是不是 CDN 导致的”——这要求你在定义 histogram.WithLabelValues("listening", "ja") 时，就已经想好了 Grafana dashboard 的筛选逻辑和告警阈值。
