# 变量与筛选

仪表盘变量在盘顶生成下拉框，选项由标签值驱动、可互相联动；选一台机器或一个集群，整屏图表跟着切换。

最后校对于 2026-10-10

这页办完你会得到：一块盘顶上多出几个下拉框，选一台机器、一个集群，整屏的图跟着切； 一块盘服务几十台机器，而不是复制几十块盘。

## 1. 加第一个变量[​](#1-加第一个变量 "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. 变量类型[​](#2-变量类型 "2. 变量类型的直接链接")

| 类型                               | 候选值从哪儿来                 | 典型用法                               |
| ---------------------------------- | ------------------------------ | -------------------------------------- |
| 查询 (Query)                       | 向数据源查                     | 机器、实例、集群、服务名               |
| 自定义 (Custom)                    | 你自己写的、逗号分隔的固定列表 | `prod,staging,dev`                     |
| 文本框 (Text box)                  | 看盘的人手输                   | 一个 trace id、一个关键字              |
| 常量 (Constant)                    | 一个写死的值                   | 抽出重复出现的前缀，通常配「隐藏变量」 |
| 数据源 (Datasource)                | 某一类数据源的全部实例         | 同一块盘在多个机房的 Prometheus 之间切 |
| 数据源标识 (Datasource identifier) | 同上，取的是标识而不是内部 id  |                                        |
| 机器标识 (Host ident)              | 当前用户有权限的机器           | 需要按权限过滤机器列表时               |

最后一个有个副作用要记住：**用了「机器标识」的仪表盘不能匿名分享**，因为它依赖登录态 接口。界面上会直接禁掉分享链接的生成，见[匿名限时分享](https://n9e.github.io/zh/docs/query/sharing.md)。

## 3. 让下拉框互相联动[​](#3-让下拉框互相联动 "3. 让下拉框互相联动的直接链接")

在一个变量的定义里引用另一个变量，就成了级联：

```
cluster     label_values(up, cluster)

instance    label_values(up{cluster="$cluster"}, instance)
```

选中某个 cluster 之后，instance 的候选值自动收窄到这个集群里的实例。

注意顺序：**被引用的变量必须排在前面**，变量列表里可以拖动调整。

## 4. 在面板里用变量[​](#4-在面板里用变量 "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 图，就靠这个，不用手工复制。

## 时间范围是怎么参与的[​](#时间范围是怎么参与的 "时间范围是怎么参与的的直接链接")

两件容易混的事：

1. **变量的候选值是在当前时间范围里取的。** `label_values(...)` 查的是这段时间里出现过的 序列。所以把范围从「最近 1 小时」拉到「最近 7 天」，下拉框里可能多出几台已经下线的 机器；反过来，机器刚上线不到一小时看不到它，也是正常的。排查「下拉框里没有我要的 机器」时先看这一条。
2. **时间范围本身不是变量。** 它存在 URL 的 `__from` / `__to` 里，并按仪表盘记在浏览器 中，下次打开还是它。要在查询里引用它，用上面那组 `${__from}` / `${__range}`。

## 几个容易踩的地方[​](#几个容易踩的地方 "几个容易踩的地方的直接链接")

* 变量名只能用字母、数字、下划线，这和 `$name` 的解析规则是配套的；
* **多选变量必须配 `=~`**，写成 `=` 只会去匹配字面量 `a|b|c`，结果永远是空；
* 「包含全选」在没设「自定义全选值」时，全选展开成**当前所有候选项拼起来**（`a|b|c`）， 所以同样只在 `=~` 下有意义；想让它变成 `.*` 就填进「自定义全选值」；
* 这一页说的是**仪表盘变量**。系统配置 → 变量设置（`/system/variable-settings`）是另一 回事，那是给通知模板和规则用的全局变量，见[全局变量与密文](https://n9e.github.io/zh/docs/security/variables.md)。

## 下一步[​](#下一步 "下一步的直接链接")

* 把变量用到面板上：[创建仪表盘](https://n9e.github.io/zh/docs/query/dashboards.md)
* 带变量的盘怎么分享：[匿名限时分享](https://n9e.github.io/zh/docs/query/sharing.md)
* 标签是从哪儿来的：[标签与注解](https://n9e.github.io/zh/docs/concepts/labels-annotations.md)