Circuit breaker settings

Elasticsearch contains multiple circuit breakers used to prevent operations from using an excessive amount of memory. Each breaker tracks the memory used by certain operations and specifies a limit for how much memory it may track. Additionally, there is a parent-level breaker that specifies the total amount of memory that may be tracked across all breakers.

When a circuit breaker reaches its limit, Elasticsearch will reject further operations. See Circuit breaker errors for information about errors raised by circuit breakers.

Circuit breakers do not track all memory usage in Elasticsearch and therefore provide only incomplete protection against excessive memory usage. If Elasticsearch uses too much memory then it may suffer from performance issues and nodes may even fail with an OutOfMemoryError. See High JVM memory pressure for help with troubleshooting high heap usage.

Except where noted otherwise, these settings can be dynamically updated on a live cluster with the cluster-update-settings API.

For information about circuit breaker errors, see Circuit breaker errors.

The parent-level breaker can be configured with the following settings:

The field data circuit breaker estimates the heap memory required to load a field into the field data cache. If loading the field would cause the cache to exceed a predefined memory limit, the circuit breaker stops the operation and returns an error.

The request circuit breaker allows Elasticsearch to prevent per-request data structures (for example, memory used for calculating aggregations during a request) from exceeding a certain amount of memory.

The in flight requests circuit breaker allows Elasticsearch to limit the memory usage of all currently active incoming requests on transport or HTTP level from exceeding a certain amount of memory on a node. The memory usage is based on the content length of the request itself. This circuit breaker also considers that memory is not only needed for representing the raw request but also as a structured object which is reflected by default overhead.

Slightly different than the previous memory-based circuit breaker, the script compilation circuit breaker limits the number of inline script compilations within a period of time.

See the "prefer-parameters" section of the scripting documentation for more information.

If the cluster regularly hits the given max_compilation_rate, it’s possible the script cache is undersized, use Nodes Stats to inspect the number of recent cache evictions, script.cache_evictions_history and compilations script.compilations_history. If there are a large number of recent cache evictions or compilations, the script cache may be undersized, consider doubling the size of the script cache via the setting script.cache.max_size.

Poorly written regular expressions can degrade cluster stability and performance. The regex circuit breaker limits the use and complexity of regex in Painless scripts.

When a 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 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 is used, which limits the memory allocation during the execution of a sequence query. When the breaker is triggered, an org.elasticsearch.common.breaker.CircuitBreakingException is thrown and a descriptive error message including circuit_breaking_exception is returned to the user.

This circuit breaker can be configured using the following settings: