本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 变量类型 **** 本文档主题专为支持 **Grafana 8.x 版本**的 Grafana 工作区而设计。 对于支持 Grafana 10.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 10](using-grafana-v10.md)。 对于支持 Grafana 9.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 9](using-grafana-v9.md)。 Grafana 使用几种类型的变量。 | 变量类型 | 说明 | | --- | --- | | Query | 查询生成的值列表，例如指标名称、服务器名称、传感器 IDs、数据中心等。有关更多信息，请参阅 [添加查询变量](#add-a-query-variable)。 | | 自定义 | 使用逗号分隔的列表手动定义变量选项。有关更多信息，请参阅 [添加自定义变量](#add-a-custom-variable)。 | | Text box（文本框） | 显示带有可选默认值的文本输入字段。有关更多信息，请参阅 [添加文本框变量](#add-a-text-box-variable)。 | | 常量 | 定义隐藏的常量。有关更多信息，请参阅 [添加常量变量](#add-a-constant-variable)。 | | 数据来源 | 快速更改整个控制面板的数据来源。有关更多信息，请参阅 [添加数据来源变量](#add-a-data-source-variable)。 | | Interval | 间隔变量表示时间跨度。有关更多信息，请参阅 [添加间隔变量](#add-an-interval-variable)。 | | 临时筛选条件 | Key/value 过滤器会自动添加到数据源的所有指标查询中（InfluxDB、Prometheus，仅限）。 OpenSearch 有关更多信息，请参阅 [添加临时筛选条件](#add-ad-hoc-filters)。 | | 全局变量 | 可在查询编辑器的表达式中使用的内置变量。有关更多信息，请参阅 [全局变量](#global-variables)。 | | 链式变量 | 变量查询可以包含其他变量。有关更多信息，请参阅 [链式变量](#chained-variables)。 | ## 添加查询变量 通过查询变量，您可以编写数据来源查询，该查询可返回指标名称、标签值或键的列表。例如，查询变量可能返回服务器名称 IDs、传感器或数据中心的列表。变量值在使用数据来源查询动态获取选项时会发生变化。 查询表达式可以包含对其他变量的引用，实际上就是创建链接变量。Grafana 会检测到这一点，并在其中一个链接变量发生变化时自动刷新变量。 ### 查询表达式 每个数据来源的查询表达式都不同。有关更多信息，请参阅 [连接到数据来源](AMG-data-sources.md) 中的数据来源文档。 ### 输入常规选项 **输入查询变量的常规选项** 1. 导航到要为其设置变量的控制面板，然后选择页面顶部的**控制面板设置**（齿轮）图标。 1. 在**变量**选项卡上，选择**新建**。 1. 输入变量的**名称**。 1. 在**类型**列表中，选择**查询**。 1. （可选）在**标签**中，输入变量下拉列表的显示名称。如果未输入显示名称，则下拉标签就是变量名称。 1. 选择**隐藏**选项： + **无选择（空白）**：变量下拉列表显示变量**名称**或**标签**值。这是默认值。 + **标签**：变量下拉列表仅显示选定变量值和向下箭头。 + **变量**：控制面板上不显示变量下拉列表。 ### 输入查询选项 **输入查询变量的查询选项** 1. 在**数据来源**列表中，选择查询的目标数据来源。有关数据来源的详细信息，请参阅 [连接到数据来源](AMG-data-sources.md)。 1. 在**刷新**列表中，选择变量应何时更新选项。 + **从不**：缓存变量查询，且值不会更新。如果值从不改变，则没问题，但如果值是动态的并且变化很大，则会出现问题。 + **控制面板加载时**：每次加载控制面板时查询数据来源。这会减慢控制面板的加载速度，因为必需在初始化控制面板之前完成变量查询。 + **时间范围更改时**：当控制面板时间范围发生变化时查询数据来源。仅当变量选项查询包含时间范围筛选条件或依赖于控制面板时间范围时，才使用此选项。 1. 在**查询**字段中，输入查询。 + 查询字段因数据来源而异。某些数据来源具有自定义查询编辑器。 + 如果单个输入字段查询编辑器中需要更多空间，请将光标悬停在字段右下角的行上，然后向下拖动以展开。 1. （可选）在**正则表达式**字段中，键入正则表达式以筛选或捕获数据来源查询返回的名称的特定部分。有关示例，请参阅 [使用正则表达式过滤变量](templates-and-variables.md#filter-variables-with-regex)。 1. 在**排序**列表中，选择要在下拉列表中显示的值的排序顺序。默认选项**禁用**表示使用数据来源查询返回的选项顺序。 1. （可选）输入**选择选项**。有关更多信息，请参阅 [输入变量选择选项](templates-and-variables.md#enter-variable-selection-options)。 1. 在**值预览**中，Grafana 工作区显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加自定义变量 对于不变的值，请使用*自定义*变量。这可能是数字、字符串，甚至是其他变量。 例如，如果您的服务器名称或区域名称不会改变，则可能需要将其创建为自定义变量，而不是查询变量。因为其不会更改，所以可以在链式变量中，而不是其他查询变量中使用。这将减少链式变量更新时 Grafana 必须发送的查询次数。有关链式变量的更多信息，请参阅 [链式变量](#chained-variables)。 ### 输入常规选项 **输入自定义变量的查询选项** 1. 导航到要为其设置变量的控制面板，然后选择页面顶部的**控制面板设置**（齿轮）图标。 1. 在**变量**选项卡上，选择**新建**。 1. 输入变量的**名称**。 1. 在**类型**列表中，选择**自定义**。 1. （可选）在**标签**中，输入变量下拉列表的显示名称。如果未输入显示名称，则下拉标签就是变量名称。 1. 选择**隐藏**选项： + **无选择（空白）**：变量下拉列表显示变量**名称**或**标签**值。这是默认值。 + **标签**：变量下拉列表仅显示选定变量值和向下箭头。 + **变量**：控制面板上不显示变量下拉列表。 ### 输入自定义选项 **输入自定义变量的自定义选项** 1. **以逗号分隔的值**列表，在逗号分隔的列表中输入此变量的值。可以包含数字、字符串、其他变量或由冒号分隔的键值对。 1. （可选）输入**选择选项**。有关更多信息，请参阅 [输入变量选择选项](templates-and-variables.md#enter-variable-selection-options)。 1. 在**值预览**中，Grafana 工作区显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加文本框变量 *文本框*变量显示带有可选默认值的文本输入字段。这是最灵活的变量，因为您可以输入任何值。如果您的指标具有高基数，或者您希望同时更新控制面板中的多个面板，请使用此类型的变量。 ### 输入常规选项 **输入文本框变量的常规选项** 1. 导航到要为其设置变量的控制面板，然后选择页面顶部的**控制面板设置**（齿轮）图标。 1. 在**变量**选项卡上，选择**新建**。 1. 输入变量的**名称**。 1. 在**类型**列表中，选择**文本框**。 1. （可选）在**标签**中，输入变量下拉列表的显示名称。如果未输入显示名称，则下拉标签就是变量名称。 1. 选择**隐藏**选项： + **无选择（空白）**：变量下拉列表显示变量**名称**或**标签**值。这是默认值。 + **标签**：变量下拉列表仅显示选定变量值和向下箭头。 + **变量**：控制面板上不显示变量下拉列表。 ### 输入文本选项 **输入文本框变量的文本选项** 1. （可选）在**默认值**字段中，选择变量的默认值。如果未在此字段中输入任何内容，Grafana 会显示一个空文本框，供您键入文本。 1. 在**值预览**中，Grafana 显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加常量变量 要定义隐藏常量，请使用*常量*变量。常量变量对于要共享的控制面板的指标路径前缀很有用。导出控制面板时，常量变量会转换为导入选项。 常量变量不灵活。每个常量变量仅包含一个值。若要更新，则必须更新变量设置。 如果需要在查询中包含复杂的值，但又不想在每次查询中都重新输入，常量变量就非常有用。例如，如果有一个名为 `i-0b6a61efe2ab843gg` 的服务器路径，则可以将其替换为一个名为 `$path_gg` 的变量。 ### 输入常规选项 **输入常量变量的常规选项** 1. 导航到要为其设置变量的控制面板，然后选择页面顶部的**控制面板设置**（齿轮）图标。 1. 在**变量**选项卡上，选择**新建**。 1. 输入变量的**名称**。 1. 在**类型**列表中，选择**常量**。 1. （可选）在**标签**中，输入变量下拉列表的显示名称。如果未输入显示名称，则下拉标签就是变量名称。 1. 选择**隐藏**选项： + **变量**：控制面板上不显示变量下拉列表。这是默认值。 + **无选择（空白）**：变量下拉列表显示变量**名称**或**标签**值。 + **标签**：变量下拉列表仅显示选定变量值和向下箭头。 ### 输入常量选项 **输入常量变量的常量选项** 1. 在**值**字段中，输入变量值。您可以输入字母、数字和符号。如果使用高级变量格式选项，则甚至可以使用通配符。有关更多信息，请参阅 [高级变量格式选项](templates-and-variables.md#advanced-variable-format-options)。 1. 在**值预览**中，Grafana 工作区显示当前变量值。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加数据来源变量 快速更改整个控制面板的数据来源，可使用*数据来源*变量。如果您有多个数据来源实例（可能位于不同的环境中），则会很有用。 ### 输入常规选项 **输入数据来源变量的常规选项** 1. 导航到要为其设置变量的控制面板，然后选择页面顶部的**控制面板设置**（齿轮）图标。 1. 在**变量**选项卡上，选择**新建**。 1. 输入变量的**名称**。 1. 在**类型**列表中，选择**数据来源**。 1. （可选）在**标签**中，输入变量下拉列表的显示名称。如果未输入显示名称，则下拉标签就是变量名称。 1. 选择**隐藏**选项： + **无选择（空白）**：变量下拉列表显示变量**名称**或**标签**值。这是默认值。 + **标签**：变量下拉列表仅显示选定变量值和向下箭头。 + **变量**：控制面板上不显示变量下拉列表。 ### 输入数据来源选项 **输入数据来源变量的数据来源选项** 1. 在**类型**列表中，选择变量的目标数据来源。有关数据来源的详细信息，请参阅 [连接到数据来源](AMG-data-sources.md)。 1. （可选）对于**实例名称筛选条件**，在变量值下拉列表中输入要从中选择的数据来源实例的正则表达式筛选条件。将此字段留空可显示所有实例。 1. （可选）输入**选择选项**。有关更多信息，请参阅 [输入变量选择选项](templates-and-variables.md#enter-variable-selection-options)。 1. 在**值预览**中，Grafana 显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ## 添加间隔变量 使用*间隔*变量来表示时间跨度，例如 `1m`、`1h`、`1d`。你可以把它们看作是仪表板范围内的命令 group-by-time。间隔变量会更改数据在可视化中的分组方式。您也可以使用“自动选项”在每个时间跨度返回一定数量的数据点。 您可以使用间隔变量作为按时间分组的参数（对于 InfluxDB）、日期直方图间隔（对于 OpenSearch）或作为汇总函数参数（对于 Graphite）进行分组。 ### 输入常规选项 **输入间隔变量的常规选项** 1. 导航到要为其设置变量的控制面板，然后选择页面顶部的**控制面板设置**（齿轮）图标。 1. 在**变量**选项卡上，选择**新建**。 1. 输入变量的**名称**。 1. 在**类型**列表中，选择**间隔**。 1. （可选）在**标签**中，输入变量下拉列表的显示名称。如果未输入显示名称，则下拉标签就是变量名称。 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 个 2 分钟增量。 1. 在**值预览**中，Grafana 显示当前变量值的列表。查看以确保其符合您的预期。 1. 选择**添加**将变量添加到控制面板。 ### 间隔变量示例 在 Graphite 函数中使用模板变量 `myinterval` 的示例： ``` summarize($myinterval, sum, false) ``` 更复杂的 Graphite 示例： ``` groupByNode(summarize(movingAverage(apps.$app.$server.counters.requests.count, 5), '$interval', 'sum', false), 2, 'sum') ``` ## 添加临时筛选条件 您可以使用一次性或*临时*筛选条件来添加键/值筛选条件，这些筛选条件会自动添加到使用指定数据来源的所有指标查询中。与其他变量不同的是，不在查询中使用一次性筛选条件。而是用其为现有查询编写筛选条件。 **注意** **注意：**一次性或临时筛选变量仅适用于 InfluxDB、Prometheus 和数据源。 OpenSearch ### 输入常规选项 **输入临时筛选条件的常规选项** 1. 导航到要为其设置变量的控制面板，然后选择页面顶部的**控制面板设置**（齿轮）图标。 1. 在**变量**选项卡上，选择**新建**。 1. 输入变量的**名称**。 1. 在**类型**列表中，选择**临时筛选条件**。 1. （可选）在**标签**中，输入变量下拉列表的显示名称。如果未输入显示名称，则下拉标签就是变量名称。 1. 选择**隐藏**选项： + **无选择（空白）**：变量下拉列表显示变量**名称**或**标签**值。这是默认值。 + **标签**：变量下拉列表仅显示选定变量值和向下箭头。 + **变量**：控制面板上不显示变量下拉列表。 ### 输入选项 **输入临时筛选条件的选项** 1. 在**数据来源**列表中，选择目标数据来源。有关数据来源的详细信息，请参阅 [连接到数据来源](AMG-data-sources.md)。 1. 选择**添加**将变量添加到控制面板。 ### 创建临时筛选条件 临时筛选条件是可用的最复杂、最灵活的变量选项之一。此变量允许构建控制面板范围的临时查询，而不是常规的变量选项列表。以这种方式应用的筛选条件将应用于控制面板上的所有面板。 ## 链式变量 *链式变量*，也称为*链接变量*或*嵌套变量*，是变量查询中包含一个或多个其他变量的查询变量。本节说明了链式变量的工作原理，并提供了指向使用链式变量的示例控制面板的链接。 每个数据来源的链式变量查询都不同，但前提都是一样的。您可以在任何支持的数据来源中使用链式变量查询。 您可以构建复杂的链接、模板化控制面板，深度为 5 或 10 级。从技术上讲，深度和复杂程度没有限制，但链接越多，查询负荷就越大。 ### 最佳实践和提示 以下做法可使您的控制面板和变量更易于使用。 #### 创建新的链式变量 + 链式变量会创建父-子依赖关系。您可以将其想象成梯子或树。 + 创建新的链式变量最快的方法是复制要作为新变量基础的变量。在变量列表中，选择变量条目右侧的**复制变量**图标以创建副本。然后，您就可以为父变量添加查询。 + 通过这种方式创建的新的链式变量显示在列表的底部。要为列表指定逻辑顺序，请将变量拖动到列表中的其他位置。 #### 变量顺序 要更改控制面板变量列表中的变量顺序，请选择每个条目右侧的向上和向下箭头。Grafana 工作区根据此列表从左到右列出变量下拉列表，在最左侧的列表顶部显示变量。 + 在顶部列出没有依赖关系的变量，放在其子变量之前。 + 每个变量都应遵循其依赖的变量。 + UI 不会指示哪些变量具有依赖关系。按逻辑顺序列出变量，以方便最终用户（和您自己）了解。 #### 复杂性考虑 变量中的依赖关系层越多，更改变量后更新控制面板所需的时间就越长。 例如，如果您有一系列四个链接变量（国家、地区、服务器、指标），并更改了根变量值（国家），Grafana 工作区必须先对所有因变量运行查询，然后才能更新控制面板中的可视化。 ## 全局变量 Grafana 具有全局内置变量，可在查询编辑器的表达式中使用。本主题按字母顺序列出了这些变量，并对其进行了定义。这些变量在查询、控制面板链接、面板链接和数据链接中非常有用。 ### \$1\$1\$1dashboard 此变量是当前控制面板的名称。 ### \$1\$1\$1from 和 \$1\$1\$1to Grafana 有两个内置的时间范围变量：`$__from` 和 `$__to`。默认情况下，当前始终插值为 epoch 毫秒，但您可以控制日期格式。 | 语法 | 示例结果 | 说明 | | --- | --- | --- | | \$1\$1\$1\$1from\$1 | 1594671549254 | Unix 毫秒 epoch | | \$1\$1\$1\$1from:date\$1 | 2020-07-13T20:19:09.254Z | 无参数，默认为 ISO 8601/RFC 3339 | | \$1\$1\$1\$1from:date:iso\$1 | 2020-07-13T20:19:09.254Z | ISO 8601/RFC 3339 | | \$1\$1\$1\$1from:date:seconds\$1 | 1594671549 | Unix 秒 epoch | | \$1\$1\$1\$1from:date:YYYY-MM\$1 | 2020-07 | 任何自定义数据格式。有关更多信息，请参阅[显示](https://momentjs.com/docs/#/displaying/)。 | 上面的语法也适用于 `${__to}`。 你也可以在中 URLs 使用这个变量。例如，要将最终用户发送到显示从六小时前到现在的时间范围的仪表板，请使用以下 URL：https://play.grafana。 org/d/000000012/grafana-play-home？ viewpanel=2&orgid=1？ from=now-6h&to=now ### \$1\$1\$1interval 你可以将该`$__interval`变量用作按时间（对于 InfluxDB、Myself、Postgres、MSSQL）、日期直方图间隔（对于）进行分组的参数，也可以用作*汇总*函数参数（对于 Graphite OpenSearch）。 Grafana 工作区会自动计算一个间隔，该间隔可用于在查询中按时间分组。当数据点多于图形上显示的数据点时，可通过按更大的间隔分组来提高查询的效率。例如，在查看 3 个月的数据时，按 1 天分组比按 10 秒分组更有效。图形看起来是一样的，查询速度也更快。`$__interval` 是使用时间范围和图形宽度（像素数）计算得出的。 近似计算：`(from - to) / resolution` 例如，当时间范围为 1 小时且图形为全屏时，则可以将间隔计算为 `2m`，点按 2 分钟间隔分组。如果时间范围为 6 个月且图形为全屏时，则间隔可能是 `1d`（1 天），点按天分组。 在 InfluxDB 数据来源中，传统变量 `$interval` 是同一个变量。请改用 `$__interval`。 InfluxDB 和 OpenSearch 数据源具有用于硬编码间隔或使用语法-> 设置`$__interval`变量的最小限制的`Group by time interval`字段。`>` `>10m` ### \$1\$1\$1interval\$1ms 此变量是以毫秒为单位的 `$__interval` 变量，而不是时间间隔格式的字符串。例如，如果 `$__interval` 为 `20m`，则 `$__interval_ms` 为 `1200000`。 ### \$1\$1\$1name 此变量仅在 Singlestat 面板中可用，可在**选项**选项卡上的前缀或后缀字段中使用。该变量将替换为序列名称或别名。 ### \$1\$1\$1org 此变量是当前组织的 ID。变量 `${__org.name}` 是当前组织的名称。 ### \$1\$1\$1user 变量 `${__user.id}` 是当前用户的 ID。变量 `${__user.login}` 是当前用户的登录句柄。变量 `${__user.email}` 是当前用户的电子邮件。 ### \$1\$1\$1range 目前仅 Prometheus 数据来源支持此变量。此变量表示当前控制面板的范围。由 `to - from` 计算得出。此变量有毫秒和秒两种表示形式，分别称为 `$__range_ms` 和 `$__range_s`。 ### \$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 数据来源。