From df8b6911184aeb7e37aed4323db3f555dd6b3177 Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Tue, 15 Jul 2025 12:56:56 +0200 Subject: [PATCH 01/11] Add docs for ES|QL query logs --- docs/reference/query-languages/esql.md | 3 +- .../query-languages/esql/esql-query-log.md | 130 ++++++++++++++++++ .../esql/esql-troubleshooting.md | 9 ++ 3 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 docs/reference/query-languages/esql/esql-query-log.md create mode 100644 docs/reference/query-languages/esql/esql-troubleshooting.md diff --git a/docs/reference/query-languages/esql.md b/docs/reference/query-languages/esql.md index 034794af7d8e9..d66dceb1d36ff 100644 --- a/docs/reference/query-languages/esql.md +++ b/docs/reference/query-languages/esql.md @@ -20,4 +20,5 @@ This reference section provides detailed technical information about {{esql}} fe * [Advanced workflows](esql/esql-advanced.md): Learn how to handle more complex tasks with these guides, including how to extract, transform, and combine data from multiple indices * [Types and fields](esql/esql-types-and-fields.md): Learn about how {{esql}} handles different data types and special fields * [Limitations](esql/limitations.md): Learn about the current limitations of {{esql}} -* [Examples](esql/esql-examples.md): Explore some example queries \ No newline at end of file +* [Examples](esql/esql-examples.md): Explore some example queries +* [Troubleshooting](esql/esql-troubleshooting.md): Learn how to diagnose and resolve issues with {{esql}} diff --git a/docs/reference/query-languages/esql/esql-query-log.md b/docs/reference/query-languages/esql/esql-query-log.md new file mode 100644 index 0000000000000..da55ff8f333b9 --- /dev/null +++ b/docs/reference/query-languages/esql/esql-query-log.md @@ -0,0 +1,130 @@ +--- +navigation_title: "Query Log" +--- + +# {{esql}} Query Log [esql-query-log] + + +Query Log allows to log {{esql}} queries based on their execution time. + +You can use these logs to investigate, analyze or troubleshoot your cluster’s historical ES|QL performance. + +ES|QL query log reports task duration at coordinator level, but might not encompass the full task execution time observed on the client. For example, logs don’t surface HTTP network delays. + +Events that meet the specified threshold are emitted into [{{es}} server logs](docs-content://deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels.md). + +These logs can be found in local {{es}} service logs directory. Slow log files have a suffix of `_esql_querylog.json`. + +## Query log format [query-log-format] + +The following is an example of a successful query event in the query log: + +```js +{ + "@timestamp": "2025-03-11T08:39:50.076Z", + "log.level": "TRACE", + "auth.type": "REALM", + "elasticsearch.querylog.planning.took": 3108666, + "elasticsearch.querylog.planning.took_millis": 3, + "elasticsearch.querylog.query": "from index | limit 100", + "elasticsearch.querylog.search_type": "ESQL", + "elasticsearch.querylog.success": true, + "elasticsearch.querylog.took": 8050416, + "elasticsearch.querylog.took_millis": 8, + "user.name": "elastic-admin", + "user.realm": "default_file", + "ecs.version": "1.2.0", + "service.name": "ES_ECS", + "event.dataset": "elasticsearch.esql_querylog", + "process.thread.name": "elasticsearch[runTask-0][esql_worker][T#12]", + "log.logger": "esql.querylog.query", + "elasticsearch.cluster.uuid": "KZo1V7TcQM-O6fnqMm1t_g", + "elasticsearch.node.id": "uPgRE2TrSfa9IvnUpNT1Uw", + "elasticsearch.node.name": "runTask-0", + "elasticsearch.cluster.name": "runTask" +} +``` + +The following is an example of a failing query event in the query log: + +```js +{ + "@timestamp": "2025-03-11T08:41:54.172Z", + "log.level": "TRACE", + "auth.type": "REALM", + "elasticsearch.querylog.error.message": "line 1:15: mismatched input 'limitxyz' expecting {DEV_CHANGE_POINT, 'enrich', 'dissect', 'eval', 'grok', 'limit', 'sort', 'stats', 'where', DEV_INLINESTATS, DEV_FORK, 'lookup', DEV_JOIN_LEFT, DEV_JOIN_RIGHT, DEV_LOOKUP, 'mv_expand', 'drop', 'keep', DEV_INSIST, 'rename'}", + "elasticsearch.querylog.error.type": "org.elasticsearch.xpack.esql.parser.ParsingException", + "elasticsearch.querylog.query": "from person | limitxyz 100", + "elasticsearch.querylog.search_type": "ESQL", + "elasticsearch.querylog.success": false, + "elasticsearch.querylog.took": 963750, + "elasticsearch.querylog.took_millis": 0, + "user.name": "elastic-admin", + "user.realm": "default_file", + "ecs.version": "1.2.0", + "service.name": "ES_ECS", + "event.dataset": "elasticsearch.esql_querylog", + "process.thread.name": "elasticsearch[runTask-0][search][T#16]", + "log.logger": "esql.querylog.query", + "elasticsearch.cluster.uuid": "KZo1V7TcQM-O6fnqMm1t_g", + "elasticsearch.node.id": "uPgRE2TrSfa9IvnUpNT1Uw", + "elasticsearch.node.name": "runTask-0", + "elasticsearch.cluster.name": "runTask" +} +``` + + +## Enable query logging [enable-query-log] + +You can enable query logging at cluster level. + +By default, all thresholds are set to `-1`, which results in no events being logged. + +Query log thresholds can be enabled for the four logging levels: `trace`, `debug`, `info`, and `warn`. + +To view the current query log settings, use the [get cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-get-settings): + +```console +GET _cluster/settings?filter_path=*.esql.querylog.* +``` + +You can use the `esql.querylog.include.user` setting to append `user.*` and `auth.type` fields to slow log entries. These fields contain information about the user who triggered the request. + +The following snippet adjusts all available ES|QL query log settings [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings): + +```console +PUT /_cluster/settings +{ + "transient": { + "esql.querylog.threshold.warn": "10s", + "esql.querylog.threshold.info": "5s", + "esql.querylog.threshold.debug": "2s", + "esql.querylog.threshold.trace": "500ms", + "esql.querylog.include.user": true + } +} +``` + + + +## Best practices for query logging [troubleshoot-query-log] + +Logging slow requests can be resource intensive to your {{es}} cluster depending on the qualifying traffic’s volume. For example, emitted logs might increase the index disk usage of your [{{es}} monitoring](docs-content://deploy-manage/monitor/stack-monitoring.md) cluster. To reduce the impact of slow logs, consider the following: + +* Set high thresholds to reduce the number of logged events. +* Enable slow logs only when troubleshooting. + +If you aren’t sure how to start investigating traffic issues, consider enabling the `warn` threshold with a high `30s` threshold at the index level using the [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings): + +* Enable for search requests: + + ```console + PUT /_cluster/settings + { + "transient": { + "esql.querylog.include.user": true, + "esql.querylog.threshold.warn": "30s", + } + } + ``` + diff --git a/docs/reference/query-languages/esql/esql-troubleshooting.md b/docs/reference/query-languages/esql/esql-troubleshooting.md new file mode 100644 index 0000000000000..c64053def6f20 --- /dev/null +++ b/docs/reference/query-languages/esql/esql-troubleshooting.md @@ -0,0 +1,9 @@ +--- +navigation_title: "Query Log" +--- + +# Troubleshooting {{esql}} [esql-troubleshooting] + +This section provides some useful resource for troubleshooting {{esql}} + +* [Query log](esql/esql-query-log.md): Learn how to log {{esql}} queries From 3bf73f63d9ebe42565569e5ea58bf4b0c3ec193a Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Tue, 15 Jul 2025 13:02:49 +0200 Subject: [PATCH 02/11] Fix ToC --- docs/reference/query-languages/toc.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/reference/query-languages/toc.yml b/docs/reference/query-languages/toc.yml index 31bead277f05f..6ecc4d08d81b9 100644 --- a/docs/reference/query-languages/toc.yml +++ b/docs/reference/query-languages/toc.yml @@ -119,6 +119,9 @@ toc: - file: esql/limitations.md - file: esql/esql-examples.md + - file: esql/esql-troubleshooting.md + children: + - file: esql/esql-query-log.md - file: sql.md children: - file: sql/sql-spec.md From afc4376ef865b5e86d37d95509441fdc6ce3d839 Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Tue, 15 Jul 2025 13:08:41 +0200 Subject: [PATCH 03/11] Fix link --- docs/reference/query-languages/esql/esql-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/esql/esql-troubleshooting.md b/docs/reference/query-languages/esql/esql-troubleshooting.md index c64053def6f20..5f3baa7c3a41a 100644 --- a/docs/reference/query-languages/esql/esql-troubleshooting.md +++ b/docs/reference/query-languages/esql/esql-troubleshooting.md @@ -6,4 +6,4 @@ navigation_title: "Query Log" This section provides some useful resource for troubleshooting {{esql}} -* [Query log](esql/esql-query-log.md): Learn how to log {{esql}} queries +* [Query log](esql-query-log.md): Learn how to log {{esql}} queries From b347c46cd4c68735cd3f8357bb13f0403f130c60 Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Wed, 16 Jul 2025 09:23:45 +0200 Subject: [PATCH 04/11] Update docs/reference/query-languages/esql/esql-query-log.md Co-authored-by: Liam Thompson --- docs/reference/query-languages/esql/esql-query-log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/esql/esql-query-log.md b/docs/reference/query-languages/esql/esql-query-log.md index da55ff8f333b9..0eb0f4e74076a 100644 --- a/docs/reference/query-languages/esql/esql-query-log.md +++ b/docs/reference/query-languages/esql/esql-query-log.md @@ -1,5 +1,5 @@ --- -navigation_title: "Query Log" +navigation_title: "Query log" --- # {{esql}} Query Log [esql-query-log] From cc117e2ca4b9bd42ee48a6e935a2958c650c1fda Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Wed, 16 Jul 2025 09:23:51 +0200 Subject: [PATCH 05/11] Update docs/reference/query-languages/esql/esql-query-log.md Co-authored-by: Liam Thompson --- docs/reference/query-languages/esql/esql-query-log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/esql/esql-query-log.md b/docs/reference/query-languages/esql/esql-query-log.md index 0eb0f4e74076a..addf05ba7ecdc 100644 --- a/docs/reference/query-languages/esql/esql-query-log.md +++ b/docs/reference/query-languages/esql/esql-query-log.md @@ -5,7 +5,7 @@ navigation_title: "Query log" # {{esql}} Query Log [esql-query-log] -Query Log allows to log {{esql}} queries based on their execution time. +The {{esql}} query log allows to log {{esql}} queries based on their execution time. You can use these logs to investigate, analyze or troubleshoot your cluster’s historical ES|QL performance. From 72344afe7feaf1cb0736ed8995272e76ae983704 Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Wed, 16 Jul 2025 09:23:59 +0200 Subject: [PATCH 06/11] Update docs/reference/query-languages/esql/esql-query-log.md Co-authored-by: Liam Thompson --- docs/reference/query-languages/esql/esql-query-log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/esql/esql-query-log.md b/docs/reference/query-languages/esql/esql-query-log.md index addf05ba7ecdc..06cac551256f7 100644 --- a/docs/reference/query-languages/esql/esql-query-log.md +++ b/docs/reference/query-languages/esql/esql-query-log.md @@ -2,7 +2,7 @@ navigation_title: "Query log" --- -# {{esql}} Query Log [esql-query-log] +# {{esql}} Query log [esql-query-log] The {{esql}} query log allows to log {{esql}} queries based on their execution time. From f67d15ccf3688ff6e36932c11e35a103c08de426 Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Wed, 16 Jul 2025 09:24:09 +0200 Subject: [PATCH 07/11] Update docs/reference/query-languages/esql/esql-query-log.md Co-authored-by: Liam Thompson --- docs/reference/query-languages/esql/esql-query-log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/esql/esql-query-log.md b/docs/reference/query-languages/esql/esql-query-log.md index 06cac551256f7..51ba79da89600 100644 --- a/docs/reference/query-languages/esql/esql-query-log.md +++ b/docs/reference/query-languages/esql/esql-query-log.md @@ -90,7 +90,7 @@ GET _cluster/settings?filter_path=*.esql.querylog.* You can use the `esql.querylog.include.user` setting to append `user.*` and `auth.type` fields to slow log entries. These fields contain information about the user who triggered the request. -The following snippet adjusts all available ES|QL query log settings [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings): +The following snippet adjusts all available {{esql}} query log settings [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings): ```console PUT /_cluster/settings From cfe915a0031869a504d23de37f10b6602e27d10d Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Wed, 16 Jul 2025 09:25:14 +0200 Subject: [PATCH 08/11] Update docs/reference/query-languages/esql/esql-query-log.md Co-authored-by: Liam Thompson --- docs/reference/query-languages/esql/esql-query-log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/esql/esql-query-log.md b/docs/reference/query-languages/esql/esql-query-log.md index 51ba79da89600..6691ffac195d4 100644 --- a/docs/reference/query-languages/esql/esql-query-log.md +++ b/docs/reference/query-languages/esql/esql-query-log.md @@ -123,7 +123,7 @@ If you aren’t sure how to start investigating traffic issues, consider enablin { "transient": { "esql.querylog.include.user": true, - "esql.querylog.threshold.warn": "30s", + "esql.querylog.threshold.warn": "30s" } } ``` From 23c2025f89d34b66ec487dfdf4b2fc283fd933fc Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Wed, 16 Jul 2025 09:25:22 +0200 Subject: [PATCH 09/11] Update docs/reference/query-languages/esql/esql-troubleshooting.md Co-authored-by: Liam Thompson --- docs/reference/query-languages/esql/esql-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/esql/esql-troubleshooting.md b/docs/reference/query-languages/esql/esql-troubleshooting.md index 5f3baa7c3a41a..43768a2facc99 100644 --- a/docs/reference/query-languages/esql/esql-troubleshooting.md +++ b/docs/reference/query-languages/esql/esql-troubleshooting.md @@ -1,5 +1,5 @@ --- -navigation_title: "Query Log" +navigation_title: "Troubleshooting" --- # Troubleshooting {{esql}} [esql-troubleshooting] From bf6a8dbc5b3c68584497494d671ccb595db91bf8 Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Wed, 16 Jul 2025 09:30:48 +0200 Subject: [PATCH 10/11] Better wording --- .../query-languages/esql/esql-query-log.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/reference/query-languages/esql/esql-query-log.md b/docs/reference/query-languages/esql/esql-query-log.md index 6691ffac195d4..963229e9525b4 100644 --- a/docs/reference/query-languages/esql/esql-query-log.md +++ b/docs/reference/query-languages/esql/esql-query-log.md @@ -116,15 +116,15 @@ Logging slow requests can be resource intensive to your {{es}} cluster depending If you aren’t sure how to start investigating traffic issues, consider enabling the `warn` threshold with a high `30s` threshold at the index level using the [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings): -* Enable for search requests: - - ```console - PUT /_cluster/settings - { - "transient": { - "esql.querylog.include.user": true, - "esql.querylog.threshold.warn": "30s" - } - } - ``` +Here is an example of how to change cluster settings to enable query logging at `warn` level, for queries taking more than 30 seconds, and include user information in the logs: + +```console +PUT /_cluster/settings +{ + "transient": { + "esql.querylog.include.user": true, + "esql.querylog.threshold.warn": "30s" + } +} +``` From 06f163f2490b3ccd097e5702b960f328a3708dfb Mon Sep 17 00:00:00 2001 From: Luigi Dell'Aquila Date: Wed, 16 Jul 2025 09:32:35 +0200 Subject: [PATCH 11/11] ES|QL as a md tag --- docs/reference/query-languages/esql/esql-query-log.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/query-languages/esql/esql-query-log.md b/docs/reference/query-languages/esql/esql-query-log.md index 963229e9525b4..05c7f41134a9c 100644 --- a/docs/reference/query-languages/esql/esql-query-log.md +++ b/docs/reference/query-languages/esql/esql-query-log.md @@ -7,9 +7,9 @@ navigation_title: "Query log" The {{esql}} query log allows to log {{esql}} queries based on their execution time. -You can use these logs to investigate, analyze or troubleshoot your cluster’s historical ES|QL performance. +You can use these logs to investigate, analyze or troubleshoot your cluster’s historical {{esql}} performance. -ES|QL query log reports task duration at coordinator level, but might not encompass the full task execution time observed on the client. For example, logs don’t surface HTTP network delays. +{{esql}} query log reports task duration at coordinator level, but might not encompass the full task execution time observed on the client. For example, logs don’t surface HTTP network delays. Events that meet the specified threshold are emitted into [{{es}} server logs](docs-content://deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels.md).