变量

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

支持的变量类型

Scenes 支持以下变量类型

查询变量 (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 状态但将 drilldown-id 查询参数更新为此特定数据链接的插值值的 URL。

字段/系列宏

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

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

值/行宏

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

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

源代码

查看示例源代码

支持的变量类型​

向场景添加变量​

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

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

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

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

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

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

宏​

全局宏​

字段/系列宏​

值/行宏​

源代码​