使用 ES|QL 变量控件将仪表板转变为调查工具

Elastic 中国社区官方博客

173人浏览 · 2026-03-26 14:47:13

Elastic 中国社区官方博客 · 2026-03-26 14:47:13 发布

作者：来自 Elastic Miguel Sánchez

学习如何在 Kibana 中使用 ES|QL 变量，将仪表板转变为调查工具，通过应用值控件和结构控件来发现问题。

静态仪表板在大多数情况下是有用的，但一旦发生事故，默认视图往往会隐藏你需要的关键信号。在 Kibana 仪表板中使用 ES|QL 变量控件，可以在无需修改任何查询的情况下，从一个看似健康的整体视图快速定位到清晰的根因。

在本文中，我们将展示这些 ES|QL 变量控件如何将仪表板转变为交互式调查工具，以及如何设置它们来揭示被平均值掩盖的问题。通过在控件中选择一个值，所有使用该变量的面板都会随之动态调整。

仪表板

这是一个自定义的 “基础设施总览/Infrastructure Overview” 仪表板，用于监控分布在 3 个 AWS 区域的 10 台主机，基于 OpenTelemetry 主机指标构建。仪表板包含四个折线图（CPU、内存、磁盘、负载平均值）以及顶部的 ES|QL 变量控件。

在默认仪表板设置下（AVG 聚合、按 region 切分、15 分钟时间桶、选择所有主机），一切看起来都很健康。三个区域都呈现平滑的昼夜周期。

但这个视图中隐藏着一个问题。

固定查询的问题

固定图表查询将一些在调查过程中需要变化的决策硬编码了：

聚合函数（AVG、MAX、MIN、MEDIAN）
用于切分数据的维度（host、region、availability zone）
包含或排除哪些主机
时间桶间隔（1m、5m、15m、1h）

当这些被固定后，每次调整都意味着需要在多个面板中修改查询。

ES|QL 变量控件

ES|QL 变量控件可以在运行时将用户选择的值注入查询中。主要有两种类型：

值控件（?variable）：替换查询中的值，例如时间间隔或主机名列表
结构控件（??variable）：替换函数名或字段名，例如聚合函数或用于切分数据的维度

通过这种方式，可以用一套查询模式复用在所有面板中。

查询

原始的静态 CPU 查询如下：

TS metrics-hostmetricsreceiver.otel-default
| WHERE system.cpu.utilization IS NOT NULL
  AND attributes.state != "idle"
| STATS AVG(system.cpu.utilization)
  BY BUCKET(@timestamp, 1 minute), resource.attributes.host.name

为了让该查询适配变量控件，需要将每个硬编码部分替换为变量。聚合函数、时间桶以及分组维度都可以直接替换。主机名过滤则需要额外一步，因为我们希望控件支持一次选择多个主机，而按单个值过滤一次只能匹配一个主机。MV_CONTAINS 用于检查某个值是否存在于多值列表中，因此 MV_CONTAINS(?hostname, resource.attributes.host.name) 会在字段包含控件中任意选定值时返回 true。

完成这些替换后，查询变为：

TS metrics-hostmetricsreceiver.otel-default
| WHERE system.cpu.utilization IS NOT NULL
  AND attributes.state != "idle"
  AND MV_CONTAINS(?hostname, resource.attributes.host.name)
| STATS ??aggregation(system.cpu.utilization)
  BY BUCKET(@timestamp, ?interval), ??breakdown

同样的模式适用于所有四个面板（CPU、内存、磁盘、负载）。更改任意控件都会同时更新所有面板。

控件

主机名（?hostname）：根据控件中选择的主机进行过滤。配置为 “Values from a query”，并启用多选。它会运行一个 ES|QL 查询来返回可用的主机名，而图表查询中的 MV_CONTAINS 使得可以同时选择多个主机。

聚合（??aggregation）：用于替换聚合函数。配置为静态值控件，包含 AVG、MAX、MIN、MEDIAN。
时间间隔（?interval）：控制时间桶大小。配置为静态值控件，包含 1 minute、5 minutes、15 minutes、1 hour。
分组维度（??breakdown）：用于替换数据切分维度。配置为静态值控件，包含 resource.attributes.host.name、resource.attributes.cloud.region、resource.attributes.cloud.availability_zone。

调查过程

仪表板初始状态为：AVG 聚合、按 region 分组、15 分钟时间桶、选择所有主机。一切看起来都没有问题。

第一步，将聚合从 AVG 切换为 MAX，并将时间间隔调整为 1 minute。很快，在 us-east-1 区域约 3 月 7 日的位置出现了一个明显的峰值，约为 68%，而正常峰值约为 57%。平均值之所以掩盖了这个问题，是因为单个主机的间歇性峰值被该区域内五台主机的平均值稀释了。

接下来，将分组从 region 切换为 host，问题就变得清晰了。db-01 明显突出，其峰值达到 65-70%，而其正常基线约为 24%。其他所有主机都保持在预期模式下运行。

将主机名控件设置为仅 db-01，可以隔离该事件。表现为间歇性的 CPU 峰值，而非持续饱和。内存从 85% 上升到 93%，负载从 2.4 上升到 3.0，磁盘从 67% 上升到 73%。四个面板一致验证了一个持续约 4 小时的事件窗口。

为什么使用变量控件来构建查询

使用变量控件构建的仪表板，可以支持在构建时尚不存在的调查路径。如果没有这些控件，每个仪表板都只是构建时选择的一种固定视角。一旦实际问题不符合这个视角，就必须在压力下修改查询或重新构建新的仪表板。而有了控件，面板可以动态适配。

像 ?hostname 和 ?interval 这样的值控件，用于控制筛选内容以及数据粒度。像 ??aggregation 和 ??breakdown 这样的结构控件，用于控制如何聚合以及如何切分数据。多个面板共享同一查询模式，意味着一次修复或改进可以应用到所有地方，而新增一条调查路径只需在控件中增加一个值。它们共同将静态仪表板转变为一个可用于调查的操作界面。

原文：https://www.elastic.co/observability-labs/blog/kibana-dashboard-esql-variable-controls