模板变量

变量解决什么问题

一份仪表盘服务所有环境、所有服务、所有实例——诀窍是把查询里的参数值抽成仪表盘顶部的下拉框，选择后全仪表盘的面板联动刷新。变量本质上是「查询文本的替换规则」。

类型总览

创建查询变量

1. 进入 Dashboard settings → Variables → Add variable，类型选 Query。
2. 选择数据源，Query 填一条返回值列表的语句，Prometheus 常用：

label_values(http_requests_total, instance)

3. 按需打开 Multi-value（多选）与 Include All option（附加「All」）。
4. 右侧 Preview of values 预览效果，满意后 Save。

引用语法

查询与面板标题里用 $instance 或 ${instance} 引用；正则匹配器写法：

rate(http_requests_total{instance=~"$instance", status=~"$status"}[5m])

多选与 All 会被 Grafana 自动展开成 (a|b|c) 形式的正则。变量定义里的 Regex 字段还能加工取值，例如 instance=~"(.+):80" 搭配捕获组 $1，下拉框里只显示主机名。

提示： =~ 正则匹配器下 All 会自然展开为全匹配；若查询用的是 = 精确匹配，需要手动设置 Value for All option，否则 All 会被展开成带管道的字符串导致查不到数。

依赖变量

B 变量的查询里引用 A 变量，B 的候选值就随 A 的选择而变——「环境 → 服务 → 实例」三级级联就是这么做的。变量列表的排列顺序影响加载顺序，被依赖的变量放前面。

重复面板与重复查询

• Repeated panels：在变量定义里指定某面板按该变量的每个选中值各复制一块。
• Panel options → Repeat：在面板编辑页做同样的事，范围更局部。

一个变量对应一块图的「舰队视图」，优先用重复面板；想在一张图里对比所有实例，则用多选加正则即可。

变量也能代码化

仪表盘 JSON 模型里的 templating.list 保存全部变量定义，因此变量随Provisioning：配置即代码一起管理，文件示例：

apiVersion: 1
providers:
  - name: 'platform'
    folder: 'Platform'
    type: file
    options:
      path: /var/lib/grafana/dashboards

注意： 该 YAML 中 version / apiVersion 指的是 provisioning 文件格式版本，与 Grafana 产品版本无关。

常见坑

• 下拉框是空的：变量查询同样受仪表盘时间窗口约束，窗口内无数据自然无候选值。
• 切换变量面板不动：确认面板查询真的引用了 $var；Builder 模式可能隐藏插值细节，切到 Code 检查。
• 分享链接丢了选择：URL 会自动携带 var-<name>=<value>；手写链接漏掉参数时，对方看到的是变量默认值。

下一步

• 用链接携带变量跳转，见仪表盘与面板链接。
• 标注查询里的标签过滤，见标注（Annotation）。
• 步长与时间范围的联动，见分屏对比与时间范围。