模板和变量

本文档主题专为支持 Grafana 8.x 版本的 Grafana 工作空间而设计。

有关支持 Grafana 版本 10.x 的 Grafana 工作空间，请参阅。在 Grafana 版本 10 中工作

有关支持 Grafana 9.x 版本的 Grafana 工作空间，请参阅。在 Grafana 版本 9 中工作

变量是值的占位符。您可以在指标查询和面板标题中使用变量。变量使您能够创建更具交互性和动态性的仪表板。无需在指标查询中对服务器、应用程序和传感器名称之类的内容进行硬编码，而是可以使用变量来代替它们。

变量以下拉列表的形式显示在仪表板的顶部。当您使用控制面板顶部的下拉列表更改该值时，面板的指标查询会反映新的值。

对于希望允许查看者快速调整可视化效果但又不想向他们授予完全编辑权限的管理员来说，这些功能可能特别有用。Grafana 的查看者可以使用变量。

通过使用变量和模板，您可以单一来源仪表板。如果您有多个相同的数据源或服务器，则可以创建一个仪表板并使用变量来更改正在查看的内容。这简化了维护和保养。

有关支持的变量类型的列表以及添加每种变量的说明，请参见 变量类型

模板

模板是任何包含变量的查询。

例如，如果您管理控制板来监控多台服务器，则可以为每台服务器创建一个仪表板。或者，您可以创建一个仪表板并使用带有模板查询的面板，如以下示例所示。

wmi_system_threads{instance=~"$server"}

变量值始终使用语法var-<varname>=value同步到 URL。

可变的最佳实践

变量下拉列表按控制面板设置中变量列表中的列出顺序显示。

将经常更改的变量放在顶部，这样它们就会首先显示在仪表板的最左边。

变量语法

面板标题和指标查询可以使用两种不同的语法来查看变量：

• $varname此语法更易于阅读，如以下示例所示：apps.frontend.$server.requests.count。但是，不能在单词中间使用变量。

• ${var_name}如果要在表达式中间插入变量，请使用此语法。

• ${var_name:<format>}这种格式使您可以更好地控制 Grafana 如何插值。有关更多信息，请参阅 高级变量格式选项。

在将查询发送到您的数据源之前，会对查询进行插值，这意味着变量将替换为其当前值。在插值过程中，变量值可能会被转义以符合查询语言的语法及其使用位置。例如，在 Prometheus 查询的正则表达式中使用的变量将被正则表达式转义。有关插值期间值转义的详细信息，请阅读数据源特定的文档主题。

有关覆盖数据源默认格式的高级语法的信息，请参见高级变量格式选项。

其他变量选项

本节介绍其他可用的变量选项。

输入变量选择选项

您可以使用 “选择选项” 来管理变量选项选择。所有选择选项都是可选的，默认情况下它们处于关闭状态。

多值

如果启用此选项，则变量下拉列表支持同时选择多个选项。有关更多信息，请参阅 格式化多值变量。

“全部包含” 选项

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

自定义所有值

仅当选择 “全部包含” 选项时，此选项才可见。

要定义All选项的值，请在 “自定义所有值” 字段中输入正则表达式、glob 或 Lucene 语法。

默认情况下，该All值包括组合表达式中的所有选项。这可能会变得很长，并且可能会出现性能问题。有时最好指定一个自定义 all 值，比如通配符正则表达式。

在 “自定义所有值” 选项中使用自定义正则表达式、glob 或 Lucene 语法时，它永远不会被转义，因此必须考虑什么是数据源的有效值。

高级变量格式选项

变量插值的格式取决于数据源，但在某些情况下，您可能需要更改默认格式。

例如，MySQL 数据源的默认设置是以逗号分隔的多个值并使用引号:。'server01','server02'在某些情况下，你可能想要一个不带引号的逗号分隔的字符串：。server01,server02为此，请使用以下高级变量格式选项。

一般语法

语法：${var_name:option}

如果指定了任何无效的格式选项，glob则为默认选项或备用选项。

CSV

将具有多个值的变量格式化为逗号分隔的字符串。

servers = ['test1', 'test2']
String to interpolate: '${servers:csv}'
Interpolation result: 'test1,test2'

分布式——OpenTSDB

以 OpenTSDB 的自定义格式格式化具有多个值的变量。

servers = ['test1', 'test2']
String to interpolate: '${servers:distributed}'
Interpolation result: 'test1,servers=test2'

双引号

将单值和多值变量格式化为逗号分隔的字符串，在每个值"中使用转义符\"，并用引号引用每个值。"

servers = ['test1', 'test2']
String to interpolate: '${servers:doublequote}'
Interpolation result: '"test1","test2"'

Glob-石墨

将具有多个值的变量格式化为 glob（用于 Graphite 查询）。

servers = ['test1', 'test2']
String to interpolate: '${servers:glob}'
Interpolation result: '{test1,test2}'

JSON

将具有多个值的变量格式化为逗号分隔的字符串。

servers = ['test1', 'test2']
String to interpolate: '${servers:json}'
Interpolation result: '["test1", "test2"]'

Lucene- OpenSearch

以 Lucene 格式格式化具有多个值的变量。 OpenSearch

servers = ['test1', 'test2']
String to interpolate: '${servers:lucene}'
Interpolation result: '("test1" OR "test2")'

百分比码

格式化单值和多值变量以用于 URL 参数。

servers = ['foo()bar BAZ', 'test2']
String to interpolate: '${servers:percentencode}'
Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2'

竖线

将具有多个值的变量格式化为用竖线分隔的字符串。

servers = ['test1.', 'test2']
String to interpolate: '${servers:pipe}'
Interpolation result: 'test1.|test2'

原始

关闭数据源特定的格式，例如 SQL 查询中的单引号。

servers = ['test1.', 'test2']
String to interpolate: '${var_name:raw}'
Interpolation result: '{test.1,test2}'

正则表达式

将具有多个值的变量格式化为正则表达式字符串。

servers = ['test1.', 'test2']
String to interpolate: '${servers:regex}'
Interpolation result: '(test1\.|test2)'

单引号

将单值和多值变量格式化为逗号分隔的字符串，在每个值'中使用转义符\'并用引号将每个值加上引号。'

servers = ['test1', 'test2']
String to interpolate: '${servers:singlequote}'
Interpolation result: "'test1','test2'"

Sqlstring

将单值和多值变量格式化为逗号分隔的字符串，在每个值'中使用转义符''并用引号将每个值加上引号。'

servers = ["test'1", "test2"]
String to interpolate: '${servers:sqlstring}'
Interpolation result: "'test''1','test2'"

文本

将单值和多值变量格式化为其文本表示形式。对于单个变量，它只会返回文本表示形式。对于多值变量，它将返回与+组合的文本表示形式。

servers = ["test1", "test2"]
String to interpolate: '${servers:text}'
Interpolation result: "test1 + test2"

格式化多值变量

对选择了多个值的变量进行插值很棘手，因为如何将多个值格式化为在使用该变量的给定上下文中有效的字符串并不直截了当。Grafana 试图通过启用每个数据源插件来通知模板插值引擎对多个值使用哪种格式来解决这个问题。

注意

变量上的 “自定义所有值” 选项必须为空，Grafana 才能将所有值格式化为单个字符串。如果将其留空，则 Grafana 会将查询中的所有值串联（相加）。比如value1,value2,value3。如果使用自定义all值，则该值将类似于*或all。

带有 Graphite 数据源的多值变量

Graphite 使用全局表达式。在这种情况下，将对具有多个值的变量进行插值，就好{host1,host2,host3}像当前变量值为 host1、host 2 和 host3 一样。

带有 Prometheus 或 InfluxDB 数据源的多值变量

InfluxDB 和 Prometheus 使用正则表达式，因此将对相同的变量进行插值。(host1|host2|host3)每个值也会被正则表达式转义。否则，带有正则表达式控制字符的值将破坏正则表达式。

带有 Elastic 数据源的多值变量

Amazon OpenSearch 使用 Lucene 查询语法，因此相同的变量格式为。("host1" OR "host2" OR "host3")在这种情况下，必须对每个值进行转义，以便该值仅包含 Lucene 控制词和引号。

格式化问题排除

自动转义和格式化可能会导致问题。理解问题背后的逻辑可能很棘手，特别是对于 InfluxDB 和 Prometheus 来说，使用正则表达式语法要求在正则表达式运算符上下文中使用变量。

如果您不希望 Grafana 自动进行正则表达式转义和格式化，则必须执行以下操作之一：

• 关闭 “多值全部包含” 选项选项。

• 使用 [原始变量格式] ({{< relref "advanced-variable-format-options.md #raw" >}})。

使用正则表达式过滤变量

使用 Regex Query 选项，您可以筛选变量查询返回的选项列表或修改返回的选项。

本节介绍如何使用正则表达式筛选和修改变量下拉列表中的值。

使用 Regex Query 选项，您可以筛选变量查询返回的选项列表或修改返回的选项。有关更多信息，请参阅正则表达式。

对以下选项列表进行筛选的示例：

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

注意：仅支持text和value捕获组名称。

重复面板或行

您可以使用模板变量创建动态仪表板。在将查询发送到数据库之前，查询中的所有变量都会扩展为变量的当前值。使用变量，您可以为所有服务重复使用单个仪表板。

模板变量对于在整个仪表板上动态更改查询非常有用。如果您希望 Grafana 根据您选择的值动态创建新的面板或行，则可以使用 “重复” 功能。

重复面板

如果你开启了Multi-value或Include all value选项的变量，你可以选择一个面板，让 Grafana 为每个选定的值重复该面板。在面板编辑模式下，您可以在 “常规” 选项卡下找到 “重复” 功能。

direction控制面板的排列方式。

如果您愿意horizontal，则可以对面板进行排列 side-by-side。Grafana 会自动调整每个重复面板的宽度，以便填充整行。当前，您不能将一行中的其他面板与重复的面板混合使用。

设置Max per row为告诉 Grafana 您每行最多想要多少个面板。默认为 4。

如果您愿意vertical，面板将从上到下排列成一列。重复面板的宽度与正在重复的第一个面板（原始模板）的宽度相同。

仅对第一个面板（原始模板）进行更改。要使更改在所有面板上生效，您需要开始动态重新构建仪表板。您可以通过更改变量值（即重复的基础）或重新加载仪表板来实现此目的。

注意

重复面板要求变量选择一个或多个项目。您不能将面板重复零次以将其隐藏。

重复行

如上所示，如果使用Multi-value或Include all value选择选项设置了变量，则也可以重复行。

要开启此功能，必须先使用 “添加面板” 菜单添加新行。然后将鼠标悬停在行标题上并选择齿轮按钮以访问Row Options配置面板。然后，您可以选择要重复该行的变量。

最佳做法是在行标题中也使用变量。