gin服务暴露/metrics返回404或空响应，根本原因是未用gin.wraph(promhttp.handler())正确挂载prometheus handler，且需确保路径严格匹配、跳过中间件、监听0.0.0.0而非127.0.0.1。
为什么 Gin 服务暴露 /metrics 返回 404 或空响应
这不是 Grafana 的问题，而是 Gin 没把 promhttp.Handler() 正确挂载到路由系统里。Gin 的 GET、HandleFunc 不兼容 Prometheus 的 handler 类型——它需要 HTTP 标准的 http.Handler，不是 Gin 的 gin.HandlerFunc。
- 必须用
gin.WrapH(promhttp.Handler())包一层，不能写r.GET("/metrics", ...)或直接http.Handle（后者在 Gin 启动后才注册会失效） -
/metrics路径必须严格匹配，不能带前缀（比如/api/metrics），也不能结尾多斜杠（/metrics/） - 如果用了 JWT、CORS、日志等中间件，要确保
/metrics路由跳过它们——否则 Prometheus 抓取会返回401、403或超时 - 监听地址必须是
0.0.0.0:8080，不是127.0.0.1:8080；Docker/K8s 环境下，localhost对 Prometheus 容器不可达
Gin 中间件里怎么安全打点 Histogram 和 Counter
打点逻辑写在中间件里最自然，但容易漏掉错误路径、panic 情况或标签不一致。直接手写 start := time.Now() + defer 不够健壮，尤其在 handler panic 时可能不执行 Observe()。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 推荐用
prometheus.NewTimer()：它自动处理 panic 场景，且能绑定 label 值，例如timer := prometheus.NewTimer(httpDuration.WithLabelValues(r.URL.Path, r.Method, strconv.Itoa(status))) - Counter 打点必须在所有出口路径都覆盖：包括 404、500、重定向等；别只在
w.WriteHeader(200)后调用.Inc() - 标签务必用
.WithLabelValues("GET", "/user", "200")，不要用.With(map[string]string{...})——map 键顺序不确定，会导致同一语义生成多个 series，引发高基数问题 - 直方图初始化时必须显式传
Buckets，比如[]float64{0.05, 0.1, 0.25, 0.5, 1, 2.5}；空 buckets 或漏掉.Observe()调用，_bucket指标就永远不会出现
Prometheus targets 显示 DOWN，Grafana 面板空白怎么办
别急着改 Grafana 面板或 PromQL 查询。90% 的“查不到指标”问题，根源在 Prometheus 根本没拿到数据。先打开 http://<prometheus-host>:9090/targets</prometheus-host> 看状态。
- 状态为
DOWN或Last Scrape超过scrape_interval（默认 15s），说明网络或配置断了 - Docker Compose 环境下，
targets必须填host.docker.internal:8080（Mac/Win），Linux 则填宿主机真实 IP；绝不能写localhost:8080 - K8s 环境下，确认 Service 和 Endpoint 存在，且
target填的是 ClusterIP:Port 或 Pod IP:Port，不是 Deployment 名 - 检查
prometheus.yml中scrape_configs是否包含该 job，且 indentation 正确（YAML 对空格敏感）
Grafana 查不到 go_goroutines 或 http_requests_total 怎么排查
运行时指标（如 go_goroutines）和业务指标（如 http_requests_total）暴露机制不同，失败原因也不同。
-
go_goroutines类指标默认不自动注册：低版本 client_golang 需显式调用prometheus.MustRegister(prometheus.NewGoCollector())；v1.14+ 默认启用，但若你调用了prometheus.Unregister或自定义 Registerer，可能已移除 -
http_requests_total为空，先curl http://your-service:8080/metrics | grep http_requests_total—— 如果没输出，说明指标根本没注册或没打点；如果输出了但值为 0，说明打点逻辑没触发（比如中间件没生效、handler 没走通） - 验证指标是否被 Prometheus 存储：在 Prometheus 表达式浏览器里直接输
http_requests_total，看有没有时间序列；没有就不是 Grafana 问题，是上游断链 - 注意
rate()函数需要至少两个采样点，新启动的服务可能前 2 分钟查rate(http_requests_total[5m])为空，属正常现象
/metrics 的放行逻辑、以及 Histogram 的 Buckets 和 Observe() 是否成对出现——这三个地方出错，面板就会一直白着。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
