使用仪表板模板变量

Chronograf 仪表板模板变量允许您在不编辑查询的情况下更新单元格查询，这使得与仪表板单元格交互和探索数据变得容易。

• 使用模板变量
• 预定义模板变量
• 创建自定义模板变量
• 模板变量类型
• 保留变量名
• 高级模板变量使用

使用模板变量

创建 Chronograf 仪表板时，请在单元格查询和标题中使用预定义模板变量或自定义模板变量。设置变量后，变量将在仪表板用户界面（UI）中可用。

• 在单元格查询中使用模板变量
  • InfluxQL
  • Flux
• 在单元格标题中使用模板变量

在单元格查询中使用模板变量

InfluxQL 和 Flux 都支持模板变量。

InfluxQL

在 InfluxQL 查询中，将模板变量名用以下方式包围在冒号（:）内：

SELECT :variable_name: FROM "telegraf"."autogen".:measurement: WHERE time < :dashboardTime:

InfluxQL 中的模板变量引号

对于例如“字段键”和“标签值”这样的预定义元查询，不要在查询中添加引号（单引号或双引号）。Chronograf 将按照以下方式添加引号：

SELECT :variable_name: FROM "telegraf"."autogen".:measurement: WHERE time < :dashboardTime:

对于自定义查询、CSV或映射查询，按照标准的InfluxQL语法在查询中对值进行引号引用。

• 对于数值值，不需要引号。
• 对于字符串值，请在变量定义（或不是）中选择引号值。请参阅以下字符串示例。

字符串示例

在定义模板变量或在查询中添加单引号，但不要两者都添加。

在变量定义中添加单引号

如果您使用单引号定义名为 host 的自定义 CSV 变量

'host1','host2','host3'

在查询中不要包含引号

SELECT mean("usage_user") AS "mean_usage_user" FROM "telegraf"."autogen"."cpu" 
WHERE "host" = :host: and time > :dashboardTime

在查询中添加单引号

如果您未在定义名为 host 的自定义 CSV 变量时使用引号

host1,host2,host3

在查询中添加单引号

SELECT mean("usage_user") AS "mean_usage_user" FROM "telegraf"."autogen"."cpu" 
WHERE "host" = ':host:' and time > :dashboardTime

Flux

在 Flux 中，模板变量存储在 v 记录中。使用点或括号符号引用 v 记录内的变量键。

from(bucket: v.bucket)
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._field == v["Field key"])
  |> aggregateWindow(every: v.windowPeriod, fn: v.aggregateFunction)

在单元格标题中使用模板变量

要动态更改仪表板单元格的标题，请使用 :variable-name: 语法。

例如，一个名为 field 且值为 temp 的变量和一个名为 location 且值为 San Antonio 的变量，请使用以下语法：

:temp: data for :location:

显示为

预定义模板变量

Chronograf 包含受 Chronograf UI 元素控制的预定义模板变量。请在单元格查询中使用预定义模板变量。

InfluxQL 和 Flux 包含它们自己的预定义模板变量集

InfluxQL Flux

• :dashboardTime
• :upperDashboardTime
• :interval

dashboardTime

:dashboardTime: 模板变量由 Chronograf 仪表板中的“时间”下拉菜单控制。

如果使用相对时间，它表示下拉菜单中指定的偏移时间（-5m、-15m、-30m 等），并假设时间是相对于“现在”的。如果使用日期选择器定义的绝对时间，:dashboardTime: 将填充下限阈值。

SELECT "usage_system" AS "System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardTime:

要使用日期选择器指定过去的时间范围，请使用 :dashboardTime: 作为开始时间，使用 :upperDashboardTime: 作为结束时间构建查询。

upperDashboardTime

:upperDashboardTime: 模板变量由使用日期选择器指定的上限时间定义。

在使用相对时间范围时，它将继承now()；在使用绝对时间范围时，则继承上限时间。

SELECT "usage_system" AS "System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardTime: AND time < :upperDashboardTime:

间隔

在Chronograf仪表板上，:interval:模板变量由间隔下拉菜单定义。

在单元格查询中，它应该在伴随聚合函数的GROUP BY time()子句中使用。

SELECT mean("usage_system") AS "Average System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardtime:
GROUP BY time(:interval:)

• v.timeRangeStart
• v.timeRangeStop
• v.windowPeriod

向后兼容的Flux模板变量

Chronograf 1.9+支持将预定义模板变量和自定义模板变量存储在v记录中，并使用点或方括号表示法引用变量。为了向后兼容，Chronograf 1.9+仍然支持以下预定义变量，它们不使用v.语法

• dashboardTime
• upperDashboardTime
• autoInterval

v.timeRangeStart

模板变量v.timeRangeStart由Chronograf仪表板上的“时间”下拉菜单控制。

如果使用相对时间，则此变量代表下拉菜单中指定的偏移时间（-5m、-15m、-30m等），并假定时间相对于“现在”。如果使用由日期选择器定义的绝对时间，则v.timeRangeStart将填充为开始时间。

from(bucket: "telegraf/autogen")
  |> range(start: v.timeRangeStart)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system")

要使用日期选择器指定不包含“now”的过去时间范围，请将v.timeRangeStart用作开始时间，将v.timeRangeStop用作结束时间。

v.timeRangeStop

模板变量v.timeRangeStop由使用日期选择器指定的上限时间定义。

对于相对时间范围，此变量继承now()。对于绝对时间范围，此变量继承上限时间。

from(bucket: "telegraf/autogen")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system")

v.windowPeriod

模板变量v.windowPeriod由仪表板单元格的显示宽度控制，并由每个像素覆盖的时间长度计算得出。使用v.windowPeriod变量可以限制下采样数据，以在显示中每像素最多显示一个点。

from(bucket: "telegraf/autogen")
  |> range(start: v.timeRangeStart)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)

创建自定义模板变量

Chronograf允许您创建由元查询或CSV上传提供支持的自定义模板变量，这些变量返回一个可能的值数组。

要创建模板变量

1. 点击仪表板顶部的模板变量，然后点击+ 添加变量。
2. 从数据源下拉菜单中选择一个数据源。
3. 为变量提供一个名称。
4. 选择变量类型。类型定义了获取可能的值数组的方法。
5. 查看潜在值的列表并选择一个默认值。如果使用CSV或映射类型，请上传或输入CSV，其中包含所需的值，然后选择一个默认值。
6. 点击创建。

创建后，模板变量可以用于任何单元格的查询或标题，并在仪表板顶部包含变量的下拉菜单。

模板变量类型

Chronograf支持以下模板变量类型

• 数据库
• 测量
• 字段键
• 标签键
• 标签值
• CSV
• 映射
• InfluxQL元查询
• Flux查询
• 文本

数据库

数据库模板变量允许您从多个目标数据库中选择。

数据库元查询
数据库模板变量使用以下元查询来返回InfluxDB实例中所有数据库的数组。

SHOW DATABASES

单元格查询中的示例数据库变量

SELECT "purchases" FROM :databaseVar:."autogen"."customers"

数据库变量用例

在可视化具有相似或相同数据结构的多个数据库时使用数据库模板变量。变量允许您快速切换到每个数据库的各个可视化。

测量

更改目标度量。

度量元查询
度量模板变量使用以下元查询来返回给定数据库中所有度量的数组。

SHOW MEASUREMENTS ON database_name

单元格查询中的示例度量变量

SELECT * FROM "animals"."autogen".:measurementVar:

度量变量用例

度量模板变量允许您在仪表板中的单个单元格或多个单元格之间快速切换度量。

字段键

更改目标字段键。

字段键元查询
字段键模板变量使用以下元查询来返回给定数据库中给定度量的所有字段键的数组。

SHOW FIELD KEYS ON database_name FROM measurement_name

单元格查询中的示例字段键变量

SELECT :fieldKeyVar: FROM "animals"."autogen"."customers"

字段键变量用例

如果想要在给定度量中快速切换字段键的可视化，字段键模板变量非常出色。

标签键

更改目标标签键。

标签键元查询
标签键模板变量使用以下元查询来返回给定数据库中给定度量的所有标签键的数组。

SHOW TAG KEYS ON database_name FROM measurement_name

单元格查询中的示例标签键变量

SELECT "purchases" FROM "animals"."autogen"."customers" GROUP BY :tagKeyVar:

标签键变量用例

如果想要在给定度量中快速切换标签键的可视化，标签键模板变量非常出色。

标签值

更改目标标签值。

标签值元查询
标签值模板变量使用以下元查询来返回与指定度量数据库中给定标签键关联的所有值的数组。

SHOW TAG VALUES ON database_name FROM measurement_name WITH KEY tag_key

单元格查询中的示例标签值变量

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "species" = :tagValueVar:

标签值变量用例

如果想要在给定度量中快速切换标签值的可视化，标签值模板变量非常出色。

CSV

使用逗号分隔的值（CSV）的定制列表更改查询的一部分。

示例 CSV

value1, value2, value3, value4

value1
value2
value3
value4

'string1','string2','string3','string4'

单元格查询中的示例 CSV 变量

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "petname" = :csvVar:

CSV 变量用例

当您无法使用元查询从 InfluxDB 中获取变量所需值的数组时，CSV 模板变量非常出色。它们允许您使用自定义变量值。

映射

使用 CSV 格式的定制键值对列表更改查询的一部分。键值对的键用于在仪表板中填充模板变量下拉列表。值在处理单元格查询时使用。

示例 CSV

key1,value1
key2,value2
key3,value3
key4,value4

key1,'value1'
key2,'value2'
key3,'value3'
key4,'value4'

单元格查询中的示例 Map 变量

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "customer" = :mapVar:

Map 变量用例

当您需要将简单的名称或键映射或别名为较长的或更复杂的值时，Map 模板变量非常好。例如，您可能想创建一个 :customer: 变量，该变量用长数字客户 ID（11394850823894034209）填充单元格查询。使用 Map 变量，您可以将简单名称别名为复杂值，因此您的客户列表看起来可能如下

Apple,11394850823894034209
Amazon,11394850823894034210
Google,11394850823894034211
Microsoft,11394850823894034212

客户名称将填充您的模板变量下拉列表，而不是客户 ID。

InfluxQL元查询

使用自定义元查询更改查询的一部分，该查询从 InfluxDB 中提取特定值的数组。InfluxQL 元查询变量允许您提取高度定制的值数组，并提供了诸如基于其他模板变量过滤值等高级功能。

单元格查询中的示例自定义元查询变量

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "customer" = :customMetaVar:

InfluxQL元查询变量使用场景

当预定义的模板变量类型无法返回所需的值时，请使用自定义InfluxQL元查询模板变量。

Flux查询

Flux查询模板变量允许您使用Flux查询来定义变量值。变量值来自您的Flux查询返回的_value列。

Flux查询变量使用场景

当所需的变量值无法使用InfluxQL查询或您需要Flux的灵活性以返回所需的变量值列表时，Flux查询模板变量非常出色。

文本

使用单个文本字符串更改查询的一部分。每个文本变量只有一个值，但这个值很容易更改。

文本变量使用场景

文本模板变量允许您动态更改查询，例如一次性添加或更改多个单元格的WHERE子句。您还可以使用文本模板变量来更改多个查询中使用的正则表达式。当需要解决影响多个可视化指标的事故时，它们非常出色。

保留变量名

以下变量名是保留的，在创建模板变量时不能使用。Chronograf还接受模板变量作为URL查询参数以及许多其他控制仪表板中图形显示的参数。这些名称要么是预定义变量，要么会与现有的URL查询参数冲突。

• :database
• :measurement
• :dashboardTime
• :upperDashboardTime
• :interval
• :upper
• :lower
• :zoomedUpper
• :zoomedLower
• :refreshRate

高级模板变量使用

使用其他模板变量过滤模板变量

自定义InfluxQL元查询模板变量允许您使用其他现有模板变量来过滤潜在的变量值数组。

例如，假设您想列出与测量相关联的所有字段键，但想能够更改测量

1. 创建一个名为:measurementVar:的模板变量（名称“measurement”是保留的），该变量使用测量变量类型来检索来自telegraf数据库的所有测量。

   

2. 创建一个名为:fieldKey:的模板变量，该变量使用InfluxQL元查询变量类型。以下元查询根据现有的:measurementVar:模板变量检索字段键列表。

   SHOW FIELD KEYS ON telegraf FROM :measurementVar:
   

   

3. 创建一个新的仪表板单元格，在该单元格的查询中使用fieldKey和measurementVar模板变量。

   InfluxQL Flux

   SELECT :fieldKey: FROM "telegraf"..:measurementVar: WHERE time > :dashboardTime:
   

   from(bucket: "telegraf/")
     |> range(start: v.timeRangeStart)
     |> filter(fn: (r) =>
       r._measurement == v.measurementVar and
       r._field == v.fieldKey
     )
   

生成的仪表板将这样工作

在URL中定义模板变量

Chronograf使用URL查询参数（也称为查询字符串参数）来设置显示选项和模板变量。这使得共享仪表板的链接变得容易，以便它们以特定的状态加载，并选择特定的模板变量值。

URL查询参数以问号（?）附加到URL的末尾，表示查询参数的开始。使用与号（&）连接多个查询参数。

要声明模板变量或日期范围作为URL查询参数，它必须遵循以下模式

模板变量查询参数的模式

# Spaces for clarity only
& tempVars %5B variableName %5D = variableValue

&
表示多个查询参数系列中新的查询参数的开始。

tempVars
通知Chronograf正在传递的查询参数是一个模板变量。 所有模板变量查询参数均需使用。

%5B, %5D
URL编码的分别表示包围模板变量名称的[和]。

variableName
模板变量的名称。

variableValue
模板变量的值。

示例模板变量查询参数

.../?&tempVars%5BmeasurementVar%5D=cpu

在URL中包含多个模板变量

要将多个模板变量作为URL查询参数链接起来，请为每个模板变量包含完整的模式。

# Spaces for clarity only
.../?  &tempVars%5BmeasurementVar%5D=cpu  &tempVars%5BfieldKey%5D=usage_system