Beego中自定义Counter或Gauge必须在init()或main()开头注册且挂载/metrics路由，否则Prometheus抓不到指标；需包级变量定义、全局注册器注册、http.Handle("/metrics", promhttp.Handler())显式挂载，并避免标签高基数与命名冲突。
Beego里注册自定义Counter或Gauge必须在init()或main()开头
Beego服务启动后Prometheus抓不到指标，90%是因为指标注册时机错了。Go的prometheus.MustRegister()不是“定义即生效”，而是必须在HTTP服务监听前完成注册——否则/metrics端点返回空或404。
常见错误是把注册逻辑写在某个Controller的Get()方法里，或者放在func (c *MyController) Prepare()中，这会导致每次请求都尝试注册，直接panic。
- 所有自定义指标变量（如
myReqCounter）必须声明为包级变量 - 注册动作统一放在
init()函数里，或main()最开始、beego.Run()之前 - 别用
prometheus.NewRegistry()另起炉灶，除非你明确要隔离指标；默认用全局注册器即可
Beego暴露/metrics端点需要手动挂载，不能依赖自动发现
Beego不会像Spring Boot Actuator那样自动暴露/metrics。只调MustRegister()，不挂路由，Prometheus永远404。
必须显式调用http.Handle("/metrics", promhttp.Handler())，且要在beego.Run()之前执行。如果你用了Beego的beego.BConfig.Listen.HTTPPort启动，那这个http.Handle就得和它共用同一个http.ServeMux或提前接管。
- 推荐做法：在
main()里先调http.Handle("/metrics", promhttp.Handler())，再调beego.Run() - 如果Beego启用了
EnableDocs = true，注意别让Swagger路由覆盖了/metrics - 验证方式：curl http://localhost:8080/metrics | grep "my_req_total" —— 有输出才说明挂载成功
带标签的Vec指标必须预定义维度，避免运行时爆炸
想按controller和method统计请求量？别在Handler里拼字符串再注册新指标。用CounterVec，但标签名和顺序必须严格一致，且维度值不能来自不可控输入（比如用户ID、traceID）。
例如reqCounter = prometheus.NewCounterVec(prometheus.CounterOpts{...}, []string{"controller", "method"})，后续打点必须用reqCounter.WithLabelValues("user", "POST")，顺序错一位就panic，传3个值也panic。
- 标签名强制小写+下划线，如
"tenant_id"，不能写"TenantID"或"tenant-id" - URL路径里的动态ID（如
/user/123）必须归一化为/user/{id}再作为label值，否则基数爆炸 - 高基数字段（手机号、session_id）绝对不要塞进label，改用无label的Counter按error_type分类
Beego内置监控和自定义指标别混用同一命名空间
Beego自带beego.BeeLogger和beego.GlobalMetrics会暴露一些基础指标（如goroutine数、内存使用），它们用的是内部注册器。你自己的prometheus.MustRegister()走的是全局注册器——两者不冲突，但命名容易撞车。
比如你定义http_request_total，而Beego或第三方库也注册同名指标，Prometheus抓取时会报duplicate metrics collector registration attempted。
- 自定义指标名必须带业务前缀，如
order_service_http_requests_total，别用通用名 - 检查已有指标：启动后访问
/metrics，搜索# HELP行确认没重名 - 如果要用Beego的
GlobalMetrics，记得它默认不开启，需在app.conf里配EnableMetrics = true，且它的指标名以beego_开头，可安全共存
Beego集成Prometheus最难的不是写几行代码，而是守住注册时机、路由挂载、标签设计这三道关。漏掉任意一个，指标就静默失效，而日志里往往不报错——你得主动curl /metrics去验证，而不是等告警响了才发现。
