diff --git a/explore-analyze/query-filter/languages/esql-query-log.md b/explore-analyze/query-filter/languages/esql-query-log.md new file mode 100644 index 000000000..5882ac699 --- /dev/null +++ b/explore-analyze/query-filter/languages/esql-query-log.md @@ -0,0 +1,141 @@ +--- +applies_to: + stack: ga + serverless: ga +navigation_title: "Query log" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-query-log.html +--- + + + +# ES|QL query log [esql-query-log] + + +Query Log allows to log ES|QL 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}} logging](../../../deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels.md). + +These logs can be viewed in the following locations: + +* If [{{es}} monitoring](../../../deploy-manage/monitor/stack-monitoring.md) is enabled, from [Stack Monitoring](../../../deploy-manage/monitor/monitoring-data/visualizing-monitoring-data.md). Query log events have a `logger` value of `esql.querylog`. +* From 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](../../../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/explore-analyze/query-filter/languages/esql.md b/explore-analyze/query-filter/languages/esql.md index 974f58528..e0bfca510 100644 --- a/explore-analyze/query-filter/languages/esql.md +++ b/explore-analyze/query-filter/languages/esql.md @@ -51,6 +51,7 @@ Find more details about {{esql}} in the following documentation pages: - [Using {{esql}} in {{elastic-sec}}](/explore-analyze/query-filter/languages/esql-elastic-security.md). - [Using {{esql}} across clusters](/explore-analyze/query-filter/languages/esql-cross-clusters.md). - [Task management](/explore-analyze/query-filter/languages/esql-task-management.md). + - [Query log](/explore-analyze/query-filter/languages/esql-query-log.md). - [Limitations](elasticsearch://reference/query-languages/esql/limitations.md): The current limitations of {{esql}}. diff --git a/explore-analyze/toc.yml b/explore-analyze/toc.yml index 2c3e9340f..afe738311 100644 --- a/explore-analyze/toc.yml +++ b/explore-analyze/toc.yml @@ -15,6 +15,7 @@ toc: - file: query-filter/languages/esql-multi-index.md - file: query-filter/languages/esql-cross-clusters.md - file: query-filter/languages/esql-task-management.md + - file: query-filter/languages/esql-query-log.md - file: query-filter/languages/esql-examples.md - file: query-filter/languages/sql.md children: