变量

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

支持的变量类型

场景支持以下变量类型

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

将变量添加到场景

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

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

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

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}`	当前 URL 查询参数（不带 `var-handler`）
`${__url.params:include:var-handler,var-instance}`	当前 URL 查询参数（仅包含 `var-handler` 和 `var-instance`）

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

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

使用类似于以下字符串来更新当前场景URL的新查询参数或更新它（如果存在）

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

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

字段/系列宏

以下宏在数据链接和字段覆盖属性（如displayName）中工作。

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

值/行宏

以下宏在基于行和值的行数据链接中工作。

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

源代码

查看示例源代码

支持的变量类型​

将变量添加到场景​

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

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

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

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

步骤 5. 向场景添加数据​

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

宏​

全局宏​

字段/系列宏​

值/行宏​

源代码​