必须在init()或main()开头一次性注册，否则panic；重复调用MustRegister()、延迟注册或跨包同名指标均导致运行时崩溃。
prometheus/client_golang 必须在启动时注册，否则 panic
Go 应用暴露自定义 metrics 给 Prometheus 抓取，prometheus.MustRegister() 只能调用一次，且必须在 init() 或 main() 开头完成。任何延迟注册（比如放在 HTTP handler、中间件、goroutine 里）都会导致运行时崩溃：panic: duplicate metrics collector registration attempted。
- 多个包各自声明
var httpRequestTotal = prometheus.NewCounterVec(...)→ 各自调用MustRegister()→ 冲突 panic - 测试中反复执行
main()（如多个 test 文件含func main()）→ 注册逻辑重复触发 → 崩溃 - 解决方案：统一声明全局指标变量，在单点初始化+注册；测试场景改用
prometheus.Register()（失败不 panic），或用sync.Once包裹注册逻辑
Gin 框架自动埋点需避开 runtime 注册陷阱
Gin 官方推荐的可观测性方案（如编译期注入、eBPF）本质是绕过手动注册，但若混用 SDK 手动埋点，极易踩到指标注册时机错位的问题。例如在 Gin 中间件里调用 prometheus.MustRegister()，看似“每次请求都注册”，实则第一次请求就 panic。
- 正确做法：指标定义和注册必须在
main()最前段完成，Gin 路由注册之后 - 带标签指标（如
http_request_duration_seconds）必须严格校验WithLabelValues("GET", "200")的参数数量与内容——空字符串、特殊字符、label 数量不匹配会触发inconsistent label cardinalitypanic，且无法被 recover 捕获 - HTTP 请求计数用
CounterVec，延迟统计必须用HistogramVec；误用Counter记毫秒值，PromQL 的rate()和histogram_quantile()全部失效
编译期插桩不是“替代 SDK”，而是规避注册时机问题
Go 没有字节码增强能力，所以编译期注入（如可观测 Go Agent）本质是在 go build 阶段自动插入指标采集代码，并确保所有指标变量声明和 prometheus.Register() 调用被收束到单一初始化路径，从源头杜绝多点注册。
- 它不改变
prometheus/client_golang的底层约束，只是把原本分散在业务代码里的埋点逻辑，提前固化到编译产物中 - 仍需注意：编译期生成的指标名不能与手写指标重名；若同时启用 pprof 和自定义 metrics，/debug/pprof/ 和 /metrics 两个端点要避免路由冲突
- 交叉编译（
GOOS=linux GOARCH=arm64）不影响插桩结果，但需确认目标平台的 Prometheus client 版本兼容性（推荐 v1.16+）
pprof 和 metrics 共存时的端点隔离
net/http/pprof 默认注册在 /debug/pprof/，而 promhttp.Handler() 通常挂载在 /metrics。两者可共存，但生产环境必须限制访问权限，否则暴露过多运行时细节。
立即学习“go语言免费学习笔记（深入）”；
- 不要把
pprof挂到根路径（如http.Handle("/", pprof.Handler())），会覆盖业务路由 - 若用 Gin，应显式注册：
r.GET("/debug/pprof/*path", gin.WrapH(http.HandlerFunc(pprof.Index)))，避免中间件干扰 -
expvar和promhttp不兼容——二者都试图处理/debug/vars，选其一即可；prometheus/client_golang已包含标准运行时指标（goroutines、gc 等），无需再开 expvar
MustRegister()，而是让所有包、所有测试、所有构建流程都遵守“注册只一次”这条铁律。一旦漏掉某个 test main、某个子模块的 init 函数、某次 CI 构建中的 vendor 覆盖，上线后第一秒就 panic。 
