Painless docs overhaul (explore & analyze) #3580
Open
+2,367
−453
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
kilfoyle
changed the title
kilfoyle
changed the title
yetanothertw
approved these changes
Oct 24, 2025
benironside
approved these changes
Oct 27, 2025
There was a problem hiding this comment.
painless docs shouldn't be spread throughout - they should be in their own subsection, which is a sibling of the lucene exp lang and the custom scripting language guide.
There was a problem hiding this comment.
did only a very brief sweep due to limited time. couple of things:
-
the newly introduced tutorials aren't structured as tutorials - the steps are all one big block of prose. they really need to be broken into sequential steps.
-
language in the tutorials is very flowery. could pull it back a little.
-
Lots of booboo typos and formatting errors here and there (commented on the first handful I found). Could use a finer toothed comb. Would also suggest just requesting a review from copilot in github to do an editing pass
| * [Field extraction](scripting-field-extraction.md) | ||
| Painless scripting becomes powerful when applied to real-world scenarios. These tutorials walk you through essential patterns and operations, providing working examples you can modify for your specific use cases. | ||
|
|
||
| # Available tutorials |
There was a problem hiding this comment.
this should not be an H1. I question whether you need a heading here or just an intro sentence to the list
| # Introduction to Painless [modules-scripting-painless] | ||
|
|
||
| :::{tip} | ||
| This introduction is designed for users new to Painless scripting. If you're already familiar with Painless, refer to the [Painless Language Specification](elasticsearch://reference/scripting-languages/painless/painless-language-specification.md) for syntax details and advanced features. |
There was a problem hiding this comment.
Suggested change
| This introduction is designed for users new to Painless scripting. If you're already familiar with Painless, refer to the [Painless Language Specification](elasticsearch://reference/scripting-languages/painless/painless-language-specification.md) for syntax details and advanced features. | |
| This introduction is designed for users new to Painless scripting. If you're already familiar with Painless, refer to the [Painless language specification](elasticsearch://reference/scripting-languages/painless/painless-language-specification.md) for syntax details and advanced features. |
| This introduction is designed for users new to Painless scripting. If you're already familiar with Painless, refer to the [Painless Language Specification](elasticsearch://reference/scripting-languages/painless/painless-language-specification.md) for syntax details and advanced features. | ||
| ::: | ||
|
|
||
| Painless is a secure, performant, and flexible scripting language designed specifically for {{es}}. As the default scripting language for {{es}}, Painless lets you safely customize search behavior, data processing, and operations workflows across your Elastic Stack deployments. |
There was a problem hiding this comment.
Suggested change
| Painless is a secure, performant, and flexible scripting language designed specifically for {{es}}. As the default scripting language for {{es}}, Painless lets you safely customize search behavior, data processing, and operations workflows across your Elastic Stack deployments. | |
| Painless is a secure, performant, and flexible scripting language designed specifically for {{es}}. As the default scripting language for {{es}}, Painless lets you safely customize search behavior, data processing, and operations workflows across your {{stack}} deployments. |
|
|
||
| Common use cases include creating new fields based on existing data, calculating time differences between dates, extracting structured data from log messages, and implementing custom business logic in search scoring. For more examples, refer to our step-by-step [tutorials](/explore-analyze/scripting/common-script-uses.md). | ||
|
|
||
| ## What are the benefits of Painless? |
There was a problem hiding this comment.
Suggested change
| ## What are the benefits of Painless? | |
| ## Benefits |
| * Monitor data patterns and trigger alerts with Watcher solutions | ||
| * Transform alert payloads for targeted notifications and actions | ||
|
|
||
| ## How does it work? |
There was a problem hiding this comment.
Avoid FAQ-style headings
| As part of its core design, Painless provides secure scripting capabilities across {{es}}. | ||
|
|
||
| Painless uses a fine-grained allowlist. Anything that is not part of the allowlist results in a compilation error. This capability is the first layer of security in a defense in depth strategy for scripting. | ||
| ## Why Painless is Safe |
There was a problem hiding this comment.
this might be a liiiiittle too bold of a statement
Suggested change
| ## Why Painless is Safe | |
| ## Why Painless is safe |
| By operating in a controlled sandbox environment, Painless ensures that you won’t get compromised when using it. Painless only allows pre-approved operations through fine-grained allowlists. Scripts cannot access file systems, networks, or other system resources that could compromise your cluster while still providing the flexibility you need for search scoring, data processing, and operational automation. | ||
|
|
||
| {{es}} uses [seccomp](https://en.wikipedia.org/wiki/Seccomp) in Linux, [Seatbelt](https://www.chromium.org/developers/design-documents/sandbox/osx-sandboxing-design) in macOS, and [ActiveProcessLimit](https://msdn.microsoft.com/en-us/library/windows/desktop/ms684147) on Windows as additional security layers to prevent {{es}} from forking or running other processes. | ||
| ## Security Architecture Overview |
There was a problem hiding this comment.
Suggested change
| ## Security Architecture Overview | |
| ## Security architecture overview |
| You can modify the following script settings to restrict the type of scripts that are allowed to run, and control the available [contexts](elasticsearch://reference/scripting-languages/painless/painless-contexts.md) that scripts can run in. To implement additional layers in your defense in depth strategy, follow the [{{es}} security principles](../../deploy-manage/security.md). | ||
| The fine-grained allowlist operates as the **first security layer**. Anything that is not part of the allowlist will result in a compilation error. | ||
|
|
||
| The **second layer of security** is [Java Security Manager(JSM)](https://www.oracle.com/java/technologies/javase/seccodeguide.html). As part of its startup sequence, {{es}} enables JSM to limit the actions that portions of the code can take. Painless uses this additional layer of defense to prevent scripts from doing things such as writing files and listening to sockets. |
There was a problem hiding this comment.
Suggested change
| The **second layer of security** is [Java Security Manager(JSM)](https://www.oracle.com/java/technologies/javase/seccodeguide.html). As part of its startup sequence, {{es}} enables JSM to limit the actions that portions of the code can take. Painless uses this additional layer of defense to prevent scripts from doing things such as writing files and listening to sockets. | |
| The **second layer of security** is [Java Security Manager (JSM)](https://www.oracle.com/java/technologies/javase/seccodeguide.html). As part of its startup sequence, {{es}} enables JSM to limit the actions that portions of the code can take. Painless uses this additional layer of defense to prevent scripts from doing things such as writing files and listening to sockets. |
| Finally, scripts used in [scripted metrics aggregations](elasticsearch://reference/aggregations/search-aggregations-metrics-scripted-metric-aggregation.md) can be restricted to a defined list of scripts or forbidden altogether. This can prevent users from running particularly slow or resource-intensive aggregation queries. | ||
|
|
||
| {{es}} supports two script types: `inline` and `stored`. By default, {{es}} is configured to run both types of scripts. To limit what type of scripts are run, set `script.allowed_types` to `inline` or `stored`. To prevent any scripts from running, set `script.allowed_types` to `none`. | ||
| You can modify the ***allowed script types setting*** to restrict the type of scripts that are allowed to run and control the available [contexts](elasticsearch://reference/scripting-languages/painless/painless-contexts.md) that scripts can run in. To implement additional layers in your defense-in-depth strategy, follow the [{{es}} security principles](/deploy-manage/security.md). |
There was a problem hiding this comment.
bold and italics is a lot. wish we could just link down but it would not be a very good link
Suggested change
| You can modify the ***allowed script types setting*** to restrict the type of scripts that are allowed to run and control the available [contexts](elasticsearch://reference/scripting-languages/painless/painless-contexts.md) that scripts can run in. To implement additional layers in your defense-in-depth strategy, follow the [{{es}} security principles](/deploy-manage/security.md). | |
| You can modify the allowed script types setting to restrict the type of scripts that are allowed to run and control the available [contexts](elasticsearch://reference/scripting-languages/painless/painless-contexts.md) that scripts can run in. To implement additional layers in your defense-in-depth strategy, follow the [{{es}} security principles](/deploy-manage/security.md). |
There was a problem hiding this comment.
there are no principles at this link. I'd just say something about using elasticsearch security features
| :::: | ||
| ## Allowed script types setting [allowed-script-types-setting] | ||
|
|
||
| {{es}} supports two script types: `inline` and `stored`. By default, {{es}} is configured to run both types of scripts. To limit what type of scripts are run, set `script.allowed_types` to `inline` or `stored`. To prevent any scripts from running, set `script.allowed_types` to `none`. If you use Kibana, set \`script.allowed\_types\` to both or just \`inline\`. Some Kibana features rely on inline scripts and do not function as expected if {{es}} does not allow inline scripts. |
There was a problem hiding this comment.
something fishy with these escaped backticks
Suggested change
| {{es}} supports two script types: `inline` and `stored`. By default, {{es}} is configured to run both types of scripts. To limit what type of scripts are run, set `script.allowed_types` to `inline` or `stored`. To prevent any scripts from running, set `script.allowed_types` to `none`. If you use Kibana, set \`script.allowed\_types\` to both or just \`inline\`. Some Kibana features rely on inline scripts and do not function as expected if {{es}} does not allow inline scripts. | |
| {{es}} supports two script types: `inline` and `stored`. By default, {{es}} is configured to run both types of scripts. To limit what type of scripts are run, set `script.allowed_types` to `inline` or `stored`. To prevent any scripts from running, set `script.allowed_types` to `none`. If you use Kibana, set `script.allowed_types` to `both` or just `inline`. Some Kibana features rely on inline scripts and do not function as expected if {{es}} does not allow inline scripts. |
This comment was marked as duplicate.
This comment was marked as duplicate.
Sorry, something went wrong.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This refreshes the Scripting section of the Explore and Analyze docs, based on the Painless doc project.
The content has had both technical and writer reviews, so this is essentially a port from the gdoc project folder into the V3 docs system.
Rel: https://github.com/elastic/docs-content-internal/issues/299