变量

变量用于参数化场景。它们是值的占位符，可用于查询、面板标题，甚至自定义场景对象。在Grafana 官方文档中了解有关 Grafana 模板变量的更多信息。

支持的变量类型

场景支持以下变量类型

查询变量 (QueryVariable) - 由查询生成的列表，例如指标名称、服务器名称、传感器 ID、数据中心等。
数据源变量 (DataSourceVariable) - 定义给定类型的数据源列表。
自定义变量 (CustomVariable) - 使用逗号分隔的列表手动定义变量选项。
常量变量 (ConstantVariable) - 定义一个常量值变量。
文本框变量 (TextBoxVariable) - 显示一个自由文本输入字段，并带有一个可选的默认值。

将变量添加到场景

按照以下步骤将变量添加到场景。

步骤 1. 创建和自定义变量对象

从变量定义开始。以下代码创建了一个变量，该变量从 Prometheus 数据源检索 prometheus_http_requests_total 指标的所有 handler 标签值

const handlers = new QueryVariable({
  name: 'handler',
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  query: {
    query: 'label_values(prometheus_http_requests_total,handler)',
  },
});

注意

前面代码块中使用的 datasource 指的是 Grafana 核心 Prometheus 数据源插件。请确保您的 Grafana 堆栈已安装并配置了此插件。query 属性与您在查看仪表板设置中的仪表板 JSON 时在典型仪表板模板变量中看到的属性相同。

步骤 2. 配置场景以使用变量

使用 SceneVariableSet 对象为您的场景定义一个 $variables 属性

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  body: new SceneFlexLayout({
    children: [],
  }),
});

步骤 3. 在场景中显示变量选择器

使用 EmbeddedScene 的 controls 属性在场景顶部显示变量值选择器

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  body: new SceneFlexLayout({
    children: [],
  }),
  controls: [new VariableValueSelectors({})],
});

现在，在场景顶部显示了一个选择器，允许您更改变量值。

步骤 4. 在查询中使用变量

创建 SceneQueryRunner，它将查询 Prometheus 数据源并在查询中使用配置的变量

const queryRunner = new SceneQueryRunner({
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  queries: [
    {
      refId: 'A',
      range: true,
      format: 'time_series',
      expr: 'rate(prometheus_http_requests_total{handler="$handler"}[5m])',
    },
  ],
});

请注意，Prometheus 查询的 expr 属性使用 $handler 变量。在Grafana 官方文档中了解有关 Grafana 变量语法的更多信息。

步骤 5. 将数据添加到场景

将上一步中创建的 queryRunner 与场景连接

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  $data: queryRunner,
  body: new SceneFlexLayout({
    children: [],
  }),
  controls: [new VariableValueSelectors({})],
});

步骤 6. 将可视化添加到场景

要使用 handler 变量显示查询结果，请使用 VizPanel 类将时间序列可视化添加到场景

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  $data: queryRunner,
  body: new SceneFlexLayout({
    children: [
      new SceneFlexItem({
        body: PanelBuilders.timeseries().build(),
      }),
    ],
  }),
  controls: [new VariableValueSelectors({})],
});

使用场景顶部的选择器更改变量值，以查看可视化中的更新数据。

接下来，您将找到使用 QueryVariable 的场景的完整代码

const handlers = new QueryVariable({
  name: 'handler',
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  query: {
    query: 'label_values(prometheus_http_requests_total,handler)',
  },
});

const queryRunner = new SceneQueryRunner({
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  queries: [
    {
      refId: 'A',
      range: true,
      format: 'time_series',
      expr: 'rate(prometheus_http_requests_total{handler="$handler"}[5m])',
    },
  ],
});

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  $data: queryRunner,
  body: new SceneFlexLayout({
    children: [
      new SceneFlexItem({
        body: PanelBuilders.timeseries().build(),
      }),
    ],
  }),
  controls: [new VariableValueSelectors({})],
});

宏

变量系统支持各种内置宏，这些宏是无需包含任何其他变量即可使用的变量表达式。

全局宏

语法	描述
`${___url}`	当前 URL
`${__url.path}`	不带查询参数的当前 URL
`${__url.params}`	当前 URL 查询参数
`${__url.params:exclude:var-handler}`	不带 `var-handler` 的当前 URL 查询参数
`${__url.params:include:var-handler,var-instance}`	仅带 `var-handler` 和 `var-instance` 的当前 URL 查询参数

使用类似以下的字符串从表格创建到另一个页面的数据链接，并保留所有查询参数

/scene-x/my-drilldown-view/${__value.raw}${__url.params}

使用类似以下的字符串更新当前场景 URL，添加新的查询参数或更新现有参数

/my-scene-url${__url.params:exclude:drilldown-id}&drilldown-id=${__value.raw}

这将生成一个 URL，该 URL 保留了 url 状态，但将 drilldown-id 查询参数更新为此特定数据链接的插值值。

字段/系列宏

以下宏适用于数据链接和字段覆盖属性（如 displayName）。

语法	描述
`${__field.name}`	将插值到字段/系列名称
`${__field.labels.cluster}`	将插值到 cluster 标签的值

值/行宏

以下宏适用于基于行和值的数据链接。

语法	描述
`${__value.text}`	对于表格和其他渲染行/值的可视化中的数据链接很有用
`${__value.raw}`	未格式化的值
`${__data.fields[0].text}`	将插值到同一行上第一个字段/列的值

源代码

查看示例源代码

支持的变量类型​

将变量添加到场景​

步骤 1. 创建和自定义变量对象​

步骤 2. 配置场景以使用变量​

步骤 3. 在场景中显示变量选择器​

步骤 4. 在查询中使用变量​

步骤 5. 将数据添加到场景​

步骤 6. 将可视化添加到场景​

宏​

全局宏​

字段/系列宏​

值/行宏​

源代码​