Elasticsearch 查询日志：每个查询一行协调器级别日志，适用于 ES|QL、DSL、SQL 和 EQL

作者来自 Elastic Najwa Harif 及 Valentin Crettaz通过 Elasticsearch 查询日志可以轻松理解查询对集群性能的影响。每个请求由一条协调器级别日志记录覆盖 ES|QL、DSL、SQL 和 EQL并提供完整的查询文本、追踪信息、可选用户上下文以及 CCS 提示。测试 Elastic 的前沿开箱即用能力。深入 Elasticsearch Labs 仓库中的示例 notebooks开始免费云试用或立即在本地机器上体验 Elastic。你的 dashboard 超时并且 CPU 飙升但到底是哪条查询在执行slow logs 每个 shard 只提供一行Elasticsearch 查询日志则是每个请求一条 JSON 日志行其端到端耗时与 API 中你已经信任的 took在查询返回内容中的 took 字段 相同。这一条日志还会捕获完整查询文本适用于 ES|QL、DSL、SQL 和 EQL、执行结果、追踪信息、可选用户上下文以及在相关情况下的跨集群CCS提示。这些日志遵循 ECS 规范可以直接在 Discover 中使用并且在开箱即用的 dashboard 中可直接可视化只要你写入日志即可无需自定义 schema 项目。下面内容将介绍我们为什么构建它、它与 slow logs 的区别、每一行包含的信息以及如何启用它。为什么我们要构建这个你们问得很多协调器级别的查询日志一直是一个非常高频的需求我们倾听了这些反馈并最终交付了它同样的问题不断出现你希望在服务等级目标SLO和仪表盘中看到响应时长你希望了解集群中查询执行的耗时你还希望能够看到完整的查询内容。在使用跨集群搜索cross-cluster search时一个跨多个集群扩展的搜索在应用或 Kibana 视角下看起来像一次操作但在运维层面它实际上是一条工作链协调、远程执行、合并、超时处理以及部分结果返回。当出现慢查询或不稳定情况时团队不仅需要知道请求总耗时还需要知道哪些集群参与了执行以及最终结果是成功、部分成功还是完全失败。你将获得的是一条日志流、每个查询一条记录每条记录都包含协调器耗时即与搜索 API 响应一致的 took 时间、成功或失败状态以及完整查询文本。该日志符合 Elastic Common SchemaECS支持可选的延迟阈值与用户/审计字段同时包含 X-Opaque-Id可以将热点查询追溯到其来源的 saved object并通过 trace ID 与 Kibana 或你自己的工具进行关联。更重要的是这些日志遵循稳定的 ECS 对齐 schema这意味着你不需要设计自己的数据接入 pipeline 或字段映射。这种一致性使得开箱即用的 dashboard 和分析能力可以在日志写入后立即生效。Slow logs vs. query logs30 秒版本slow logs 多年来一直是常用工具。它们可以告诉你哪个搜索操作变慢了但它们是以 shard 为单位输出日志 ——每个 shard 只会产生一行且每一行只反映该 shard 执行的一部分工作。这意味着它们无法提供一个从客户端视角出发的、描述整个查询执行耗时的单一记录。query logs 则正好相反每个查询只输出一行并提供端到端wall clock耗时这个时间与 search API 响应中的 took 时间一致。这使得它们更适合理解工作负载模式以及快速定位问题查询。slow logs 和 query logs 在触发时机与覆盖范围上也不同。slow logs 只有在 shard 执行超过阈值时才会写入也就是说它们主要用于“发现异常慢的 shard 工作”。query logs 可以记录所有查询或仅记录超过你在集群级别配置的阈值的查询因此你可以根据分析或排障需求调节日志量。slow logs 仅支持 DSL 查询而 query logs 覆盖ES|QL、DSL、SQL和EQL这更符合现代技术栈中 “这个集群到底执行了什么” 的分析方式。两者在 header 关联、trace 和审计信息方面提供相同能力当你开启用户上下文时。下面的表格总结了传统 slow logs 与新的 query logs 功能之间的主要差异。Slow logs vs. Query logs对比项Slow logsQuery logs用途用于定位 “热点 shard” 或慢索引操作以及在单集群内进行传统性能调优用于理解“执行了什么查询”、端到端耗时协调器视角、执行是否成功更适合 SLO、分析与故障排查粒度按 shard以及 phase记录一次用户查询可能在多个 shard / replica 上产生多条日志按协调器级别查询记录一个查询对应一条日志事件覆盖范围查询 索引仅查询索引日志未来才会支持可获得的信息“这个 index 上的这个 shard 在 query/fetch 阶段超过 N ms”“这条查询完整文本、耗时、结果状态以及在相关情况下跨集群/联邦查询汇总信息”支持的查询类型仅 DSLES阈值模型通常是分层阈值多个时间档位、按 index 配置集群级单一时间阈值例如≥ 500ms 记录日志每条日志里包含什么每一条日志都是一个 JSON 对象对应一个请求存放在独立文件中例如 Elasticsearch 日志目录下的*_querylog.json。下面是你可以从这些数据中获得的信息是否成功、耗时多少、哪里出错包含执行结果是否成功、耗时took / took_millis与 API 返回一致以及发生错误或超时时的清晰失败信息。这是用于告警、SLO 和仪表盘的核心信号“系统是否正常如果不正常原因是什么”同时还会提供返回的行数或命中数result_count用于区分“慢但结果很少”“慢且返回量很大”实际执行了什么查询包含查询类型esql、dsl、sql、eql以及完整查询文本。这可以回答问题哪个 dashboard 规则 / saved search / 客户端请求在持续压系统结合耗时和结果状态可以快速定位最 “昂贵” 的查询进行优化或限流。谁发起的请求如何端到端追踪通过X-Opaque-Id和trace ID可以将日志关联回 Kibana 或自定义请求头。task和可选的parent task ID可以追踪异步或嵌套执行链路。跨集群搜索CCS谁参与了有没有异常在启用跨集群搜索时日志可以包含远程集群别名每个集群的耗时执行状态成功 / 失败 / 部分成功 / 跳过你可以快速判断慢是本地问题还是远端集群拖慢了整体响应DSL 可以记录是否来自 remote aliasES|QL 提供更丰富的 cluster mapEQL 在涉及远端时提供更轻量视图例如涉及哪些 remote 以及数量安全信息可选当开启elasticsearch.querylog.include.user时可以获得用户身份信息realm 信息run-as 情况下的 effective userAPI key 元数据结合查询文本和耗时可以用于治理和容量分析不仅看 IP也看“谁在用”。还有更多信息此外还可能包含更细粒度的执行细节shard 级别结果可选 profiling 信息取决于查询类型完整字段与配置请参考 Elasticsearch 官方 query logs 文档。日志存放位置以及如何使用日志会以*_querylog.json的形式写入 Elasticsearch 的日志目录中例如mycluster_querylog.json位于协调节点coordinating node上。你可以通过 Filebeat Elasticsearch 模块中的querylogfileset 来采集这些日志然后在 Discover 中查看通过event.dataset: elasticsearch.querylog过滤。在 Elastic Cloud 上你需要先为 deployment 启用 Logs一旦开启query logs 就会自动开始收集与传输。两种使用方式如果你只是想做一次性排查例如谁在 “打爆” 集群当前查询类型分布是什么做一次快速审计可以直接开启日志设置一个 duration 阈值例如 ≥ 1 秒或 ≥ 5 分钟只记录有意义的慢查询用完后关闭即可。如果你需要持续性的查询分析只需启用 logging用 Filebeat 采集日志在监控集群上打开 dashboard非常简单的两步启用 采集就完成了。每条请求一行每条请求一个耗时无需任何自定义 pipeline。Dashboard 概览下面的 dashboard 基于新的 query logs 开箱即用。在顶部一行你可以看到P95 / P99 查询延迟以及可选的 “可接受延迟” 参考线查询类型分布成功 / 失败比例用户查询 vs 系统查询比例针对 DSLhits 与 aggregations 的比例在下方你可以看到延迟随时间变化avg、p50、p95、p99、max并带有参考线用于识别回归查询量随时间变化按类型分层Top indices、Top users、Top error types 表格通过 cluster、user 或 index 过滤器你可以精确聚焦到你关心的范围。提醒一下查询日志是异步的因此不会阻塞查询执行。你可以使用 duration 阈值来控制日志量。另外需要注意在非常高的 QPS每秒查询数情况下我们可能会丢弃部分日志记录而不是让集群性能受到影响。对于分析用途建议将日志发送到独立的监控集群这样可以避免正在排障的集群承担额外负载。一些配置与代码示例查询日志默认是关闭的。你可以在elasticsearch.yml中开启或者通过 cluster settings API 开启。方法如下启用查询日志在elasticsearch.yml中elasticsearch.querylog.enabled: true或者通过集群设置 API 动态开启PUT _cluster/settings { persistent: { elasticsearch.querylog.enabled: true } }仅记录超过持续时间阈值的查询如果你不希望记录每一个健康检查或极小请求只需设置一个阈值让系统仅在查询执行时间达到或超过该阈值时才写入日志。duration 的单位是时间单位PUT _cluster/settings { persistent: { elasticsearch.querylog.enabled: true, elasticsearch.querylog.threshold: 1s } }包含用户 / 审计信息如果你使用 Security 插件并且希望查看每条查询是由谁执行的PUT _cluster/settings { persistent: { elasticsearch.querylog.enabled: true, elasticsearch.querylog.include.user: true } }记录仅命中系统索引的 DSL 查询默认情况下只针对系统索引system indices的搜索不会被记录。如果你希望将这些查询也纳入日志需要启用 query logging并设置PUT _cluster/settings { persistent: { elasticsearch.querylog.enabled: true, elasticsearch.querylog.include.system_indices: true } }示例日志条目一行 一个 JSON 对象 一个请求对 ES|QL、DSL、SQL、EQL 都具有相同结构。下面分别展示一个成功的 DSL 查询和一个失败的 EQL 查询包括时间戳、耗时、查询类型和完整查询内容。成功时会包含结果数量和 shard 统计信息失败时会包含错误信息块。当你启用相关配置后还会包含用户信息和 X-Opaque-Id。成功DSL 查询{ timestamp: 2026-03-04T19:40:34.736Z, log: { level: INFO, logger: elasticsearch.querylog }, event: { duration: 1000000, outcome: success }, elasticsearch: { querylog: { type: dsl, query: {\size\:10,\query\:{\match_all\:{\boost\:1.0}}}, indices: [query_log_test_index], result_count: 3, search: { total_count: 3 }, shards: { successful: 1 }, took: 1000000, took_millis: 1 }, node: { name: node-1 }, cluster: { name: my-es-cluster } }, http: { request: { headers: { x_opaque_id: opaque-1772653234 } } }, user: { name: elastic, realm: reserved } }失败EQL 查询{ timestamp: 2026-03-04T19:40:35.271Z, log: { level: INFO, logger: elasticsearch.querylog }, event: { duration: 1326334, outcome: failure }, elasticsearch: { querylog: { type: eql, query: any where true, indices: [nonexistent_index_xyz], result_count: 0, took_millis: 1 }, node: { name: node-1 }, cluster: { name: my-es-cluster } }, error: { type: org.elasticsearch.index.IndexNotFoundException, message: no such index [Unknown index [nonexistent_index_xyz]] } }总结Elasticsearch 查询日志为每个查询提供一条协调器级别日志覆盖 ES|QL、DSL、SQL、EQL。每个请求一行包含协调器耗时、完整查询内容以及可选的用户信息和 X-Opaque-Id。启用后你可以设置持续时间阈值以及用户信息采集如需要即可完成配置。日志存储在日志目录中*_querylog.json通过 Filebeat 采集后可以在 Discover 中通过elasticsearch.querylog数据集查看。完整配置项和字段说明请参考 Elasticsearch 查询日志官方文档。慢查询或异常查询也可以在 AutoOps 中查看它利用 X-Opaque-Id 将长耗时搜索追溯到其来源例如 dashboard、saved search 或告警规则。最后需要注意的是这个新的查询日志是 9.2 版本中仅支持 ES|QL 的查询日志的演进版本。我们建议使用新的查询日志因为它不仅支持 ES|QL还支持所有其他查询类型。现在可以去看看你的集群里到底在运行什么查询了。原文https://www.elastic.co/search-labs/blog/elasticsearch-query-logs