go服务/metrics端点返回空或查不到业务指标，根本原因是自定义指标未显式调用prometheus.mustregister()注册到defaultregisterer或指定registry；运行时指标自动注册，但业务指标必须在init/main中提前注册，且不可重复或在handler中注册。
直接暴露 /metrics 端点不等于监控就跑通了——90% 的 Go 服务在 Prometheus 抓取失败时，问题不出在配置，而在指标注册时机、注册器隔离或 HTTP handler 绑定方式上。
为什么 promhttp.Handler() 返回空指标？
这是最常踩的坑：代码里写了 http.Handle("/metrics", promhttp.Handler())，curl http://localhost:8080/metrics 能返回数据，但 Prometheus Target 显示 UP 却查不到任何 http_requests_total 这类业务指标。
- 根本原因是
promhttp.Handler()（已废弃）或未传入注册器的promhttp.HandlerFor()默认只暴露prometheus.DefaultRegisterer里已注册的指标；而你定义的requestCounter如果没调用prometheus.MustRegister()，它压根不在这个注册器里 - Go 运行时指标（
go_*、process_*）是自动注册的，所以你能看到它们，但业务指标不会“自动出现” - 如果用了
promauto.NewCounterVec()却没指定prometheus.DefaultRegisterer或自定义注册器，它内部会 fallback 到默认注册器——但前提是没被其他包提前 panic 掉（见下一条）
panic: duplicate metrics collector registration 怎么定位？
启动时崩溃报这个错，不是并发写冲突，而是两个地方试图注册同名指标。Prometheus 对指标名+标签组合做强校验，不允许重复。
- 常见场景：多个
init()函数都调用了prometheus.MustRegister(requestCounter)，尤其在中间件、工具包、主应用都各自初始化了同一套指标 - 用
promauto时更隐蔽：不同包都写promauto.NewCounterVec(...Name: "http_requests_total"...)，只要包被 import，就会触发注册，且无法绕过 - 解决方法不是加锁，而是收口：统一在
main()或服务初始化入口处创建指标并注册，其他模块只接收指标实例（如*prometheus.CounterVec）作为参数注入 - 调试技巧：启动前加
prometheus.Unregister(requestCounter)再注册，或改用prometheus.NewRegistry()隔离，避免污染全局
如何安全暴露带标签的 Histogram 指标？
延迟、响应体大小这类分布型指标必须用 Histogram 或 Summary，但新手常因标签管理不当导致性能下降或 panic。
-
prometheus.NewHistogramVec()的Name字段只允许小写字母、数字、下划线、冒号；Help不能为空字符串，否则MustNewHistogramVec直接 panic - 标签键（
[]string{"method", "endpoint"}）必须在初始化时声明，运行时WithLabelValues("GET", "/api/user")的顺序、数量必须严格匹配，错一位就 panic - 别在 HTTP handler 里反复调用
WithLabelValues()创建新指标对象——虽然开销不大，但高频请求下会增加 map 查找和内存分配；建议提前缓存常用组合：getUsersHist := httpRequestDuration.WithLabelValues("GET", "/api/users") - 注意
Buckets设置：太密（如[0.001, 0.002, ..., 1]）会导致指标膨胀；推荐用prometheus.ExponentialBuckets(0.001, 2, 10)
多实例部署时怎么避免指标冲突？
容器化或蓝绿发布场景下，多个服务实例共用同一个 Prometheus job_name，但指标名相同、标签又没区分实例维度，会导致数据覆盖或聚合错误。
- Prometheus 默认不带实例标识，必须手动加标签：在
scrape_configs里用relabel_configs注入instance，或在 Go 代码中给所有指标加instance标签（如WithLabelValues("GET", "/api/user", os.Getenv("HOSTNAME"))） - 更稳妥的做法是用独立注册器 +
promhttp.HandlerFor(reg, ...)，每个实例启动时 new 一个prometheus.NewRegistry()，再把指标注册进去——这样即使跨进程误连，也不会互相污染 - 如果用了 go-zero、Go Kit 等框架，它们通常内置了实例标签注入逻辑（如 go-zero 的
Prometheus.Host配置会自动作为 label），但需确认是否启用，不能只依赖默认行为
真正卡住人的从来不是“怎么写指标”，而是“什么时候注册”“往哪个注册器注册”“标签值从哪来”。这三个问题没理清，可视化面板永远只能看到 go_goroutines 这种通用指标，业务逻辑一概黑盒。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
