﻿---
title: ES|QL Query log
description: The ES|QL 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...
url: https://www.elastic.co/elastic/docs-builder/docs/2909/reference/query-languages/esql/esql-query-log
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available
---

# ES|QL Query log
The ES|QL 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  [Elasticsearch server logs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2909/deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels).
These logs can be found in local Elasticsearch service logs directory. Slow log files have a suffix of `_esql_querylog.json`.

## 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

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):
```json
```

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):
```json

{
  "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

Logging slow requests can be resource intensive to your Elasticsearch cluster depending on the qualifying traffic’s volume. For example, emitted logs might increase the index disk usage of your [Elasticsearch monitoring](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2909/deploy-manage/monitor/stack-monitoring) 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):
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:
```json

{
  "transient": {
    "esql.querylog.include.user": true,
    "esql.querylog.threshold.warn": "30s"
  }
}
```