Skip to content

Commit 72c595f

Browse files
luigidellaquilaluigidellaquila
committed
Add docs for ES|QL Query Log
1 parent 061576f commit 72c595f

File tree

2 files changed

+142
-0
lines changed

2 files changed

+142
-0
lines changed

‎explore-analyze/query-filter/languages/esql-query-log.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
applies_to:
3+
stack: ga
4+
serverless: ga
5+
navigation_title: "Query log"
6+
mapped_pages:
7+
- https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-query-log.html
8+
---
9+
10+
11+
12+
# ES|QL query log [esql-query-log]
13+
14+
15+
Query Log allows to log ES|QL queries based on their execution time.
16+
You can use these logs to investigate, analyze or troubleshoot your cluster’s historical ES|QL performance.
17+
18+
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.
19+
20+
Events that meet the specified threshold are emitted into [{{es}} logging](docs-content://deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels.md).
21+
22+
These logs can be viewed in the following locations:
23+
24+
* If [{{es}} monitoring](docs-content://deploy-manage/monitor/stack-monitoring.md) is enabled, from [Stack Monitoring](docs-content://deploy-manage/monitor/monitoring-data/visualizing-monitoring-data.md). Query log events have a `logger` value of `esql.querylog`.
25+
* From local {{es}} service logs directory. Slow log files have a suffix of `_esql_querylog.json`.
26+
27+
28+
## Query log format [query-log-format]
29+
30+
The following is an example of a successful query event in the query log:
31+
32+
```js
33+
{
34+
"@timestamp": "2025-03-11T08:39:50.076Z",
35+
"log.level": "TRACE",
36+
"auth.type": "REALM",
37+
"elasticsearch.querylog.planning.took": 3108666,
38+
"elasticsearch.querylog.planning.took_millis": 3,
39+
"elasticsearch.querylog.query": "from index | limit 100",
40+
"elasticsearch.querylog.search_type": "ESQL",
41+
"elasticsearch.querylog.success": true,
42+
"elasticsearch.querylog.took": 8050416,
43+
"elasticsearch.querylog.took_millis": 8,
44+
"user.name": "elastic-admin",
45+
"user.realm": "default_file",
46+
"ecs.version": "1.2.0",
47+
"service.name": "ES_ECS",
48+
"event.dataset": "elasticsearch.esql_querylog",
49+
"process.thread.name": "elasticsearch[runTask-0][esql_worker][T#12]",
50+
"log.logger": "esql.querylog.query",
51+
"elasticsearch.cluster.uuid": "KZo1V7TcQM-O6fnqMm1t_g",
52+
"elasticsearch.node.id": "uPgRE2TrSfa9IvnUpNT1Uw",
53+
"elasticsearch.node.name": "runTask-0",
54+
"elasticsearch.cluster.name": "runTask"
55+
}
56+
```
57+
58+
The following is an example of a failing query event in the query log:
59+
60+
```js
61+
{
62+
"@timestamp": "2025-03-11T08:41:54.172Z",
63+
"log.level": "TRACE",
64+
"auth.type": "REALM",
65+
"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'}",
66+
"elasticsearch.querylog.error.type": "org.elasticsearch.xpack.esql.parser.ParsingException",
67+
"elasticsearch.querylog.query": "from person | limitxyz 100",
68+
"elasticsearch.querylog.search_type": "ESQL",
69+
"elasticsearch.querylog.success": false,
70+
"elasticsearch.querylog.took": 963750,
71+
"elasticsearch.querylog.took_millis": 0,
72+
"user.name": "elastic-admin",
73+
"user.realm": "default_file",
74+
"ecs.version": "1.2.0",
75+
"service.name": "ES_ECS",
76+
"event.dataset": "elasticsearch.esql_querylog",
77+
"process.thread.name": "elasticsearch[runTask-0][search][T#16]",
78+
"log.logger": "esql.querylog.query",
79+
"elasticsearch.cluster.uuid": "KZo1V7TcQM-O6fnqMm1t_g",
80+
"elasticsearch.node.id": "uPgRE2TrSfa9IvnUpNT1Uw",
81+
"elasticsearch.node.name": "runTask-0",
82+
"elasticsearch.cluster.name": "runTask"
83+
}
84+
```
85+
86+
87+
## Enable query logging [enable-query-log]
88+
89+
You can enable query logging at cluster level.
90+
91+
By default, all thresholds are set to `-1`, which results in no events being logged.
92+
93+
Query log thresholds can be enabled for the four logging levels: `trace`, `debug`, `info`, and `warn`.
94+
95+
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):
96+
97+
```console
98+
GET _cluster/settings?filter_path=*.esql.querylog.*
99+
```
100+
101+
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.
102+
103+
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):
104+
105+
```console
106+
PUT /_cluster/settings
107+
{
108+
"transient": {
109+
"esql.querylog.threshold.warn": "10s",
110+
"esql.querylog.threshold.info": "5s",
111+
"esql.querylog.threshold.debug": "2s",
112+
"esql.querylog.threshold.trace": "500ms",
113+
"esql.querylog.include.user": true
114+
}
115+
}
116+
```
117+
118+
119+
120+
## Best practices for query logging [troubleshoot-query-log]
121+
122+
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:
123+
124+
* Set high thresholds to reduce the number of logged events.
125+
* Enable slow logs only when troubleshooting.
126+
127+
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):
128+
129+
* Enable for search requests:
130+
131+
```console
132+
PUT /_cluster/settings
133+
{
134+
"transient": {
135+
"esql.querylog.include.user": true,
136+
"esql.querylog.threshold.warn": "30s",
137+
}
138+
}
139+
```
140+
141+

‎explore-analyze/query-filter/languages/esql.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ Find more details about {{esql}} in the following documentation pages:
5151
- [Using {{esql}} in {{elastic-sec}}](/explore-analyze/query-filter/languages/esql-elastic-security.md).
5252
- [Using {{esql}} across clusters](/explore-analyze/query-filter/languages/esql-cross-clusters.md).
5353
- [Task management](/explore-analyze/query-filter/languages/esql-task-management.md).
54+
- [Query log](/explore-analyze/query-filter/languages/esql-query-log.md).
5455

5556
- [Limitations](elasticsearch://reference/query-languages/esql/limitations.md): The current limitations of {{esql}}.
5657

0 commit comments

Comments
 (0)