golang服务需先暴露/metrics接口，prometheus抓取后存入时序数据库，grafana再查询该数据库实现可视化；三者链路缺一不可，顺序错误或任一环节失败（如404、标签爆炸、直方图桶缺失）均导致监控失效。
Golang 服务本身不“配置图形化监控面板”——你真正要做的，是让 Go 暴露指标、Prometheus 抓取指标、Grafana 查 Prometheus。三者缺一不可，顺序不能乱。
/metrics 接口 404 或返回空内容
这是第一道坎，卡住就全链路失效。不是 Grafana 配错了，是 Prometheus 根本没拿到数据。
-
http.Handle("/metrics", promhttp.Handler())必须在http.ListenAndServe()之前调用；放错位置会导致 handler 注册失败，curl返回 HTTP 200 但 body 为空 - 路径必须严格是
/metrics，不是/metrics/、/monitor/metrics或带前缀的路径；Prometheus 默认只拉/metrics - 如果用了中间件（JWT 鉴权、CORS、日志拦截器），必须显式跳过
/metrics路径，否则 Prometheus 抓取会返回 401/403 或超时 - 监听地址不能写
127.0.0.1:8080；Docker/K8s 环境下，localhost对 Prometheus 不可达，得用0.0.0.0:8080
Counter 和 Histogram 打点后 Prometheus 查不到数据
注册了指标 ≠ 有数据。Prometheus 里查 http_requests_total 或 http_request_duration_seconds_bucket 为空，大概率是打点逻辑没触发或类型误用。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 只调用
prometheus.MustRegister()不够，必须在业务路径中实际调用.Inc()、.Add(1)或.Observe(duration.Seconds())；没打点 = 零值静默 -
Histogram初始化时必须传非空Buckets，例如[]float64{0.05, 0.1, 0.25, 0.5, 1, 2.5}；漏掉或传空 slice，_bucket系列指标根本不会生成 - 标签必须用
.WithLabelValues("GET", "/api/user")，别用.With(map[string]string{})；后者因 map key 顺序不可控、拼写易错，极易引发 series 爆炸 - 记录耗时推荐用
prometheus.NewTimer()包裹 handler，比手写start := time.Now(); defer更可靠，避免 panic 导致打点丢失
Grafana 查不到指标？先看 Prometheus Targets 页面
Grafana 是“最后一环”，它连的是 Prometheus，不是你的 Go 服务。面板空白，优先查 Prometheus 是否真拿到了数据。
- 打开
http://<prometheus-host>:9090/targets</prometheus-host>，确认你的 job 状态是UP，Last Scrape时间距现在不超过scrape_interval（默认 15s）；显示DOWN就别调 Grafana，先看右侧的Scrape error - targets 地址必须写 Go 服务**真实可达的地址**：Docker Compose 里 Prometheus 容器要写
host.docker.internal:8080（Mac/Win），K8s 里要用 Service DNS 名，比如my-go-service:8080 - 确保 Prometheus 的
scrape_configs中job_name和static_configs.targets正确，且没有被网络策略、防火墙或 Service Mesh 拦截
直方图查询语法写错导致分位数为空
即使 http_request_duration_seconds_bucket 有数据，histogram_quantile(0.95, ...) 仍可能返回空，常见于 PromQL 写法错误或时间范围不匹配。
- 必须套用
rate()或increase()：正确写法是histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))，不能直接查原始 bucket - 时间范围
[5m]要大于等于 Prometheus 的scrape_interval，否则 rate 计算无足够样本点 - 确保 label match 一致：如果打点用了
.WithLabelValues("GET", "200")，查询时也要加{method="GET",status="200"}，否则聚合跨 label 失效 - 检查 bucket 边界是否覆盖实际延迟——若所有请求都 _bucket{le="0.05"} 以外全为 0，分位数计算失真
最常被忽略的是：Grafana 面板里写的 PromQL，和你在 Prometheus 表达式浏览器里跑出来的结果，可能根本不是同一组数据——因为 Grafana 默认带时间变量（如 $__range），而手动测试时用的是固定区间。调试时务必在 Grafana 面板右上角点「Inspect → Data」，看原始响应体里有没有 series、label、value。没数据，问题一定出在前两环。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
