ES|QL 热力来袭：通过 Elasticsearch 插件将其引入 Grafana 仪表盘

ES|QL 热力来袭：通过 Elasticsearch 插件将其引入 Grafana 仪表盘

Elasticsearch 数据源是 Grafana 生态系统中最受欢迎的插件之一，现在它已支持 ES|QL 作为实验性功能，从 Grafana 13.0 版本开始可用。ES|QL 是 Elasticsearch 现代的基于管道的查询语言，它能够查询日志、指标和追踪数据，并允许直接从 Grafana 查询编辑器将 Elasticsearch 用作原生的 Prometheus PromQL 数据源。这项集成由 Elastic 与 Grafana Labs 合作构建，并贡献给 Grafana 开源项目，通过一个简单的功能标志 (elasticsearchESQLQuery = true) 即可启用，它将解锁一个由 Monaco 提供支持的编辑器，具备语法高亮、自动补全和内联错误消息功能。我们将逐步介绍如何启用它，并编写您的第一个用于日志分析、时间序列可视化和指标聚合的查询。

背景

Elasticsearch 是与 Grafana UI 配合使用的顶级插件之一。到目前为止，Elasticsearch 插件仅支持 Lucene 和原始的 Query DSL 进行查询。ES|QL 是 Elastic 现代的基于管道的查询语言，专为日志、指标和追踪数据的分析而设计。与 Query DSL 或 Lucene 相比，其直观的语法使得过滤、聚合和转换数据变得更加容易。

自 2024 年以来，社区一直在追踪此项请求：grafana/grafana#81765。

如何在 Grafana 中启用 ES|QL 支持

此功能通过 elasticsearchESQLQuery 功能标志控制。要开启它，请在您的 grafana.ini 文件中添加以下内容：

[feature_toggles]
elasticsearchESQLQuery = true

保存后请重启 Grafana。此功能从 Grafana 13.0 版本开始可用。

Grafana 查询编辑器中的 ES|QL

启用该标志后，Elasticsearch 查询编辑器将获得一个查询语言选择器。您可以在同一个编辑器面板中切换 Lucene、Raw DSL 和 ES|QL。

当您选择 ES|QL 时，编辑器会切换到一个由 Monaco 提供支持的代码编辑器，这与 VS Code 使用的引擎相同。您可以立即获得语法高亮、错误高亮和基本的自动补全功能。

智能索引预填充功能使得入门变得快速：如果在数据源设置中配置了索引模式，首次点击 ES|QL 编辑器时会自动插入 FROM <index>。您可以自由更改或删除它。如果没有配置索引，FROM 子句将留空。

运行您的第一个查询

按严重性统计日志条目

这是一个很好的入门查询，可以确认 ES|QL 是否正常工作并熟悉其语法。

FROM logs*
| STATS count = COUNT(*) BY log.level
| SORT count DESC

在 Raw Data 面板类型中运行它，您将看到一个按日志级别统计数量的表格：

浏览最新错误

WHERE、KEEP、SORT 和 LIMIT 命令使得精确筛选您关心的字段和行变得轻而易举。

FROM logs*
| WHERE log.level == "ERROR"
| KEEP @timestamp, message, host.name
| SORT @timestamp DESC
| LIMIT 20

按时间统计日志量

使用 BUCKET 将日志计数按小时间隔分组。这与 Metrics 面板类型配合得很好，后者可以将其渲染为时间序列图。

FROM logs*
| STATS count = COUNT(*) BY bucket = BUCKET(@timestamp, 1 hour)
| SORT bucket ASC

按日志活动统计热门主机

识别最活跃的主机是常见的运维任务。使用 STATS 结合 BY 和 LIMIT 可以简洁地实现。

FROM logs*
| STATS log_count = COUNT(*) BY host.name
| SORT log_count DESC
| LIMIT 10

用于时间序列指标的 TS 命令

对于 时间序列数据流 (TSDS) 中的指标数据，ES|QL 中的 TS 源命令支持指标分析和时间序列聚合。

例如：

• RATE(): 随时间的变化率
• AVG_OVER_TIME(): 滑动窗口内的平均值
• INCREASE(): 一段时间内的总增长量
• DELTA(): 第一个值和最后一个值之间的差值
• LAST_OVER_TIME(): 窗口内最新值

其模式遵循两级聚合：一个应用于每个独立时间序列的内部函数，然后是一个跨组（例如，按主机或按服务）进行聚合的外部函数。

TS metrics*
| STATS SUM(RATE(metrics.system.cpu.time)) BY TBUCKET(10 m)

您还可以使用 AVG_OVER_TIME() 计算指标在滑动窗口内的平均值，然后按主机和 10 分钟桶来分割结果：

TS metrics*
| STATS MAX(AVG_OVER_TIME(metrics.system.memory.utilization)) BY host.name,TBUCKET(10m)

TS 命令还会通过 ES|QL 向量化计算引擎运行查询。内部基准测试显示，对于 TSDS 支持的数据，与等效的 Query DSL 查询相比，性能提升了一个数量级或更多。

参考：

• TS 命令文档
• 时间序列聚合函数

内联错误消息

ES|QL 查询通过 Elasticsearch 上的 /_query HTTP 端点 运行。如果您的查询存在语法错误或引用了不存在的字段，Elasticsearch 会返回结构化的错误响应。插件会将此信息直接呈现在查询编辑器中作为内联消息，因此您可以在 Grafana UI 中准确看到哪里出了问题。

在上面的示例中，host.nam 缺少了最后的 e。Elasticsearch 会将其捕获为验证异常，并返回无法解析的字段名称。该消息会以内联形式出现在查询编辑器下方。

技术细节

在底层，该插件对 ES|QL 和其他查询类型采用不同的代码路径处理。ES|QL 查询发送到 /_query 端点，Content-Type: application/json。Lucene 和 Query DSL 查询则继续使用 /_msearch，Content-Type: application/x-ndjson。

这种分离是刻意为之的：/_query 返回不同的响应结构，插件在将数据传递给 Grafana 面板之前会独立解析它。

立即试用！

这也意味着现在是尝试并提供反馈的好时机。

上游 PR 和 原始追踪问题 都是公开的。如果您遇到问题或有任何请求，欢迎在这两个地方发表评论。

后续步骤

• 在您的 Grafana 13.0 实例中启用此功能，设置 elasticsearchESQLQuery = true。
• 针对您自己的索引尝试上述示例查询。
• 对于指标数据，请在 Elasticsearch 9.2 或 Serverless 数据源上试用 ES|QL 的 TS 命令。
• 阅读完整的 ES|QL 概述 以探索该语言的其他功能。