看板与查询 · 怎么做一个有用的看板

最实用的功能，也是“看板不该复制粘贴”的关键。

变量 $service  ← 从 label_values(up, job) 动态取值
变量 $instance ← 从 label_values(up{job="$service"}, instance) 级联

然后面板里写：

sum(rate(http_requests_total{job="$service"}[5m]))

于是一个看板 = 所有服务的看板，顶部下拉框一切换就换了对象。

几个关键用法：

• 级联变量 —— $instance 的取值依赖 $service。选了服务，实例列表自动过滤。
• $__rate_interval —— 这个内置变量值得专门说。第 4 部分讲过 rate() 的窗口至少要 4 倍抓取间隔，而 Grafana 不知道你的抓取间隔。$__rate_interval 会自动算出一个安全的窗口（基于面板的 step 和数据源配置的 scrape_interval）。

  rate(http_requests_total[$__rate_interval])   ← 比硬编码 [5m] 更稳

  硬编码 [5m] 的问题：用户把时间范围拉到 30 天，step 变成 30 分钟，而你的窗口还是 5 分钟——大部分求值点的窗口里可能只有 0 个采样点（第 4 部分讲过会返回空），图上全是断线。$__rate_interval 自动跟着 step 放大，这个坑很多人踩过。
• repeat（重复面板） —— 按变量的每个值自动生成一行/一个面板。比如“每个实例一个 CPU 图”，不用手工加 20 个。

变量把“看板”从“一次性产物”变成了“模板”——这是看板能被复用、被维护的前提。

UI 上点出来的看板，有三个必然的问题：

• 没有版本控制 —— 谁改的？改了什么？想回滚？不知道。
• 没法复制到别的环境 —— 测试环境的看板要重新点一遍。
• 会腐烂 —— 人走了，看板留着，没人知道它还准不准。

解法：把看板定义（JSON）放进 Git，用 provisioning 自动加载。

# provisioning/dashboards/main.yaml
apiVersion: 1
providers:
  - name: 'my-dashboards'
    folder: 'Services'
    type: file
    options:
      path: /var/lib/grafana/dashboards    # ← 从这个目录加载 JSON
    allowUiUpdates: false    # ← 禁止 UI 改!强制走 Git

allowUiUpdates: false 是关键的一步：它强制所有变更走代码评审。否则总有人在 UI 上“临时改一下”，然后那个改动就永远地和 Git 里的版本分叉了。

更进一步：用 Grafonnet（Jsonnet）或 Terraform 生成看板 —— 好处是能抽象：定义一个“标准服务看板”函数，20 个服务调用它生成 20 个看板。改一处，20 个全更新。

这和告警规则该走代码是同一条原则：可观测性配置是基础设施，该有和代码一样的工程纪律（评审、版本、可复现）。手工点出来的东西，注定腐烂。

这是本章最重要的一条，第 2 部分提过，这里落实：看板的结构应该长得像排障的思路，而不是像“我们能采到的指标列表”。

❌ 典型的坏看板：

一页 50 个图,按"我们有什么指标"排列:
[CPU] [内存] [磁盘] [网络] [GC] [线程] [连接池] [QPS] [延迟] [错误] ...

问题：出事时，你不知道该先看哪个。 50 个图里有 48 个是绿的，而你要在剩下的里面找关联——这是人肉做 join，效率极低。

✅ 好看板：分层，一层一个问题

┌─ 第一层:用户体验好吗?([黄金信号](/manual/observability/four-golden-signals),4 个图)
│   [成功率] [P50/P99] [QPS] [错误预算剩余]
│        ↓ 红了才往下看
├─ 第二层:是哪一跳?([RED](/manual/observability/red-method),按依赖分解)
│   [本服务 RED] [下游 A 的 RED] [下游 B 的 RED]
│        ↓ 定位到某跳才往下看
└─ 第三层:是哪个资源?([USE](/manual/observability/use-method))
    [CPU U/S] [内存 U/S] [连接池 U/S] [磁盘 U/S]

检验标准（再说一遍，因为它真的好用）：

如果值班的人被叫醒后，能顺着看板从上往下，在 5 分钟内定位到根因，这个看板就是好的。 如果他还是得去 tail 日志或者问人，那它就是装饰品。

实现上，用 Grafana 的 row（行） 折叠：第一层展开，二三层默认折叠。平时只看 4 个图，出事了再逐层展开——这直接把“分层”变成了物理结构。

• 面板上放 PromQL 的“意图” —— 用面板的 description 写清“这个图在回答什么问题”。三个月后你自己都会忘。
• 用 recording rule 喂看板 —— 不只是快，而且看板里的表达式变得极简（service:http_errors:ratio_rate5m vs 一大坨嵌套查询），可读性天差地别。
• 给关键面板配 runbook 链接 —— 面板的 links 里放上“这个图异常时该怎么办”。
• 注意时间范围的默认值 —— 默认 30 天 = 每次打开都是一次昂贵查询。默认 1 小时或 6 小时。
• 别在一个面板里画 500 条线 —— 人眼分辨不了，而且数据传输和渲染都很贵。用 topk(10, ...) 或者聚合掉。