文档 Grafana 文档 仪表盘 变量 添加变量

添加变量

下表列出了与 Grafana 附带的变量类型。

输入常规选项

您必须为创建的任何类型的变量输入常规选项。

1. 导航到您要创建变量的仪表盘，然后单击页面顶部的 **仪表盘设置**（齿轮）图标。

2. 在 **变量** 选项卡上，单击 **新建变量**。

3. 输入变量的 **名称**。

4. 在 **类型** 列表中，选择 **查询**。

5. （可选）在 **标签** 中，输入变量下拉菜单的显示名称。

   如果您没有输入显示名称，则下拉菜单标签将是变量名称。

6. 选择 **隐藏** 选项

   • **无选择（空白）：**变量下拉菜单显示变量 **名称** 或 **标签** 值。这是默认设置。
   • **标签：**变量下拉菜单仅显示选定的变量值和一个向下箭头。
   • **变量：**仪表盘上没有显示变量下拉菜单。

添加查询变量

查询变量使您可以编写数据源查询，该查询可以返回指标名称、标签值或键的列表。例如，查询变量可能会返回服务器名称、传感器 ID 或数据中心的列表。变量值会随着它们使用数据源查询动态获取选项而变化。

查询变量通常仅支持字符串。如果您的查询返回数字或任何其他数据类型，您可能需要将它们转换为字符串才能将它们用作变量。例如，对于 Azure 数据源，您可以使用 tostring 函数来实现此目的。

查询表达式可以包含对其他变量的引用，实际上可以创建链接变量。Grafana 会检测到这一点并自动刷新一个变量，当它链接的变量之一发生变化时。

**注意：**每个数据源的查询表达式都不同。有关更多信息，请参阅您的 数据源 的文档。

1. 输入常规选项.

2. 在 **数据源** 列表中，选择查询的目标数据源。有关数据源的更多信息，请参阅 添加数据源。

3. 在 **刷新** 列表中，选择变量应何时更新选项。

   • **仪表盘加载时：**每次加载仪表盘时查询数据源。这会减慢仪表盘加载速度，因为变量查询需要在初始化仪表盘之前完成。
   • **时间范围更改时：**每次加载仪表盘时以及仪表盘时间范围更改时查询数据源。如果您的变量选项查询包含时间范围过滤器或依赖于仪表盘时间范围，请使用此选项。

4. 在 **查询** 字段中，输入查询。

   • 查询字段根据您的数据源而有所不同。一些数据源具有自定义查询编辑器。
   • 每个数据源都定义了如何提取变量值。典型实现将从数据源响应返回的每个字符串值用作变量值。请务必仔细查看数据源的文档。
   • 某些数据源允许您为值提供自定义“显示名称”。例如，PostgreSQL、MySQL 和 Microsoft SQL Server 插件通过查找结果中名为 __text 和 __value 的字段来处理此问题。其他数据源可能会查找 text 和 value 或使用不同的方法。请始终记住仔细查看数据源的文档。
   • 如果您在一个输入字段查询编辑器中需要更多空间，则将鼠标悬停在字段右下角的线上并向下拖动以展开。

5. （可选）在 **正则表达式** 字段中，键入正则表达式以过滤或捕获数据源查询返回的名称的特定部分。要查看示例，请参阅 使用正则表达式过滤变量。

6. 在 **排序** 列表中，选择要在下拉列表中显示的值的排序顺序。默认选项 **禁用** 表示将使用数据源查询返回的选项顺序。

7. （可选）输入 选择选项。

8. 在**值预览**中，Grafana 显示当前变量值的列表。请查看它们以确保它们符合您的预期。

9. 单击**添加**将变量添加到仪表板。

添加自定义变量

使用自定义变量来表示不变的值，例如数字或字符串。

例如，如果您有永远不会改变的服务器名称或区域名称，那么您可能希望将它们创建为自定义变量而不是查询变量。由于它们不会改变，您可能会在链式变量中使用它们，而不是其他查询变量。这将减少 Grafana 在更新链式变量时必须发送的查询数量。

1. 输入常规选项.
2. 在**以逗号分隔的值**列表中，以逗号分隔的列表形式输入此变量的值。您可以包含数字、字符串或以空格和冒号分隔的键值对。例如，key1 : value1,key2 : value2。
3. （可选）输入 选择选项。
4. 在**值预览**中，Grafana 显示当前变量值的列表。请查看它们以确保它们符合您的预期。
5. 单击**添加**将变量添加到仪表板。

添加文本框变量

文本框变量显示一个带有可选默认值的自由文本输入字段。这是最灵活的变量，因为您可以输入任何值。如果您有具有高基数的指标，或者您希望同时更新仪表板中的多个面板，请使用这种类型的变量。

有关基数的更多信息，请参阅什么是基数峰值以及它们为何重要？

1. 输入常规选项.
2. （可选）在**默认值**字段中，选择变量的默认值。如果您未在此字段中输入任何内容，则 Grafana 将显示一个空文本框供用户在其中键入文本。
3. 在**值预览**中，Grafana 显示当前变量值的列表。请查看它们以确保它们符合您的预期。
4. 单击**添加**将变量添加到仪表板。

添加常量变量

常量变量使您能够定义一个隐藏的常量。这对于您想要共享的仪表板的指标路径前缀很有用。当您导出仪表板时，常量变量将转换为导入选项。

常量变量不灵活。每个常量变量只保存一个值，并且除非您更新变量设置，否则它无法更新。

当您需要在查询中包含复杂的值，但不想在每个查询中重新输入时，常量变量很有用。例如，如果您有一个名为i-0b6a61efe2ab843gg的服务器路径，那么您可以用一个名为$path_gg的变量替换它。

1. 输入常规选项.
2. 在**值**字段中，输入变量值。您可以输入字母、数字和符号。如果您使用原始格式，您甚至可以使用通配符。
3. 在**值预览**中，Grafana 显示当前变量值。请查看它以确保它符合您的预期。
4. 单击**添加**将变量添加到仪表板。

添加数据源变量

数据源变量使您能够快速更改整个仪表板的数据源。如果您有多个数据源实例（可能在不同的环境中），它们会很有用。

1. 输入常规选项.

2. 在**类型**列表中，选择变量的目标数据源。

   您也可以单击**打开高级数据源选择器**以查看更多选项，包括添加数据源（仅限管理员）。有关数据源的更多信息，请参阅添加数据源。

3. （可选）在**实例名称过滤器**中，输入一个正则表达式过滤器，用于从变量值下拉列表中选择哪些数据源实例。保留此字段为空以显示所有实例。

4. （可选）输入 选择选项。

5. 在**值预览**中，Grafana 显示当前变量值的列表。请查看它们以确保它们符合您的预期。

6. 单击**添加**将变量添加到仪表板。

添加间隔变量

使用间隔变量来表示时间跨度，例如1m、1h、1d。您可以将它们视为整个仪表板的“按时间分组”命令。间隔变量会改变数据在可视化中的分组方式。您还可以使用自动选项来返回每个时间跨度的一组数据点。

您可以将间隔变量用作按时间分组的参数（对于 InfluxDB）、日期直方图间隔（对于 Elasticsearch），或者用作汇总函数参数（对于 Graphite）。

1. 输入常规选项.
2. 在**值**字段中，输入您希望在变量下拉列表中显示的时间范围间隔。支持以下时间单位：s（秒）、m（分钟）、h（小时）、d（天）、w（周）、M（月）和y（年）。您也可以接受或编辑默认值：1m,10m,30m,1h,6h,12h,1d,7d,14d,30d。
3. （可选）如果您想将auto选项添加到列表中，请打开**自动选项**。此选项允许您指定当前时间范围应划分多少次以计算当前auto时间跨度。如果您打开它，则会出现另外两个选项
   • 步数 - 选择将当前时间范围划分多少次以计算值，类似于最大数据点查询选项。例如，如果当前可见时间范围为 30 分钟，则auto间隔将数据分组为 30 个一分钟的增量。默认值为 30 步。
   • 最小间隔 - 步数间隔将不会划分时间的最小阈值。为了继续 30 分钟的示例，如果最小间隔设置为 2m，则 Grafana 将数据分组为 15 个两分钟的增量。
4. 在**值预览**中，Grafana 显示当前变量值的列表。请查看它们以确保它们符合您的预期。
5. 单击**添加**将变量添加到仪表板。

间隔变量示例

以下示例显示了 Graphite 函数中的模板变量myinterval

复制

summarize($myinterval, sum, false)

以下示例显示了更复杂的 Graphite 示例，来自Graphite 模板嵌套请求面板

复制

groupByNode(summarize(movingAverage(apps.$app.$server.counters.requests.count, 5), '$interval', 'sum', false), 2, 'sum')

添加临时过滤器

临时过滤器使您能够添加键值过滤器，这些过滤器会自动添加到使用指定数据源的所有指标查询中。与其他变量不同，您不会在查询中使用临时过滤器。相反，您使用临时过滤器为现有查询编写过滤器。

1. 输入常规选项.

2. 在**数据源**列表中，选择目标数据源。

   您也可以单击**打开高级数据源选择器**以查看更多选项，包括添加数据源（仅限管理员）。有关数据源的更多信息，请参阅添加数据源。

3. 单击**添加**将变量添加到仪表板。

创建临时过滤器

临时过滤器是可用的最复杂和最灵活的变量选项之一。它不像普通的变量选项列表，而是允许您构建整个仪表板的临时查询。以这种方式应用的过滤器将应用于仪表板上的所有面板。

配置变量选择选项

选择选项是您可以用来管理变量选项选择的特性。所有选择选项都是可选的，并且默认情况下处于关闭状态。

多值变量

用选定的多个值插值变量很棘手，因为将多个值格式化为在使用变量的给定上下文中有效的字符串并不直观。Grafana 试图通过允许每个数据源插件告知模板插值引擎使用哪种格式来处理多个值来解决这个问题。

具有 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 执行此自动正则表达式转义和格式化，那么您必须执行以下操作之一

• 关闭多值或包含所有选项选项。
• 使用原始变量格式。

包含所有选项

Grafana 会在变量下拉列表中添加一个All选项。如果用户选择此选项，则将选择所有变量选项。

自定义所有值

此选项仅在选择包含所有选项时可见。

在自定义所有值字段中输入正则表达式、glob 或 lucene 语法以定义All选项的值。

默认情况下，All值包含组合表达式中的所有选项。这可能会变得非常长，并可能导致性能问题。有时，指定一个自定义的 all 值（例如通配符正则表达式）会更好。

为了在自定义所有值选项中拥有自定义正则表达式、glob 或 lucene 语法，它永远不会被转义，因此您需要考虑对您的数据源来说什么是有效值。

全局变量

Grafana 具有全局内置变量，这些变量可以在查询编辑器中的表达式中使用。本主题按字母顺序列出它们并进行定义。这些变量在查询、仪表板链接、面板链接和数据链接中很有用。

$__dashboard

仅在 Grafana v6.7+ 中可用。在 Grafana 7.1 中，变量从显示当前仪表板的 UID 更改为显示当前仪表板的名称。

此变量是当前仪表板的名称。

$__from 和 $__to

Grafana 有两个内置时间范围变量：$__from 和 $__to。它们目前始终默认插值为纪元毫秒，但您可以控制日期格式。

上述语法也适用于${__to}。

您也可以在 URL 中使用此变量。例如，您可以将用户发送到一个仪表板，该仪表板显示从六小时前到现在的時間范围：https://play.grafana.org/d/000000012/grafana-play-home?viewPanel=2&orgId=1?from=now-6h&to=now

$__interval

您可以使用 $__interval 变量作为参数按时间分组（对于 InfluxDB、MySQL、Postgres、MSSQL），日期直方图间隔（对于 Elasticsearch），或作为汇总函数参数（对于 Graphite）。

Grafana 会自动计算一个可在查询中按时间分组的间隔。当数据点多于图表上显示的数据点时，可以通过按较大的间隔分组来提高查询效率。在查看 3 个月的數據时，按 1 天分组比按 10 秒分组更有效率，而且图表外观相同，查询速度更快。$__interval 是根据时间范围和图表宽度（像素数）计算的。

近似计算：(to - from) / resolution

例如，当时间范围为 1 小时，图表全屏显示时，间隔可能计算为 2m - 数据点按 2 分钟间隔分组。如果时间范围为 6 个月，图表全屏显示，则间隔可能为 1d（1 天） - 数据点按天分组。

在 InfluxDB 数据源中，旧变量 $interval 与该变量相同。应使用 $__interval 替代。

InfluxDB 和 Elasticsearch 数据源具有 按时间间隔分组 字段，用于硬编码间隔或设置 $__interval 变量的最小限制（使用 > 语法 -> >10m）。

$__interval_ms

该变量是 $__interval 变量的毫秒值，而不是时间间隔格式字符串。例如，如果 $__interval 是 20m，则 $__interval_ms 为 1200000。

$__name

该变量仅在 Singlestat 面板中可用，可在选项选项卡上的前缀或后缀字段中使用。该变量将被替换为系列名称或别名。

$__org

该变量是当前组织的 ID。${__org.name} 是当前组织的名称。

$__user

仅在 Grafana v7.1+ 中可用

${__user.id} 是当前用户的 ID。${__user.login} 是当前用户的登录句柄。${__user.email} 是当前用户的电子邮件。

$__range

目前仅支持 Prometheus 和 Loki 数据源。该变量表示当前仪表板的范围。它由 to - from 计算。它具有毫秒和秒表示形式，分别称为 $__range_ms 和 $__range_s。

$__rate_interval

目前仅支持 Prometheus 数据源。$__rate_interval 变量用于 rate 函数。有关详细信息，请参阅 Prometheus 查询变量。

$__rate_interval_ms

该变量是 $__rate_interval 变量的毫秒值，而不是时间间隔格式字符串。例如，如果 $__rate_interval 是 20m，则 $__rate_interval_ms 为 1200000。

$timeFilter 或 $__timeFilter

$timeFilter 变量返回当前选择的时间范围作为表达式。例如，时间范围间隔 Last 7 days 表达式为 time > now() - 7d。

它在多个地方使用，包括

• InfluxDB 数据源的 WHERE 子句。在查询编辑器模式下，Grafana 会自动将其添加到 InfluxDB 查询中。您可以在文本编辑器模式下手动添加：WHERE $timeFilter。
• Azure Monitor 数据源中的日志分析查询。
• MySQL、Postgres 和 MSSQL 中的 SQL 查询。
• $__timeFilter 变量用于 MySQL 数据源。

$__timezone

$__timezone 变量返回当前选择的时间区域，可以是 utc 或 IANA 时区数据库的条目（例如，America/New_York）。

如果当前选择的时间区域是浏览器时间，Grafana 将尝试确定您的浏览器时区。

链式变量

链式变量，也称为链接变量或嵌套变量，是其变量查询中包含一个或多个其他变量的查询变量。本节介绍链式变量的工作原理，并提供使用链式变量的示例仪表板的链接。

链式变量查询对于每个数据源都不相同，但前提对于所有数据源都是相同的。您可以在允许使用链式变量查询的任何数据源中使用链式变量查询。

可以创建极其复杂的链接模板化仪表板，深度可达 5 或 10 层。从技术上讲，深度或复杂度没有限制，但链接越多，查询负载就越大。

Grafana Play 仪表板示例

以下 Grafana Play 仪表板包含相当简单的链式变量，只有两层深度。要查看变量及其设置，请单击仪表板设置（齿轮图标），然后单击变量。这两个示例在下一节中进行了扩展。

• Graphite 模板化嵌套
• InfluxDB 模板化

示例说明

变量有助于重用仪表板并动态更改仪表板中显示的内容。链式变量特别有助于筛选您看到的内容。

在变量中创建父子关系，类似于树形结构，您可以在其中选择不同级别的过滤器。

以下部分深入介绍了上面仪表板中链接的示例，并在它们的基础上进行了扩展。虽然示例是特定于数据源的，但这些概念可以广泛应用。

Graphite 示例

在此示例中，有多个应用程序。每个应用程序都有不同的服务器子集。它基于 Graphite 模板化嵌套。

现在，您可以为每个指标源创建单独的变量，但那样您就必须知道哪个服务器属于哪个应用程序。更好的解决方案是使用一个变量来筛选另一个变量。在此示例中，当用户更改 app 变量的值时，它会更改 server 变量返回的下拉选项。这两个变量都使用多值选项和包含所有选项，使用户能够随时选择一些或所有显示的选项。

app 变量

此变量的查询基本上表示“给我所有存在的应用程序”。

复制

apps.*

返回的值是 backend、country、fakesite 和 All。

server 变量

此变量的查询基本上表示“给我当前选择的应用程序的所有服务器”。

复制

apps.$app.*

如果用户选择 backend，则查询会更改为

复制

apps.backend.*

该查询返回与 backend 相关联的所有服务器，包括 backend_01、backend_02 等。

如果用户选择 fakesite，则查询会更改为

复制

apps.fakesite.*

该查询返回与 fakesite 相关联的所有服务器，包括 web_server_01、web_server_02 等。

更多变量

仪表板在两层停止，但您可以继续下去。例如，如果您想获取所选服务器的 CPU 指标，可以复制 server 变量并扩展查询，使其读取

复制

apps.$app.$server.cpu.*

该查询基本上表示“向我显示所选服务器的 CPU 指标”。

根据用户选择的变量选项，您可能会得到类似以下的查询

复制

apps.backend.backend_01.cpu.*
apps.{backend.backend_02,backend_03}.cpu.*
apps.fakesite.web_server_01.cpu.*

InfluxDB 示例

在此示例中，您有几个数据中心。每个数据中心都有不同的主机子集。它基于 InfluxDB 模板化 仪表板。

在此示例中，当用户更改 datacenter 变量的值时，它会更改 host 变量返回的下拉选项。host 变量使用多值选项和包含所有选项，使用户能够随时选择一些或所有显示的选项。datacenter 既不使用这两个选项，因此您一次只能选择一个数据中心。

datacenter 变量

此变量的查询基本上表示“给我所有存在的数据中心”。

复制

SHOW TAG VALUES WITH KEY = "datacenter"

返回的值是 America、Africa、Asia 和 Europe。

host 变量

此变量的查询基本上表示“给我当前选择的数据中心的所有主机”。

复制

SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^$datacenter$/

如果用户选择 America，则查询会更改为

复制

SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^America/

该查询返回与 America 相关联的所有服务器，包括 server1、server2 等。

如果用户选择 Europe，则查询会更改为

复制

SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^Europe/

该查询返回与 Europe 相关联的所有服务器，包括 server3、server4 等。

更多变量

仪表板在两层停止，但您可以继续下去。例如，如果您想获取所选主机的 CPU 指标，可以复制 host 变量并扩展查询，使其读取

复制

SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^$datacenter$/ AND "host" =~ /^$host$/

该查询基本上表示“向我显示所选主机的 CPU 指标”。

根据用户选择的变量选项，您可能会得到类似以下的查询

bash Copy

SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^America/ AND "host" =~ /^server2/
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^Africa/ AND "host" =~ /^server/7/
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^Europe/ AND "host" =~ /^server3+server4/

最佳实践和技巧

以下实践将使您的仪表板和变量更易于使用。

创建新的链接变量

• 链接变量创建父子依赖关系。您可以将它们想象成梯子或树。
• 创建新的链接变量最简单的方法是复制要基于其创建新变量的变量。在变量列表中，单击变量条目右侧的复制变量图标以创建副本。然后，您可以添加到父变量的查询中。
• 以这种方式创建的新变量将显示在列表的底部。您可能需要将其拖动到列表中的其他位置以将其排列到逻辑顺序。

变量顺序

您可以通过单击每个条目右侧的向上和向下箭头来更改仪表板变量列表中变量的顺序。Grafana 根据此列表从左到右列出变量下拉菜单，列表顶部的变量位于最左侧。

• 将没有依赖关系的变量列在顶部，在其子变量之前。
• 每个变量都应该遵循其依赖的变量。
• 请记住，UI 中没有指示哪些变量具有依赖关系。按逻辑顺序列出变量，以便其他用户（和您自己）更容易理解。

复杂度考虑

变量的依赖关系层级越多，更改变量后更新仪表板所需的时间就越长。

例如，如果您有一系列四个链接变量（国家、地区、服务器、指标），并且您更改了根变量值（国家），那么 Grafana 必须在更新仪表板中的可视化效果之前运行所有依赖变量的查询。

使用正则表达式筛选变量

使用正则表达式查询选项，您可以筛选变量查询返回的选项列表或修改返回的选项。

此页面介绍了如何使用正则表达式筛选/修改变量下拉菜单中的值。

使用正则表达式查询选项，您可以过滤变量查询返回的选项列表或修改返回的选项。有关更多信息，请参考 Mozilla 关于 正则表达式的指南。

以下选项列表的过滤示例

text 复制

backend_01
backend_02
backend_03
backend_04

过滤，以便仅返回以 01 或 02 结尾的选项

正则表达式

regex 复制

/(01|02)$/

结果

text 复制

backend_01
backend_02

使用正则表达式捕获组过滤和修改选项，以返回文本的一部分

正则表达式

regex 复制

/.*(01|02)/

结果

text 复制

01
02

过滤和修改 - Prometheus 示例

选项列表

text 复制

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

正则表达式

regex 复制

/.*instance="([^"]*).*/

结果

text 复制

demo.robustperception.io:9090
demo.robustperception.io:9093
demo.robustperception.io:9100

使用命名文本和值捕获组过滤和修改

使用命名捕获组，您可以从变量查询返回的选项中捕获单独的“文本”和“值”部分。这允许变量下拉列表包含可以选择的每个值的友好名称。

例如，在查询 node_hwmon_chip_names Prometheus 指标时，chip_name 比 chip 值更友好。因此，以下变量查询结果

text 复制

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

通过以下正则表达式传递

regex 复制

/chip_name="(?<text>[^"]+)|chip="(?<value>[^"]+)/g

将产生以下下拉列表

text 复制

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 捕获组名称。