github-mirrors/elasticsearch
1
0
Fork 0
mirror of https://github.com/elastic/elasticsearch.git synced 2025-06-28 17:34:17 -04:00
Code Issues Projects Releases Packages Wiki Activity

EQL: [Docs] Add documentation for the CircuitBreaker (#74897)

Browse source 
Add documentation for the newly introduced CircuitBreaker, which is
used to restrict the memory usage for an EQL sequence query to avoid
OutOfMemory exceptions.

Follows: #74381
This commit is contained in:
Marios Trivyzas 2021-07-07 09:20:25 +02:00 • committed by GitHub
parent d3eb540fe4
commit dd302dcfef
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 40 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/reference/eql/eql-search-api.asciidoc
View file

@ -293,6 +293,7 @@ change the sort order of hits in the response.
include::{es-repo-dir}/search/search.asciidoc[tag=runtime-mappings-def] include::{es-repo-dir}/search/search.asciidoc[tag=runtime-mappings-def]
[[eql-search-api-params-size]]
`size`:: `size`::
(Optional, integer or float) (Optional, integer or float)
For <<eql-basic-syntax,basic queries>>, the maximum number of matching events to For <<eql-basic-syntax,basic queries>>, the maximum number of matching events to

39
docs/reference/eql/eql.asciidoc
View file

@ -792,6 +792,45 @@ results by using <<get-async-eql-status-api,get async EQL status API>>.
You can also manually delete saved synchronous searches using the You can also manually delete saved synchronous searches using the
<<delete-async-eql-search-api,delete async EQL search API>>. <<delete-async-eql-search-api,delete async EQL search API>>.
[discrete]
[[eql-circuit-breaker]]
=== EQL circuit breaker settings
When a <<eql-sequences, sequence>> query is executed, the node handling the query
needs to keep some structures in memory, which are needed by the algorithm
implementing the sequence matching. When large amounts of data need to be processed,
and/or a large amount of matched sequences is requested by the user (by setting the
<<eql-search-api-params-size, size>> query param), the memory occupied by those
structures could potentially exceed the available memory of the JVM. This would cause
an `OutOfMemory` exception which would bring down the node.
To prevent this from happening, a special <<circuit-breaker, circuit breaker>> is used,
which limits the memory allocation during the execution of a <<eql-sequences, sequence>>
query. When the breaker is triggered, an `org.elasticsearch.common.breaker.CircuitBreakingException`
is thrown and a descriptive error message is returned to the user.
This <<circuit-breaker, circuit breaker>> can be configured using the following settings:
`breaker.eql_sequence.limit`::
(<<cluster-update-settings,Dynamic>>) The limit for circuit breaker used to restrict
the memory utilisation during the execution of an EQL sequence query. This value is
defined as a percentage of the JVM heap. Defaults to `50%`. If the
<<parent-circuit-breaker,parent circuit breaker>> is set to a value less than `50%`,
this setting uses that value as its default instead.
`breaker.eql_sequence.overhead`::
(<<cluster-update-settings,Dynamic>>) A constant that sequence query memory
estimates are multiplied by to determine a final estimate. Defaults to `1`.
`breaker.eql_sequence.type`::
(<<static-cluster-setting,Static>>) Circuit breaker type. Valid values are:
`memory` (Default):::
The breaker limits memory usage for EQL sequence queries.
`noop`:::
Disables the breaker.
include::syntax.asciidoc[] include::syntax.asciidoc[]
include::functions.asciidoc[] include::functions.asciidoc[]
include::pipes.asciidoc[] include::pipes.asciidoc[]