diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index f8d925945401e..28933eb75050d 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -28,7 +28,7 @@ You can pass an `X-Opaque-Id` HTTP header to track the origin of a request in * Response of any request that includes the header * <<_identifying_running_tasks,Task management API>> response -* <<_identifying_search_slow_log_origin,Slow logs>> +* <> * <> For the deprecation logs, {es} also uses the `X-Opaque-Id` value to throttle @@ -52,7 +52,7 @@ safely generate a unique `traceparent` header for each request. If provided, {es} surfaces the header's `trace-id` value as `trace.id` in the: * <> -* <<_identifying_search_slow_log_origin,Slow logs>> +* <> * <> For example, the following `traceparent` value would produce the following diff --git a/docs/reference/how-to/search-speed.asciidoc b/docs/reference/how-to/search-speed.asciidoc index 0ef55d7808873..2db03a19b3532 100644 --- a/docs/reference/how-to/search-speed.asciidoc +++ b/docs/reference/how-to/search-speed.asciidoc @@ -567,3 +567,8 @@ also possible to update the client-side logic in order to route queries to the relevant indices based on filters. However `constant_keyword` makes it transparently and allows to decouple search requests from the index topology in exchange of very little overhead. + +[discrete] +=== Default search timeout + +By default, search requests don't time out. You can set a timeout using the <> setting. diff --git a/docs/reference/index-modules/slowlog.asciidoc b/docs/reference/index-modules/slowlog.asciidoc index c29296b59ad4a..e848668c1a66d 100644 --- a/docs/reference/index-modules/slowlog.asciidoc +++ b/docs/reference/index-modules/slowlog.asciidoc @@ -1,15 +1,118 @@ [[index-modules-slowlog]] -== Slow Log +== Slow log + +The slow log records database searching and indexing events that have execution durations above specified thresholds. You can use these logs to investigate analyze or troubleshoot your cluster's historical search and indexing performance. + +Slow logs report task duration at the shard level for searches, and at the index level +for indexing, but might not encompass the full task execution time observed on the client. For example, slow logs don't surface HTTP network delays or the impact of <>. + +Events that meet the specified threshold are emitted into <> under the `fileset.name` of `slowlog`. These logs can be viewed in the following locations: + +* If <> is enabled, from +{kibana-ref}/xpack-monitoring.html[Stack Monitoring]. Slow log events have a `logger` value of `index.search.slowlog` or `index.indexing.slowlog`. + +* From local {es} service logs directory. Slow log files have a suffix of `_index_search_slowlog.json` or `_index_indexing_slowlog.json`. + +[discrete] +[[slow-log-format]] +=== Slow log format + +The following is an example of a search event in the slow log: + +TIP: If a call was initiated with an `X-Opaque-ID` header, then the ID is automatically included in Search slow logs in the **elasticsearch.slowlog.id** field. See <> for details and best practices. + +[source,js] +--------------------------- +{ + "@timestamp": "2024-12-21T12:42:37.255Z", + "auth.type": "REALM", + "ecs.version": "1.2.0", + "elasticsearch.cluster.name": "distribution_run", + "elasticsearch.cluster.uuid": "Ui23kfF1SHKJwu_hI1iPPQ", + "elasticsearch.node.id": "JK-jn-XpQ3OsDUsq5ZtfGg", + "elasticsearch.node.name": "node-0", + "elasticsearch.slowlog.id": "tomcat-123", + "elasticsearch.slowlog.message": "[index6][0]", + "elasticsearch.slowlog.search_type": "QUERY_THEN_FETCH", + "elasticsearch.slowlog.source": "{\"query\":{\"match_all\":{\"boost\":1.0}}}", + "elasticsearch.slowlog.stats": "[]", + "elasticsearch.slowlog.took": "747.3micros", + "elasticsearch.slowlog.took_millis": 0, + "elasticsearch.slowlog.total_hits": "1 hits", + "elasticsearch.slowlog.total_shards": 1, + "event.dataset": "elasticsearch.index_search_slowlog", + "fileset.name" : "slowlog", + "log.level": "WARN", + "log.logger": "index.search.slowlog.query", + "process.thread.name": "elasticsearch[runTask-0][search][T#5]", + "service.name": "ES_ECS", + "user.name": "elastic", + "user.realm": "reserved" +} + +--------------------------- +// NOTCONSOLE + + +The following is an example of an indexing event in the slow log: + +[source,js] +--------------------------- +{ + "@timestamp" : "2024-12-11T22:34:22.613Z", + "auth.type": "REALM", + "ecs.version": "1.2.0", + "elasticsearch.cluster.name" : "41bd111609d849fc9bf9d25b5df9ce96", + "elasticsearch.cluster.uuid" : "BZTn4I9URXSK26imlia0QA", + "elasticsearch.index.id" : "3VfGR7wRRRKmMCEn7Ii58g", + "elasticsearch.index.name": "my-index-000001", + "elasticsearch.node.id" : "GGiBgg21S3eqPDHzQiCMvQ", + "elasticsearch.node.name" : "instance-0000000001", + "elasticsearch.slowlog.id" : "RCHbt5MBT0oSsCOu54AJ", + "elasticsearch.slowlog.source": "{\"key\":\"value\"}" + "elasticsearch.slowlog.took" : "0.01ms", + "event.dataset": "elasticsearch.index_indexing_slowlog", + "fileset.name" : "slowlog", + "log.level" : "TRACE", + "log.logger" : "index.indexing.slowlog.index", + "service.name" : "ES_ECS", + "user.name": "elastic", + "user.realm": "reserved" +} + +--------------------------- +// NOTCONSOLE + +[discrete] +[[enable-slow-log]] +=== Enable slow logging + +You can enable slow logging at two levels: + +* For all indices under the <>. This method requires a node restart. +* At the index level, using the <> + +By default, all thresholds are set to `-1`, which results in no events being logged. + +Slow log thresholds can be enabled for the four logging levels: `trace`, `debug`, `info`, and `warn`. You can mimic setting log level thresholds by disabling more verbose levels. + +To view the current slow log settings, use the <>: + +[source,console] +-------------------------------------------------- +GET _all/_settings?expand_wildcards=all&filter_path=*.settings.index.*.slowlog +-------------------------------------------------- [discrete] [[search-slow-log]] -=== Search Slow Log +==== Enable slow logging for search events + +Search slow logs emit per shard. They must be enabled separately for the shard's link:https://www.elastic.co/blog/understanding-query-then-fetch-vs-dfs-query-then-fetch[query and fetch search phases]. -Shard level slow search log allows to log slow search (query and fetch -phases) into a dedicated log file. +You can use the `index.search.slowlog.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. -Thresholds can be set for both the query phase of the execution, and -fetch phase, here is a sample: +The following snippet adjusts all available search slow log settings across all indices using the +<>: [source,yaml] -------------------------------------------------- @@ -22,10 +125,11 @@ index.search.slowlog.threshold.fetch.warn: 1s index.search.slowlog.threshold.fetch.info: 800ms index.search.slowlog.threshold.fetch.debug: 500ms index.search.slowlog.threshold.fetch.trace: 200ms + +index.search.slowlog.include.user: true -------------------------------------------------- -All of the above settings are _dynamic_ and can be set for each index using the -<> API. For example: +The following snippet adjusts the same settings for a single index using the <>: [source,console] -------------------------------------------------- @@ -38,138 +142,109 @@ PUT /my-index-000001/_settings "index.search.slowlog.threshold.fetch.warn": "1s", "index.search.slowlog.threshold.fetch.info": "800ms", "index.search.slowlog.threshold.fetch.debug": "500ms", - "index.search.slowlog.threshold.fetch.trace": "200ms" + "index.search.slowlog.threshold.fetch.trace": "200ms", + "index.search.slowlog.include.user": true } -------------------------------------------------- // TEST[setup:my_index] -By default thresholds are disabled (set to `-1`). -The logging is done on the shard level scope, meaning the execution of a -search request within a specific shard. It does not encompass the whole -search request, which can be broadcast to several shards in order to -execute. Some of the benefits of shard level logging is the association -of the actual execution on the specific machine, compared with request -level. +[discrete] +[[index-slow-log]] +==== Enable slow logging for indexing events +Indexing slow logs emit per index document. -The search slow log file is configured in the `log4j2.properties` file. +You can use the `index.indexing.slowlog.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. -[discrete] -==== Identifying search slow log origin +The following snippet adjusts all available indexing slow log settings across all indices using the +<>: -It is often useful to identify what triggered a slow running query. -To include information about the user that triggered a slow search, -use the `index.search.slowlog.include.user` setting. +[source,yaml] +-------------------------------------------------- +index.indexing.slowlog.threshold.index.warn: 10s +index.indexing.slowlog.threshold.index.info: 5s +index.indexing.slowlog.threshold.index.debug: 2s +index.indexing.slowlog.threshold.index.trace: 500ms + +index.indexing.slowlog.source: 1000 +index.indexing.slowlog.reformat: true + +index.indexing.slowlog.include.user: true +-------------------------------------------------- + + +The following snippet adjusts the same settings for a single index using the <>: [source,console] -------------------------------------------------- PUT /my-index-000001/_settings { - "index.search.slowlog.include.user": true + "index.indexing.slowlog.threshold.index.warn": "10s", + "index.indexing.slowlog.threshold.index.info": "5s", + "index.indexing.slowlog.threshold.index.debug": "2s", + "index.indexing.slowlog.threshold.index.trace": "500ms", + "index.indexing.slowlog.source": "1000", + "index.indexing.slowlog.reformat": true, + "index.indexing.slowlog.include.user": true } -------------------------------------------------- // TEST[setup:my_index] -This will result in user information being included in the slow log. +[discrete] +===== Logging the `_source` field -[source,js] ---------------------------- -{ - "@timestamp": "2024-02-21T12:42:37.255Z", - "log.level": "WARN", - "auth.type": "REALM", - "elasticsearch.slowlog.id": "tomcat-123", - "elasticsearch.slowlog.message": "[index6][0]", - "elasticsearch.slowlog.search_type": "QUERY_THEN_FETCH", - "elasticsearch.slowlog.source": "{\"query\":{\"match_all\":{\"boost\":1.0}}}", - "elasticsearch.slowlog.stats": "[]", - "elasticsearch.slowlog.took": "747.3micros", - "elasticsearch.slowlog.took_millis": 0, - "elasticsearch.slowlog.total_hits": "1 hits", - "elasticsearch.slowlog.total_shards": 1, - "user.name": "elastic", - "user.realm": "reserved", - "ecs.version": "1.2.0", - "service.name": "ES_ECS", - "event.dataset": "elasticsearch.index_search_slowlog", - "process.thread.name": "elasticsearch[runTask-0][search][T#5]", - "log.logger": "index.search.slowlog.query", - "elasticsearch.cluster.uuid": "Ui23kfF1SHKJwu_hI1iPPQ", - "elasticsearch.node.id": "JK-jn-XpQ3OsDUsq5ZtfGg", - "elasticsearch.node.name": "node-0", - "elasticsearch.cluster.name": "distribution_run" -} +By default, {es} logs the first 1000 characters of the `_source` in the slow log. You can adjust how `_source` is logged using the `index.indexing.slowlog.source` setting. Set `index.indexing.slowlog.source` to `false` or `0` to skip logging the source entirely. Set `index.indexing.slowlog.source` to `true` to log the entire source regardless of size. ---------------------------- -// NOTCONSOLE +The original `_source` is reformatted by default to make sure that it fits on a single log line. If preserving the original document format is important, then you can turn off reformatting by setting `index.indexing.slowlog.reformat` to `false`. This causes source to be logged with the original formatting intact, potentially spanning multiple log lines. -If a call was initiated with an `X-Opaque-ID` header, then the ID is included -in Search Slow logs in the **elasticsearch.slowlog.id** field. See -<> for details and best practices. +[discrete] +[[slow-log-fields]] [discrete] -[[index-slow-log]] -=== Index Slow log +[[troubleshoot-slow-log]] +=== Best practices for slow logging -The indexing slow log, similar in functionality to the search slow -log. The log file name ends with `_index_indexing_slowlog.json`. Log and -the thresholds are configured in the same way as the search slowlog. -Index slowlog sample: +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 <> cluster. To reduce the impact of slow logs, consider the following: -[source,yaml] --------------------------------------------------- -index.indexing.slowlog.threshold.index.warn: 10s -index.indexing.slowlog.threshold.index.info: 5s -index.indexing.slowlog.threshold.index.debug: 2s -index.indexing.slowlog.threshold.index.trace: 500ms -index.indexing.slowlog.source: 1000 --------------------------------------------------- +* Enable slow logs against specific indices rather than across all indices. +* Set high thresholds to reduce the number of logged events. +* Enable slow logs only when troubleshooting. -All of the above settings are _dynamic_ and can be set for each index using the -<> API. For example: +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 <>: +* Enable for search requests: ++ [source,console] -------------------------------------------------- -PUT /my-index-000001/_settings +PUT /*/_settings { - "index.indexing.slowlog.threshold.index.warn": "10s", - "index.indexing.slowlog.threshold.index.info": "5s", - "index.indexing.slowlog.threshold.index.debug": "2s", - "index.indexing.slowlog.threshold.index.trace": "500ms", - "index.indexing.slowlog.source": "1000" + "index.search.slowlog.include.user": true, + "index.search.slowlog.threshold.fetch.warn": "30s", + "index.search.slowlog.threshold.query.warn": "30s" } -------------------------------------------------- // TEST[setup:my_index] -To include information about the user that triggered a slow indexing event, -use the `index.indexing.slowlog.include.user` setting. - +* Enable for indexing requests: ++ [source,console] -------------------------------------------------- -PUT /my-index-000001/_settings +PUT /*/_settings { - "index.indexing.slowlog.include.user": true + "index.indexing.slowlog.include.user": true, + "index.indexing.slowlog.threshold.index.warn": "30s" } -------------------------------------------------- // TEST[setup:my_index] -By default Elasticsearch will log the first 1000 characters of the _source in -the slowlog. You can change that with `index.indexing.slowlog.source`. Setting -it to `false` or `0` will skip logging the source entirely, while setting it to -`true` will log the entire source regardless of size. The original `_source` is -reformatted by default to make sure that it fits on a single log line. If preserving -the original document format is important, you can turn off reformatting by setting -`index.indexing.slowlog.reformat` to `false`, which will cause the source to be -logged "as is" and can potentially span multiple log lines. +Slow log thresholds being met does not guarantee cluster performance issues. In the event that symptoms are noticed, slow logs can provide helpful data to diagnose upstream traffic patterns or sources to resolve client-side issues. For example, you can use data included in `X-Opaque-ID`, the `_source` request body, or `user.*` fields to identify the source of your issue. This is similar to troubleshooting <>. + +If you're experiencing search performance issues, then you might also consider investigating searches flagged for their query durations using the <>. You can then use the profiled query to investigate optimization options using the link:{kibana-ref}/xpack-profiler.html[query profiler]. This type of investigation should usually take place in a non-production environment. -The index slow log file is configured in the `log4j2.properties` file. +Slow logging checks each event against the reporting threshold when the event is complete. This means that it can't report if events trigger <>. If suspect circuit breaker errors, then you should also consider enabling <>, which logs events before they are executed. [discrete] -=== Slow log levels +=== Learn more -You can mimic the search or indexing slow log level by setting appropriate -threshold making "more verbose" loggers to be switched off. -If for instance we want to simulate `index.indexing.slowlog.level: INFO` -then all we need to do is to set -`index.indexing.slowlog.threshold.index.debug` and `index.indexing.slowlog.threshold.index.trace` to `-1`. +To learn about other ways to optimize your search and indexing requests, refer to <> and <>. \ No newline at end of file