本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 添加和管理变量 **** 本文档主题专为支持 **Grafana 10.x 版本**的 Grafana 工作区而设计。 对于支持 Grafana 9.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 9](using-grafana-v9.md)。 对于支持 Grafana 8.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 8](using-grafana-v8.md)。 下表列出了 Grafana 中的变量类型。 | 变量类型 | 说明 | | --- | --- | | Query | 查询生成的值列表，例如指标名称、服务器名称、传感器 IDs、数据中心等。 | | 自定义 | 使用逗号分隔的列表手动定义变量选项。 | | Text box（文本框） | 显示带有可选默认值的自由文本输入字段。 | | 常量 | 定义隐藏的常量。 | | 数据来源 | 快速更改整个控制面板的数据来源。 | | Interval | 间隔变量表示时间跨度。 | | 临时筛选条件 | 自动添加到数据来源（仅限 Prometheus、Loki、InfluxDB 和 Elasticsearch）的所有指标查询中的键值筛选条件。 | | 全局变量 | 可在查询编辑器的表达式中使用的内置变量。 | | 链式变量 | 变量查询可以包含其他变量。 | **Topics** + [输入常规选项](#v10-dash-variable-options) + [添加查询变量](#v10-dash-variable-add-query) + [添加自定义变量](#v10-dash-variable-add-custom) + [添加文本框变量](#v10-dash-variable-add-text) + [添加常量变量](#v10-dash-variable-add-constant) + [添加数据来源变量](#v10-dash-variable-add-datasource) + [添加间隔变量](#v10-dash-variable-add-internal) + [添加临时筛选条件](#v10-dash-variable-add-adhoc) + [配置变量选择选项](#v10-dash-variable-add-selection) + [全局变量](#v10-dash-variable-add-global) + [链式变量](#v10-dash-variable-add-chained) + [管理变量](#v10-dash-variable-add-manage) + [使用正则表达式筛选变量](#v10-dash-variable-add-filter) ## 输入常规选项 您必须为创建的任何类型的变量输入常规选项。 **输入常规选项** 1. 导航到要为其设置变量的控制面板，然后选择页面顶部的**控制面板设置**（齿轮）图标。 1. 在**变量**选项卡上，选择**新建变量**。 1. 输入变量的**名称**。 1. 在**类型**列表中，选择**查询**。 1. （可选）在**标签**中，输入变量下拉列表的显示名称。 如果未输入显示名称，则下拉标签就是变量名称。 1. 选择**隐藏**选项： + **无选择（空白）**：变量下拉列表显示变量**名称**或**标签**值。 + **标签**：变量下拉列表仅显示选定变量值和向下箭头。 + **变量**：控制面板上不显示变量下拉列表。 ## 添加查询变量 通过查询变量，您可以编写数据来源查询，该查询可返回指标名称、标签值或键的列表。例如，查询变量可能返回服务器名称 IDs、传感器或数据中心的列表。变量值在使用数据来源查询动态获取选项时会发生变化。 查询变量通常仅支持字符串。如果您的查询返回数字或任何其他数据类型，则可能需要将其转换为字符串，才能将其用作变量。例如，对于 Azure 数据来源，您可以使用 [tostring](https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/tostringfunction) 函数来实现此目的。 查询表达式可以包含对其他变量的引用，实际上就是创建链接变量。Grafana 会检测到这一点，并在其中一个链接变量发生变化时自动刷新变量。 **注意** 每个数据来源的查询表达式都不同。有关更多信息，请参阅[数据来源](AMG-data-sources.md)的文档。 **添加查询变量** 1. 如上所示，输入常规选项。 1. 在**数据来源**列表中，选择查询的目标数据来源。 1. 在**刷新**列表中，选择变量应何时更新选项。 + **控制面板加载时**：每次加载控制面板时查询数据来源。这会减慢控制面板的加载速度，因为需要在初始化控制面板之前完成变量查询。 + **时间范围更改时**：当控制面板时间范围发生变化时查询数据来源。仅当变量选项查询包含时间范围筛选条件或依赖于控制面板时间范围时，才使用此选项。 1. 在**查询**字段中，输入查询。 + 查询字段因数据来源而异。某些数据来源具有自定义查询编辑器。 + 查询必须返回名为 `__text` 和 `__value` 的值。例如，在 SQL 中，您可以使用 `SELECT hostname AS __text, id AS __value from MyTable` 之类的查询。其他语言的查询会因语法而异。 + 如果单个输入字段查询编辑器中需要更多空间，请将光标悬停在字段右下角的行上，然后向下拖动以展开。 1. （可选）在**正则表达式**字段中，键入正则表达式以筛选或捕获数据来源查询返回的名称的特定部分。要查看示例，请参阅[使用正则表达式筛选变量](#v10-dash-variable-add-filter)。 1. 在**排序**列表中，选择要在下拉列表中显示的值的排序顺序。默认选项**禁用**表示使用数据来源查询返回的选项顺序。 1. （可选）输入[选择选项](#v10-dash-variable-add-selection)。 1. 在**值预览**中，Grafana 显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加自定义变量 对不变的值（如数字或字符串）使用*自定义*变量。 例如，如果您的服务器名称或区域名称从未更改，则可能需要将其创建为自定义变量，而不是查询变量。因为其不会更改，所以可以在[链式变量](#v10-dash-variable-add-chained)中，而不是其他查询变量中使用。这将减少链式变量更新时 Grafana 必须发送的查询次数。 **添加自定义变量** 1. 如上所示，输入常规选项。 1. **以逗号分隔的值**列表，在逗号分隔的列表中输入此变量的值。可以包含由空格和冒号分隔的数字、字符串或键值对。例如 `key1 : value1,key2 : value2`。 1. （可选）输入[选择选项](#v10-dash-variable-add-selection)。 1. 在**值预览**中，Grafana 显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加文本框变量 *文本框*变量显示带有可选默认值的自由文本输入字段。这是最灵活的变量，因为您可以输入任何值。如果您的指标具有高基数，或者您希望同时更新控制面板中的多个面板，请使用此类型的变量。 **添加文本框变量** 1. 如上所示，输入常规选项。 1. （可选）在**默认值**字段中，选择变量的默认值。如果未在此字段中输入任何内容，Grafana 会显示一个空文本框，供用户键入文本。 1. 在**值预览**中，Grafana 显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加常量变量 *常量变量*允许定义隐藏的常量。这对于要共享的控制面板的指标路径前缀很有用。导出控制面板时，常量变量会转换为导入选项。 常量变量*不*灵活。每个常量变量仅包含一个值，除非更新变量设置，否则无法更新。 如果需要在查询中包含复杂的值，但又不想在每次查询中都重新输入，常量变量就非常有用。例如，如果有一个名为 `i-0b6a61efe2ab843gg` 的服务器路径，则可以将其替换为一个名为 `$path_gg` 的变量。 **添加常量变量** 1. 如上所示，输入常规选项。 1. 在**值**字段中，输入变量值。您可以输入字母、数字和符号。如果您使用[原始格式](v10-dash-variable-syntax.md#v10-dash-variable-syntax-raw)，甚至可以使用通配符。 1. 在**值预览**中，Grafana 显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加数据来源变量 *数据来源*变量让您可以快速更改整个控制面板的数据来源。如果您有多个数据来源实例（可能位于不同的环境中），则会很有用。 **添加数据来源变量** 1. 如上所示，输入常规选项。 1. 在**类型**列表中，选择变量的目标数据来源。 您还可以选择**打开高级数据来源选取器**以查看更多选项，包括添加数据来源（仅限管理员）。有关更多信息，请参阅 [连接到数据来源](AMG-data-sources.md)。 1. （可选）在**实例名称筛选条件**中，在变量值下拉列表中输入要从中选择的数据来源实例的正则表达式筛选条件。将此字段留空可显示所有实例。 1. （可选）输入[选择选项](#v10-dash-variable-add-selection)。 1. 在**值预览**中，Grafana 显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加间隔变量 使用*间隔*变量来表示时间跨度，例如 `1m`、`1h` 或 `1d`。您可以将其视为控制面板范围内的*按时间分组*命令。间隔变量会更改数据在可视化中的分组方式。您也可以使用“自动选项”在每个时间跨度返回一定数量的数据点。 您可以使用间隔变量作为按时间分组参数（对于 InfluxDB）、日期直方图间隔（对于 Elasticsearch）或作为 summarize 函数参数（对于 Graphite）。 **添加间隔变量** 1. 如上所示，输入常规选项。 1. 在**值**字段中，输入您希望在变量下拉列表中显示的时间范围间隔。支持以下时间单位：`s (seconds)`、`m (minutes)`、`h (hours)`、`d (days)`、`w (weeks)`、`M (months)` 和 `y (years)`。您也可以接受或编辑默认值：`1m,10m,30m,1h,6h,12h,1d,7d,14d,30d`. 1. （可选）如果要将 `auto` 选项添加到列表中，请打开**自动选项**。此选项允许您指定应将当前时间范围划分多少次，来计算当前 `auto` 时间跨度。如果将其打开，则会出现另外两个选项： + **步数**：选择当前时间范围的划分次数以计算该值，类似于**最大数据点**查询选项。例如，如果当前可见的时间范围为 30 分钟，则 `auto` 间隔将数据分组为 30 个一分钟增量。默认值为 30 步。 + **最小间隔**：最小阈值，低于该阈值的步数间隔不会划分时间。继续以 30 分钟为例，如果最小间隔设置为 2m，则 Grafana 会将数据分组为 15 个两分钟增量。 1. 在**值预览**中，Grafana 显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 **间隔变量示例** 以下示例显示了 Graphite 函数中的模板变量 `myinterval`： ``` summarize($myinterval, sum, false) ``` ## 添加临时筛选条件 *临时筛选条件*允许您添加键值筛选条件，这些筛选条件会自动添加到使用指定数据来源的所有指标查询中。与其他变量不同的是，不在查询中使用临时筛选条件。而是使用临时筛选条件为现有查询编写筛选条件。 **注意** 临时筛选条件变量仅适用于 Prometheus、Loki、InfluxDB 和 Elasticsearch 数据来源。 1. 如上所示，输入常规选项。 1. 在**数据来源**列表中，选择目标数据来源。 您还可以选择**打开高级数据来源选取器**以查看更多选项，包括添加数据来源（仅限管理员）。有关更多信息，请参阅 [连接到数据来源](AMG-data-sources.md)。 1. 选择**添加**将变量添加到控制面板。 **创建临时筛选条件** 临时筛选条件是可用的最复杂、最灵活的变量选项之一。此变量让您可以构建控制面板范围的临时查询，而不是常规的变量选项列表。以这种方式应用的筛选条件将应用于控制面板上的所有面板。 ## 配置变量选择选项 *选择选项*是一项用于管理变量选项选择的功能。所有选择选项都是可选的，默认处于关闭状态。 ### 多值变量 对选择了多个值的变量进行插值会比较麻烦，因为如何将多个值格式化为字符串，而且该字符串在使用该变量的给定上下文中有效，这不是个简单明了的过程。Grafana 试图通过允许每个数据来源插件通知模板插值引擎对多个值使用的格式来解决这个问题。 **注意** 变量上的**自定义所有值**选项必须为空，Grafana 才能将所有值格式化为单个字符串。如果将其留空，则 Grafana 会将查询中的所有值连接（相加）。例如 `value1,value2,value3`。如果使用自定义的 `all` 值，该值将变为 `*` 或 `all`。 **具有 Graphite 数据来源的多值变量** Graphite 使用 glob 表达式。在这种情况下，如果当前变量值为 *host1*、*host2* 和 *host3*，则具有多个值的变量将插值为 `{host1,host2,host3}`。 **具有 Prometheus 或 InfluxDB 数据来源的多值变量** InfluxDB 和 Prometheus 使用正则表达式，因此相同的变量将插值为 `(host1|host2|host3)`。每个值也将进行正则表达式转义。否则，带有正则表达式控制字符的值将中断正则表达式。 **具有 Elastic 数据来源的多值变量** Elasticsearch 使用 lucene 查询语法，因此相同的变量将格式化为 `("host1" OR "host2" OR "host3")`。在这种情况下，要对每个值进行转义，使该值仅包含 lucene 控制词和引号。 **多值变量问题排查** 自动转义和格式化可能会导致问题，其背后的逻辑也很难理解。特别是对于 InfluxDB 和 Prometheus 来说，使用正则表达式语法需要在正则表达式运算符上下文中使用变量。 如果您不希望 Grafana 自动执行正则表达式转义和格式化，则必须执行下列操作之一： + 关闭**多值**或**包含全部选项**选项。 + 采用[原始格式](v10-dash-variable-syntax.md#v10-dash-variable-syntax-raw)。 ### 包含全部选项 Grafana 在变量下拉列表中添加了 `All` 选项。如果用户选择此选项，则会选择所有变量选项。 ### 自定义所有值 仅当选择**包含全部选项**时，此选项才可见。 在**自定义所有值**字段中输入 regex、glob 或 lucene 语法来定义 `All` 选项的值。 默认情况下，`All` 值包含组合表达式中的所有选项。该值可能会变得很长，并且可能会出现性能问题。有时，最好指定自定义 all 值，例如通配符正则表达式。 要在**自定义所有值**选项中使用自定义 regex、glob 或 lucene 语法，使其永远不会转义，因此您必须考虑数据来源的有效值。 ## 全局变量 Grafana 具有全局内置变量，可在查询编辑器的表达式中使用。本主题按字母顺序列出了这些变量，并对其进行了定义。这些变量在查询、控制面板链接、面板链接和数据链接中非常有用。 **\$1\$1\$1dashboard** 此变量是当前控制面板的名称。 **\$1\$1\$1from 和 \$1\$1\$1to** Grafana 有两个内置的时间范围变量：`$__from` 和 `$__to`。默认情况下，当前始终插值为 epoch 毫秒，但您可以控制日期格式。 | 语法 | 示例结果 | 说明 | | --- | --- | --- | | `${__from}` | 1594671549254 | Unix 毫秒 epoch | | `${__from:date}` | 2020-07-13T20:19:09.254Z | 无参数，默认为 ISO 8601/RFC 3339 | | `${__from:date:iso}` | 2020-07-13T20:19:09.254Z | ISO 8601/RFC 3339 | | `${__from:date:seconds}` | 1594671549 | Unix 秒 epoch | | `${__from:date:YYYY-MM}` | 2020-07 | 任何不包含 : 字符的自定义日期格式 | 上面的语法也适用于 `${__to}`。 **\$1\$1\$1interval** 您可以使用 `$__interval` 变量作为按时间分组参数（对于 InfluxDB、MySQL、Postgres、MSSQL）、日期直方图间隔（对于 Elasticsearch）或作为 *summarize* 函数参数（对于 Graphite）。 Grafana 会自动计算一个间隔，该间隔可用于在查询中按时间分组。当数据点多于图形上显示的数据点时，可通过按更大的间隔分组来提高查询的效率。例如，如果您正在查看包含 3 个月数据的图形，则可能无法看到分钟级别的详细信息。按小时或天分组可以提高查询效率，而不会影响图形显示的内容。`$__interval` 是使用时间范围和图形宽度（像素数）计算得出的。 近似计算：`(to - from) / resolution` 例如，当时间范围为 1 小时且图形为全屏时，则可以将间隔计算为 `2m`，点按 2 分钟间隔分组。如果时间范围为 6 个月且图形为全屏时，则间隔可能是 `1d`（1 天），点按天分组。 在 InfluxDB 数据来源中，传统变量 `$interval` 是同一个变量。应改为使用 `$__interval`。 InfluxDB 和 Elasticsearch 数据源具有 `Group by time interval` 字段，用于对间隔进行硬编码或设置 `$__interval` 变量的最小限制（使用 `>` 语法，例如 `>10m`）。 **\$1\$1\$1interval\$1ms** 此变量是以毫秒为单位的 `$__interval` 变量，而不是时间间隔格式的字符串。例如，如果 `$__interval` 为 `20m`，则 `$__interval_ms` 为 `1200000`。 **\$1\$1\$1org** 此变量是当前组织的 ID。`${__org.name}` 是当前组织的名称。 **\$1\$1\$1user** `${__user.id}` 是当前用户的 ID。`${__user.login}` 是当前用户的登录句柄。`${__user.email}` 是当前用户的电子邮件。 **\$1\$1\$1range** 仅支持 Prometheus 和 Loki 数据来源。此变量表示当前控制面板的范围。由 `to - from` 计算得出。此变量有毫秒和秒两种表示形式，分别称为 `$__range_ms` 和 `$__range_s`。 **\$1\$1\$1rate\$1interval** 仅支持 Prometheus 数据来源。`$__rate_interval` 变量旨在用于 rate 函数。 **\$1timeFilter 或 \$1\$1\$1timeFilter** `$timeFilter` 变量以表达式形式返回当前选定的时间范围。例如，时间范围间隔 `Last 7 days` 表达式为 `time > now() - 7d`。 可在多个地方使用，包括： + InfluxDB 数据来源的 WHERE 子句。在查询编辑器模式下，Grafana 会自动将其添加到 InfluxDB 查询。您可以在文本编辑器模式下手动添加：`WHERE $timeFilter`。 + 在 Azure Monitor 数据来源中记录分析查询。 + MySQL、Postgres 和 MSSQL 中的 SQL 查询。 + `$__timeFilter` 变量用于 MySQL 数据来源。 **\$1\$1\$1timezone** `$__timezone` 变量返回当前选定的时区，可以是 `utc`，也可以是 IANA 时区数据库的一个条目（例如 `America/New_York`）。 如果当前选定的时区是*浏览器时间*，Grafana 将尝试确定您的浏览器时区。 ## 链式变量 *链式变量*，也称为*链接变量*或*嵌套变量*，是变量查询中包含一个或多个其他变量的查询变量。 每个数据来源的链式变量查询都不同，但前提都是一样的。您可以在任何允许的数据来源中使用链式变量查询。 可以使用极为复杂的链接模板控制面板，深度为 5 或 10 级。从技术上讲，深度和复杂程度没有限制，但链接越多，查询负荷就越大。 **最佳实践和提示** 以下做法可使您的控制面板和变量更易于使用。 **创建新的链接变量** + 链接变量会产生 parent/child 依赖关系。您可以将其想象成梯子或树。 + 创建新的链式变量的最简单方法是复制要作为新变量基础的变量。在变量列表中，单击变量条目右侧的**复制变量**图标以创建副本。然后，您就可以为父变量添加查询。 + 通过这种方式创建的新变量显示在列表的底部。您可能需要将其拖动到列表中的其他位置，以使其按逻辑顺序排列。 **变量顺序** 您可以通过单击每个条目右侧的向上和向下箭头，来更改控制面板变量列表中变量的顺序。Grafana 根据此列表从左到右列出变量下拉列表，变量位于最左侧的顶部。 + 在顶部列出没有依赖关系的变量，放在其子变量之前。 + 每个变量都应遵循其依赖的变量。 + 请记住，UI 中没有指示哪些变量具有依赖关系。按逻辑顺序列出变量，以方便其他用户（和您自己）使用。 **复杂性考虑** 变量中的依赖关系层越多，更改变量后更新控制面板所需的时间就越长。 例如，如果您有一系列四个链接变量（国家、地区、服务器、指标），并更改了根变量值（国家），Grafana 必须先对所有因变量运行查询，然后才能更新控制面板中的可视化。 ## 管理变量 您可以在变量页面上添加变量和管理现有变量。还可以[检查](v10-dash-variable-add-inspect.md)变量，并确定变量是否在其他变量或控制面板中被引用（或使用）。 **移动**：您可以使用拖放操作在列表中上下移动变量。 **克隆**：要克隆变量，请单击右侧图标集中的克隆图标。这将创建一个变量的副本，其原始变量的名称前缀为 `copy_of_`。 **删除**：要删除变量，请单击右侧图标集中的垃圾桶图标。 ## 使用正则表达式筛选变量 通过 Regex Query 选项，您可以筛选变量查询返回的选项列表或修改返回的选项。 本页展示了如何使用正则表达式来处理变量下 filter/modify 拉列表中的值。 通过 Regex Query 选项，您可以筛选变量查询返回的选项列表或修改返回的选项。有关更多信息，请参阅 Mozilla [正则表达式](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)指南。 以下示例显示了对以下选项列表的筛选 ``` backend_01 backend_02 backend_03 backend_04 ``` **筛选以仅返回以 `01` 或 `02` 结尾的选项** 正则表达式： ``` / ( 01|02 ) $/ ``` 结果： ``` backend_01 backend_02 ``` **使用正则表达式捕获组筛选和修改选项以返回部分文本** 正则表达式： ``` /.* ( 01|02 ) / ``` 结果： ``` 01 02 ``` **筛选和修改：Prometheus 示例** 此选项的列表： ``` up{instance="demo.robustperception.io:9090",job="prometheus"} 1 1521630638000 up{instance="demo.robustperception.io:9093",job="alertmanager"} 1 1521630638000 up{instance="demo.robustperception.io:9100",job="node"} 1 1521630638000 ``` 此正则表达式： ``` /. *instance=" ( [^"]* ) .*/ ``` 返回以下结果： ``` demo.robustperception.io:9090 demo.robustperception.io:9093 demo.robustperception.io:9100 ``` **使用命名文本和值捕获组进行筛选和修改** 使用命名捕获组，您可以从变量查询返回的选项中捕获单独的“文本”和“值”部分。这样，变量下拉列表中的每个可选值都会包含友好的名称。 例如，在查询 `node_hwmon_chip_names` Prometheus 指标时，`chip_name` 比 `chip` 值更友好。因此，以下变量查询结果： ``` node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_1",chip_name="enp216s0f0np1"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_2",chip_name="enp216s0f0np2"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_3",chip_name="enp216s0f0np3"} 1 ``` 通过以下正则表达式传递： ``` /chip_name="(?[ ^ " ] + ) |chip=" (?[ ^ " ] + )/g ``` 将生成以下下拉列表： ``` Display Name Value ------------ ------------------------- enp216s0f0np0 0000:d7:00_0_0000:d8:00_0 enp216s0f0np1 0000:d7:00_0_0000:d8:00_1 enp216s0f0np2 0000:d7:00_0_0000:d8:00_2 enp216s0f0np3 0000:d7:00_0_0000:d8:00_3 ``` 仅支持 `text` 和 `value` 捕获组名称。