From 682dcebfab0fb4fa5a90631c5f88233a739356bc Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 3 Aug 2021 16:49:11 -0400 Subject: [PATCH 1/2] [DOCS] Document regex circuit breaker Documents the `script.painless.regex.enabled` and `script.painless.regex.limit-factor` cluster settings. Relates to #63029. --- docs/reference/ingest.asciidoc | 8 ++-- .../modules/indices/circuit_breaker.asciidoc | 38 +++++++++++++++++++ 2 files changed, 42 insertions(+), 4 deletions(-) diff --git a/docs/reference/ingest.asciidoc b/docs/reference/ingest.asciidoc index 7fb70ad21b9ee..0eaec88027533 100644 --- a/docs/reference/ingest.asciidoc +++ b/docs/reference/ingest.asciidoc @@ -770,10 +770,10 @@ PUT _ingest/pipeline/my-pipeline } ---- -If the static `script.painless.regex.enabled` cluster setting is enabled, you -can use regular expressions in your `if` condition scripts. For supported -syntax, see the {painless}/painless-regexes.html[Painless regexes] -documentation. +If the <> cluster +setting is enabled, you can use regular expressions in your `if` condition +scripts. For supported syntax, see {painless}/painless-regexes.html[Painless +regular expressions]. TIP: If possible, avoid using regular expressions. Expensive regular expressions can slow indexing speeds. diff --git a/docs/reference/modules/indices/circuit_breaker.asciidoc b/docs/reference/modules/indices/circuit_breaker.asciidoc index e2ea9dffa10d8..f83c0452aedab 100644 --- a/docs/reference/modules/indices/circuit_breaker.asciidoc +++ b/docs/reference/modules/indices/circuit_breaker.asciidoc @@ -131,3 +131,41 @@ documentation for more information. Limit for the number of unique dynamic scripts within a certain interval that are allowed to be compiled for a given context. Defaults to `75/5m`, meaning 75 every 5 minutes. + +[[regex-circuit-breaker]] +[discrete] +==== Regex circuit breaker + +Poorly written regular expressions can degrade cluster stability and +performance. The regex circuit breaker limits the use and complexity of +{painless}/painless-regexes.html[regex in Painless scripts]. + +[[script-painless-regex-enabled]] +`script.painless.regex.enabled`:: +(<>) Enables regex in Painless scripts. Accepts: + +`limit` (Default)::: +Enables regex but limits complexity using the +<> +cluster setting. + +`true`::: +Enables regex with no complexity limits. Disables the regex circuit breaker. + +`false`::: +Disables regex. Any Painless script containing a regular expression triggers the +regex circuit breaker and returns an error. + +[[script-painless-regex-limit-factor]] +`script.painless.regex.limit-factor`:: +(<>) Limits the number of characters a regular +expression in a Painless script can consider. {es} calculates this limit by +multiplying the setting value by the script input's character length. ++ +For example, the input `foobarbaz` has a character length of `9`. If +`script.painless.regex.limit-factor` is `6`, a regular expression on `foobarbaz` +can consider up to 54 (9 * 6) characters. If the expression exceeds this limit, +it triggers the regex circuit breaker and returns an error. ++ +{es} only applies this limit if +<> is `limit`. From 8a79387f61b1d8957a009807f99ccb6e28610b24 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Wed, 4 Aug 2021 16:02:05 -0400 Subject: [PATCH 2/2] Reword --- docs/reference/modules/indices/circuit_breaker.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/modules/indices/circuit_breaker.asciidoc b/docs/reference/modules/indices/circuit_breaker.asciidoc index f83c0452aedab..cc5a7e78c21dd 100644 --- a/docs/reference/modules/indices/circuit_breaker.asciidoc +++ b/docs/reference/modules/indices/circuit_breaker.asciidoc @@ -153,8 +153,8 @@ cluster setting. Enables regex with no complexity limits. Disables the regex circuit breaker. `false`::: -Disables regex. Any Painless script containing a regular expression triggers the -regex circuit breaker and returns an error. +Disables regex. Any Painless script containing a regular expression returns an +error. [[script-painless-regex-limit-factor]] `script.painless.regex.limit-factor`::