From 0de4a9c4d7178a580f8e66092199b68ed31a36df Mon Sep 17 00:00:00 2001
From: elasticsearchmachine
 <58790826+elasticsearchmachine@users.noreply.github.com>
Date: Wed, 4 Aug 2021 16:48:25 -0400
Subject: [PATCH] [DOCS] Document regex circuit breaker (#76048) (#76129)

Documents the `script.painless.regex.enabled` and
`script.painless.regex.limit-factor` cluster settings.

Relates to #63029.

Closes #75199.

Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
---
 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 e060447ad0959..0eab9a29f3ded 100644
--- a/docs/reference/ingest.asciidoc
+++ b/docs/reference/ingest.asciidoc
@@ -772,10 +772,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 <<script-painless-regex-enabled,`script.painless.regex.enabled`>> 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..cc5a7e78c21dd 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`::
+(<<static-cluster-setting,Static>>) Enables regex in Painless scripts. Accepts:
+
+`limit` (Default):::
+Enables regex but limits complexity using the
+<<script-painless-regex-limit-factor,`script.painless.regex.limit-factor`>>
+cluster setting.
+
+`true`:::
+Enables regex with no complexity limits. Disables the regex circuit breaker.
+
+`false`:::
+Disables regex. Any Painless script containing a regular expression returns an
+error.
+
+[[script-painless-regex-limit-factor]]
+`script.painless.regex.limit-factor`::
+(<<static-cluster-setting,Static>>) 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
+<<script-painless-regex-enabled,`script.painless.regex.enabled`>> is `limit`.