Grafana不部署在Go工程中，而是独立服务；需Go暴露/metrics接口、Prometheus抓取、Grafana连接Prometheus数据源。关键点：/metrics响应末尾必须换行；指标须显式注册；Prometheus抓取地址须为容器网络可达的真实地址；Grafana数据源必须指向Prometheus查询接口而非Go服务。
Grafana 本身不部署在 Go 工程里，它是一个独立服务；真正要部署的是 Go 应用暴露指标的能力 + Prometheus 抓取能力 + Grafana 连接 Prometheus。跳过这个认知偏差，后续所有配置都会卡在“为什么面板没数据”上。
Go 程序必须暴露 /metrics 接口且格式严格合规
不是只要写了 http.Handle("/metrics", promhttp.Handler()) 就万事大吉——常见失败点全在这儿：
-
promhttp.Handler()返回的响应体必须以换行结尾，否则 Prometheus 解析会报text format parsing error；手写指标或误用fmt.Fprintf漏掉末尾\n是高频原因 - 所有自定义指标（比如
http_requests_total）必须显式注册：用prometheus.MustRegister()或promauto.NewCounter()，否则/metrics里根本不会出现 - 避免在
/metricshandler 里调用 DB 查询、RPC 或锁竞争操作——promhttp.Handler()是同步阻塞的，慢响应会拖垮整个健康检查路径 - 如果用了
promauto包（推荐），它自动注册，但要注意包初始化顺序：变量声明必须在main()执行前完成，否则注册时机错乱
Prometheus 的 scrape_configs 必须指向 Go 实例真实可访问地址
本地开发时写 localhost:8080 没问题，但一上 Docker/K8s 就失效——根本原因是 localhost 在容器内指自己，不是宿主机。
- 查清 Prometheus 容器网络视角下的 Go 服务地址：K8s 用 Service 名（如
myapp:8080），Docker Compose 用 service 名（如go-app:8080），裸机部署则填宿主机 IP - 确认端口映射和防火墙：Prometheus 能否从自身容器/机器 curl 通
http://<target>:8080/metrics？这是最直接的验证方式 - 别信
targets列表里写的地址，要看 Prometheus UI 的Status → Targets页面是否显示为UP；状态为DOWN时 hover 查看具体错误（常见是 connection refused 或 timeout） - 如果 Go 服务启用了 TLS，Prometheus 配置需加
scheme: https和tls_config，否则默认走 HTTP
Grafana 数据源必须连 Prometheus，不是 Go 程序
新手常把 Grafana 数据源 URL 填成 http://localhost:8080（Go 地址），结果查不到任何指标——Grafana 只认 Prometheus 的查询接口 /api/v1/query。
立即学习“go语言免费学习笔记（深入）”；
- 填对 Prometheus 地址：如果是本地 Docker 启动，填
http://host.docker.internal:9090（Mac/Win）或宿主机真实 IP（Linux）；K8s 环境填 ClusterIP Service 地址，如http://prometheus-operated:9090 - 测试连接前先手动访问该地址的
/api/v1/query?query=up，确保返回 JSON 且status: "success" - Grafana 中新建 dashboard 后，Panel 的 Query 编辑器里输入
go_goroutines或rate(http_requests_total[5m])，若提示No data，优先排查 Prometheus 是否已抓到数据（去 Prometheus UI 查 Graph） - 不要给 Go 程序加 CORS 头——Prometheus 是服务端拉取，CORS 完全无关；加了反而可能干扰调试
多维指标大屏依赖标签（labels）设计，不是堆图表
一个 http_requests_total{method="GET", status="200", path="/api/user"} 和 http_requests_total{method="POST", status="500", path="/api/order"} 是两条独立时间序列；没有标签，就做不到按接口、方法、状态码下钻分析。
- 定义 Counter/Histogram 时，在
prometheus.CounterOpts或prometheus.HistogramOpts里明确写ConstLabels或留空让业务代码动态打标 - HTTP 中间件里记录耗时时，用
duration.WithLabelValues(r.Method, strconv.Itoa(statusCode), r.URL.Path).Observe(elapsed.Seconds())—— 标签值不能含空格、斜杠、等号等非法字符，路径建议截断或哈希处理 - Grafana 变量（Variables）依赖 Prometheus label 查询，例如
label_values(http_requests_total, method)；如果指标没打标，变量下拉就是空的 - 直方图（Histogram）比 Summary 更适合 Grafana 聚合：用
rate(http_request_duration_seconds_bucket[5m])+histogram_quantile(0.95, ...)算 P95，Summary 的 quantile 是客户端计算，Prometheus 无法重算
真正卡住人的从来不是 Grafana 界面怎么点，而是指标有没有进 Prometheus、进了之后有没有带可用标签、标签能不能被 PromQL 正确切分——这三步漏掉任意一环，大屏就只是静态图片。
