变量解决什么问题
模板变量让同一张看板适配多个目标：实例换了、环境变了、任务不同，都通过下拉选择切换，而不必复制多份看板。变量值会被代入查询表达式，因此变量本质上就是一段可参数化的查询。
查询类变量的几种写法
最常用的是取标签值，即列出某个指标上某个标签的全部取值；也可以按名称模式匹配出一批指标，或先跑一段查询再用正则从结果里提取需要的片段。选择哪种写法，取决于下拉项的来源是标签、指标名还是计算结果。
刷新时机与多选的影响
变量可以设为打开看板时刷新，也可以随时间范围变化刷新。多选时会把多个取值展开成匹配表达式，取值数量直接决定查询规模；高基数下拉不仅加载慢，还会让所有引用它的面板一起变重。
基本信息
| 引用写法 | $job 或 ${job}，可用于查询、标题与图例 |
|---|---|
| 多选 | 勾选后会把多个取值展开为匹配表达式 |
| 全选选项 | 需要为全部取值提供对应的匹配规则 |
| 刷新时机 | 打开看板时刷新，或随时间范围变化刷新 |
| 取值来源 | 标签值、指标名或任意查询结果 |
典型使用场景
- 多环境切换：一个变量区分生产与预发，看板结构完全一致
- 实例下钻：从服务维度切到实例维度查看具体节点
- 多任务共用：同一套面板服务多个采集任务
- 指标选择：在指标众多时让使用者自己挑要看哪个
- 对比分析：多选两个实例观察行为差异
- 报告生成：切换变量后导出快照，内容随之变化
变量查询写法
变量查询写法
label_values(node_uname_info, instance) # 取实例列表
label_values(kube_pod_info{namespace="prod"}, pod) # 带筛选条件缩小范围
metrics(node_filesystem_.*) # 按名称模式匹配指标
query_result(topk(3, sum by (job) (up))) # 任意查询后按正则提取变量取值来源
| 写法 | 取值来源 | 适用场景 |
|---|---|---|
| label_values | 指标上某个标签的全部取值 | 实例、任务、环境选择 |
| metrics | 匹配出的指标名 | 指标数量较多时的筛选 |
| query_result | 任意查询结果中按正则提取 | 需要排序或取前几名 |
| 自定义列表 | 手写的固定取值 | 取值稳定且很少变化 |
| 文本框 | 人工输入 | 临时性的自由过滤 |
常见配置项
| 配置 | 作用 | 注意 |
|---|---|---|
| 变量名称 | 面板引用的标识 | 改名会让所有引用失效 |
| 多选与全选 | 允许一次选择多个取值 | 取值数量决定查询规模 |
| 取值排序 | 控制下拉顺序 | 数值类按数值排序更直观 |
| 显示与隐藏 | 控制是否显示在下拉条 | 固定取值可隐藏以节省空间 |
在查询中使用变量
在查询中使用变量
# 单值引用
sum by (instance) (rate(node_cpu_seconds_total{mode="idle",job="$job"}[5m]))
# 多值引用：展开为匹配表达式
sum(rate(http_requests_total{instance=~"$instance"}[5m]))
# 用于面板标题与图例，便于截图留证
# 标题写成：$job 的请求速率使用约定
- 变量名用业务含义命名，避免临时拼凑的名字
- 默认值选有代表性的取值，打开看板即可看到内容
- 高基数字段不要直接做成变量，先聚合或加筛选收敛
- 变量改动后回归检查依赖它的面板是否仍正常
变量查询本身也是一次查询：取值来源尽量带上指标名或筛选条件缩小范围，否则看板加载会明显变慢。
变量改名或删除会让引用它的面板查询直接报错：重构时先在副本上验证，再替换正式看板。
变量数量也要克制：三到四个联动变量已经能覆盖多数场景，继续增加会让使用者记不住每个变量的作用范围。