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

添加变量

以下表格列出了Grafana附带的各种变量。

输入常规选项

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

1. 点击仪表板右上角的编辑。

2. 点击设置。

3. 转到变量选项卡。

4. 点击添加变量。

5. 为变量输入一个名称。

6. 在选择变量类型下拉菜单中，选择查询。

7. (可选) 在标签中，输入变量下拉菜单的显示名称。

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

8. 选择一个 仪表板显示 选项

   • 标签和值 - 变量下拉列表显示变量 名称 或 标签 值。这是默认选项。
   • 值： 变量下拉列表仅显示所选变量的值和一个向下箭头。
   • 无： 在仪表板上不显示变量下拉列表。

添加查询变量

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

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

查询表达式可以包含对其他变量的引用，从而创建关联变量。Grafana 检测到这一点，并在其关联变量之一更改时自动刷新变量。

1. 输入通用选项.

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

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

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

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

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

5. (可选) 在 正则表达式 字段中，输入一个正则表达式来过滤或捕获数据源查询返回的名称的特定部分。有关示例，请参阅 使用正则表达式过滤变量。

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

7. (可选) 输入 选择选项。

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

9. 点击 保存仪表板。

10. 点击 返回仪表板 和 退出编辑。

添加自定义变量

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

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

1. 输入通用选项.
2. 在 逗号分隔的值 列表中，输入此变量的逗号分隔的值列表。您可以包括数字、字符串或用空格和冒号分隔的键/值对。例如，key1 : value1,key2 : value2。
3. (可选) 输入 选择选项。
4. 在 值预览 中，Grafana 显示当前变量值的列表。检查它们以确保它们符合您的预期。
5. 点击 保存仪表板。
6. 点击 返回仪表板 和 退出编辑。

添加文本框变量

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

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

1. 输入通用选项.
2. （可选）在 默认值 字段中，选择变量的默认值。如果您在此字段中不输入任何内容，则 Grafana 将显示一个空文本框，供用户输入文本。
3. 在 值预览 中，Grafana 显示当前变量值的列表。检查它们以确保它们符合您的预期。
4. 点击 保存仪表板。
5. 点击 返回仪表板 和 退出编辑。

添加常量变量

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

常量变量 不是 灵活的。每个常量变量只保存一个值，除非您更新变量设置，否则它不能更新。

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

1. 输入通用选项.
2. 在 值 字段中，输入变量值。您可以输入字母、数字和符号。如果您使用 原始格式，还可以使用通配符。
3. 在 值预览 中，Grafana 显示当前变量值。请检查它以确保它与您预期的匹配。
4. 点击 保存仪表板。
5. 点击 返回仪表板 和 退出编辑。

添加数据源变量

数据源 变量允许您快速更改整个仪表板的数据源。如果您有多个数据源实例，例如在不同环境中，这很有用。

1. 输入通用选项.

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

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

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

4. (可选) 输入 选择选项。

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

6. 点击 保存仪表板。

7. 点击 返回仪表板 和 退出编辑。

添加间隔变量

使用 间隔 变量表示时间跨度，如 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. 点击 保存仪表板。
6. 点击 返回仪表板 和 退出编辑。

间隔变量示例

以下示例显示了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. 点击 保存仪表板。

4. 点击 返回仪表板 和 退出编辑。

创建临时过滤器

临时过滤器是可用的最复杂和灵活的变量选项之一。与常规变量选项列表不同，此变量允许您构建仪表板范围的临时查询。以这种方式应用的应用程序过滤器将应用于仪表板上的所有面板。

配置变量选择选项

选择选项是一种功能，您可以使用它来管理变量选项选择。所有选择选项都是可选的，并且默认情况下都是关闭的。

多值变量

选择多个值的多值变量插值很复杂，因为不直接如何将多个值格式化为字符串，使其在变量使用的上下文中有效。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 在变量下拉列表中添加了一个 所有 选项。如果用户选择此选项，则选择所有变量选项。

自定义所有值

如果选中了 包含所有选项，则此选项可见。

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

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

为了在 自定义所有值 选项中包含自定义的正则表达式、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秒分组更高效，图形看起来相同，查询也更快速。《code>$__interval》是根据时间范围和图表宽度（像素数）计算的。

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

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

在InfluxDB数据源中，旧变量$interval与此变量相同。《code>$__interval》应该被使用。

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

$__interval_ms

此变量是《code>$__interval》变量以毫秒为单位，而不是时间间隔格式化的字符串。例如，如果《code>$__interval》是《code>20m，则《code>$__interval_ms》是《code>1200000。

$__name

此变量仅在单统计面板中可用，并可用于选项选项卡上的前缀或后缀字段。变量将被替换为系列名称或别名。

$__org

此变量是当前组织的ID。《code>${__org.name}》是当前组织的名称。

$__user

仅在Grafana v7.1+中可用。

${__user.id}是当前用户的ID。《code>${__user.login}》是当前用户的登录名。《code>${__user.email}》是当前用户的电子邮件。

$__range

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

$__rate_interval

目前仅支持Prometheus数据源。《code>$__rate_interval》变量旨在用于速率函数。请参阅Prometheus查询变量获取详细信息。

$__rate_interval_ms

此变量是《code>$__rate_interval》变量以毫秒为单位，而不是时间间隔格式化的字符串。例如，如果《code>$__rate_interval》是《code>20m，则《code>$__rate_interval_ms》是《code>1200000。

$timeFilter或《code>$__timeFilter

《code>$timeFilter》变量返回当前选择的时间范围作为表达式。例如，时间范围间隔表达式《code>过去7天是《code>time > now() - 7d。

这用于多个地方，包括

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

$__timezone

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

如果当前选择的时间区域是《em>浏览器时间》，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不使用任一选项，因此您一次只能选择一个数据中心。

数据中心变量

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

复制

SHOW TAG VALUES WITH KEY = "datacenter"

返回的值是美洲、非洲、亚洲和欧洲。

主机变量

此变量的查询基本上表示，“给我目前所选数据中心的全部主机。”

复制

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

如果用户选择美洲，那么查询将变为

复制

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

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

如果用户选择欧洲，那么查询将变为

复制

SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^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关于正则表达式的指南：正则表达式。

以下选项列表的筛选示例

文本 复制

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="(?<text>[^"]+)|chip="(?<value>[^"]+)/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