变量与筛选
仪表盘变量在盘顶生成下拉框，选项由标签值驱动、可互相联动；选一台机器或一个集群，整屏图表跟着切换。
这页办完你会得到：一块盘顶上多出几个下拉框，选一台机器、一个集群，整屏的图跟着切； 一块盘服务几十台机器，而不是复制几十块盘。
1. 加第一个变量
打开一个仪表盘，变量条就在标题栏下面。一个变量都没有时那里是一个 添加变量 链接； 已经有变量了，入口是变量条最右边的铅笔图标。
新建一个「查询 (Query)」类型的变量：
| 字段 | 填什么 |
|---|---|
| 变量名称 | 只允许字母、数字、下划线。面板里用 $名字 或 ${名字} 引用 |
| 显示名称 | 下拉框上显示的文字，留空就显示变量名 |
| 变量类型 | 见下一节 |
| 隐藏变量 | 隐藏之后下拉框不显示，但值照常参与替换 |
| 数据源 | 去哪儿取候选值 |
| 变量定义 | 取值表达式，见下面那段 |
| 正则 | 可选，用正则字面量（/…/）过滤候选项；带命名捕获组时可以让显示文本和实际值不一样 |
| 多选 / 包含全选 / 自定义全选值 | 下拉框的行为 |
| 宽度 | 下拉框宽度，留空是 180px |
Prometheus 数据源上，「变量定义」认这几种写法：
label_names() 所有标签名
label_values(ident) 某个标签的全部取值
label_values(up{job="api"}, instance) 先按表达式筛序列，再取其中一个标签的值
metrics(cpu_.*) 按正则筛指标名
query_result(up == 0) 直接用一条 PromQL 的即时查询结果
不带函数名的字符串按 PromQL 即时查询处理，等价于 query_result(...)。
表单下方有实时预览。预览里看不到候选值就先别保存——存下去也是一个空下拉框。
预期结果：保存后变量条上多出一个下拉框，选一个值，面板跟着刷新。
2. 变量类型
| 类型 | 候选值从哪儿来 | 典型用法 |
|---|---|---|
| 查询 (Query) | 向数据源查 | 机器、实例、集群、服务名 |
| 自定义 (Custom) | 你自己写的、逗号分隔的固定列表 | prod,staging,dev |
| 文本框 (Text box) | 看盘的人手输 | 一个 trace id、一个关键字 |
| 常量 (Constant) | 一个写死的值 | 抽出重复出现的前缀，通常配「隐藏变量」 |
| 数据源 (Datasource) | 某一类数据源的全部实例 | 同一块盘在多个机房的 Prometheus 之间切 |
| 数据源标识 (Datasource identifier) | 同上，取的是标识而不是内部 id | |
| 机器标识 (Host ident) | 当前用户有权限的机器 | 需要按权限过滤机器列表时 |
最后一个有个副作用要记住：用了「机器标识」的仪表盘不能匿名分享，因为它依赖登录态 接口。界面上会直接禁掉分享链接的生成，见匿名限时分享。
3. 让下拉框互相联动
在一个变量的定义里引用另一个变量，就成了级联：
cluster label_values(up, cluster)
instance label_values(up{cluster="$cluster"}, instance)
选中某个 cluster 之后，instance 的候选值自动收窄到这个集群里的实例。
注意顺序：被引用的变量必须排在前面，变量列表里可以拖动调整。
4. 在面板里用变量
面板的查询语句、面板标题、文本卡片里都能写 ${变量名}：
cpu_usage_idle{ident="$ident"}
多选变量替换出来的是 a|b|c 这种形式，所以必须换成正则匹配：
cpu_usage_idle{ident=~"$ident"}
除了自己定义的，还有一批内置变量可以直接引用：
| 内置变量 | 是什么 |
|---|---|
${__field.name} / ${__field.value} | 图例的名称 / 数值 |
${__field.labels.X} / ${__field.labels.__name__} | 某个标签的值 / 指标名 |
${__interval} / ${__interval_ms} | 时间间隔，默认就是 step |
${__range} / ${__range_ms} | 当前时间范围的长度 |
${__rate_interval} | __interval * 4 |
${__from} / ${__to} | 起止时间（毫秒），另有 __from_date_seconds、__from_date_iso |
面板配置里还有个「重复」：选一个多选变量，每个取值渲染一块一样的图，还能设每行最多几块。 八台机器八块一模一样的 CPU 图，就靠这个，不用手工复制。
时间范围是怎么参与的
两件容易混的事：
- 变量的候选值是在当前时间范围里取的。
label_values(...)查的是这段时间里出现过的 序列。所以把范围从「最近 1 小时」拉到「最近 7 天」，下拉框里可能多出几台已经下线的 机器；反过来，机器刚上线不到一小时看不到它，也是正常的。排查「下拉框里没有我要的 机器」时先看这一条。 - 时间范围本身不是变量。 它存在 URL 的
__from/__to里，并按仪表盘记在浏览器 中，下次打开还是它。要在查询里引用它，用上面那组${__from}/${__range}。
几个容易踩的地方
- 变量名只能用字母、数字、下划线，这和
$name的解析规则是配套的； - 多选变量必须配
=~，写成=只会去匹配字面量a|b|c，结果永远是空； - 「包含全选」在没设「自定义全选值」时，全选展开成当前所有候选项拼起来（
a|b|c）， 所以同样只在=~下有意义；想让它变成.*就填进「自定义全选值」； - 这一页说的是仪表盘变量。系统配置 → 变量设置（
/system/variable-settings）是另一 回事，那是给通知模板和规则用的全局变量，见全局变量与密文。