Grafana集成起点是Go服务正确暴露/metrics端点给Prometheus；需注册promhttp.Handler()、监听0.0.0.0、放行中间件、自定义业务指标并规范打点，避免高基数标签。
Grafana 本身不接收或存储 Go 服务的指标，它只查 Prometheus；所以“集成 Grafana”真正的起点，是让你的 Go 服务把自定义业务指标正确暴露给 Prometheus。
Go 服务必须跑通 /metrics 端点且返回有效指标文本
这是整个链路的生死线。没这一步，Grafana 就是空转。
-
http.Handle("/metrics", promhttp.Handler())必须在http.ListenAndServe()之前注册，否则 handler 不生效，curl http://localhost:8080/metrics会返回 200 + 空 body - 路径必须严格是
/metrics，不能是/metrics/、/monitor/metrics或带前缀（如/api/metrics），Prometheus 默认只拉这个路径 - 如果用了中间件（JWT、日志、CORS），要显式放行
/metrics：比如用if r.URL.Path == "/metrics" { next.ServeHTTP(...) }跳过鉴权，否则 Prometheus 抓取会卡在 401/403 - Docker/K8s 环境下，监听地址不能写
127.0.0.1:8080，得用0.0.0.0:8080；Prometheus 容器里访问不到 localhost
自定义业务指标必须注册 + 打点，不能只靠默认收集器
默认的 promhttp.Handler() 只暴露 go_goroutines、go_memstats_alloc_bytes 这类运行时指标，对业务无感。你要的「订单创建数」「支付成功率」必须自己定义、注册、并在代码中触发。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 用
promauto.NewCounter()替代prometheus.NewCounter().MustRegister()，避免重复注册 panic - 直方图打点必须调用
.Observe(duration.Seconds())，且初始化时指定Buckets（如[]float64{0.05, 0.1, 0.25, 0.5, 1, 2.5}），漏掉Observe()或Buckets为空，_bucket指标根本不会生成 - 标签务必用
.WithLabelValues("POST", "200", "/order/create")，别用.With(map[string]string{...})—— map key 顺序不一致会导致 series 爆炸，Prometheus 存不下也查不出 - 延迟打点推荐用
prometheus.NewTimer()包裹 handler，比手写start := time.Now(); defer ...更可靠，尤其在 panic 场景下也能保证打点
Grafana 查不到数据？先确认 Prometheus targets 是 UP，再看 label 和查询语法
Grafana 面板空白，90% 的问题不在 Grafana，而在 Prometheus 根本没拿到数据，或拿到了但你查错了维度。
立即学习“go语言免费学习笔记（深入）”；
- 打开
http://<prometheus-host>:9090/targets</prometheus-host>，确认你的 job 状态是 UP，Last Scrape时间距现在不超过scrape_interval（默认 15s）；显示 DOWN 就别调 Grafana，先看右侧的Scrape error - targets 地址必须写 Go 服务**真实可达的地址**：Docker Compose 里写
host.docker.internal:8080（Mac/Win）或宿主机 IP（Linux），不能写localhost:8080 - PromQL 查询必须带正确 label 过滤，比如
rate(http_requests_total{job="service-order"}[5m])；漏掉{job="..."}会跨服务混算 - 直方图分位数必须套两层：先
sum(rate(..._bucket[5m])) by (le)，再套histogram_quantile(0.95, ...)；少一层sum by (le)，结果就是空
高基数 label 是隐形炸弹，别把 user_id、request_id 当标签打
一个 user_id="u123" 标签会让 Prometheus 为每个用户生成独立时间序列，10 万用户 = 10 万 series。内存暴涨、查询变慢、甚至 OOM，都是常态。
- 能聚合就聚合：用
region="cn-east"、env="prod"这类低基数维度，而不是具体 ID - 想追踪单次请求？用 OpenTelemetry 做 trace，不是靠 Prometheus label
- 业务指标命名要有业务含义，比如
order_created_total、payment_succeeded_ratio，别起metric_v2_1这种名字，后期没人能维护 - 生产环境暴露
/metrics前，检查是否加了基础认证或网络白名单，避免敏感指标被未授权访问
