[Request][ESS] Document advanced setting that allows users to disable ES|QL in ESS

[nastasha-solomon]

Contributes to #5163 and #5149

Previews: A note about the enableESQL advanced setting was added to the following locations:

• At the start of the Use ES|QL to investigate events section
  • NOTE: The outdated language that tells users to not use ES|QL in production envs, and the note about the ES|QL Timeline tab being in tech preview, will be removed once I merge [Request][ESS][8.14] ES|QL Timeline tab enabled by default and moved to GA  #5139.
• At the start of the Knowledge base for ES|QL section
• Under the description for the ES|QL rule type here

No Serverless PR was created. The advanced setting is only available in ESS right now.

[github-actions]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

Request a new doc build by commenting

• Rebuild this PR: run docs-build
• Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

[joepeeples]

The text itself LGTM, but I'm not sure why we need to remind users in all these places that they can turn off ES|QL. If a user goes to a section like "Create an ES|QL rule" or "Use ES|QL to investigate events," they're not trying to turn off the entire language — they want to use it. Maybe there's a different context where it'd be more natural to tell users how to disable ES|QL if they don't want to use it?

[nastasha-solomon]

Looking at this again, I don't think we need to put this notice in the places where users are creating a new ES|QL rule from the UI. I agree that if they've landed on those instructions, they've already decided to create an ES|QL rule. But I do think it's important to keep the note in the places that provide background on the ES|QL features in Security to ensure it's visible in the places where users go to learn about the feature. Here's where I think it'd be appropriate:

• At the start of the Use ES|QL to investigate events section
• At the start of the Knowledge base for ES|QL section
• Under the description for the ES|QL rule type here

I also think we can change the focus of the message to let users know that there's a single advanced setting that controls all ES|QL features in ESS. Here's what I'm thinking:

ES|QL features are turned on by default and are controlled by the enableESQL advanced setting.

@joepeeples and @paulewing let me know your thoughts on what I've laid out above.

[joepeeples]

Thanks @nastasha-solomon, here are some direct responses:

I do think it's important to keep the note in the places that provide background on the ES|QL features in Security to ensure it's visible in the places where users go to learn about the feature.

Definitely agree! Ideally there'd be a single location where we can document this, instead of having the same message repeated across several topics. But repeating might be unavoidable.

• At the start of the Use ES|QL to investigate events section

This section appears to have two duplicate notes about the same thing — or maybe it's two different things that, at first (and second) glance look like the same thing? Either way it's confusing.

Here's what I'm thinking:

ES|QL features are turned on by default and are controlled by the enableESQL advanced setting.

LGTM!

[nastasha-solomon]

@joepeeples yeah, within the Security docs, there's no one single place to add the information about the advanced setting. There is this page over on the Elasticsearch side, but it's in the ES docset, so it's a bit out of the way for Security users. Plus, I feel like Using ES|QL page would be the better place to put the advanced setting information. I'll ping Liam about this next week to get his thoughts on adding the advanced setting information to the ES|QL docs.

RE the second note that you pointed out under the Timeline docs:
That note, and the one above it that says to not use ES|QL in production envs will be removed once I merge #5139.

[mergify]

This pull request is now in conflicts. Could you fix it @nastasha-solomon? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b issue-5163-esql-adv-set upstream/issue-5163-esql-adv-set
git merge upstream/main
git push upstream issue-5163-esql-adv-set

[nastasha-solomon]

I pinged the ES|QL writer to check whether they're mentioning the advanced setting in the core ES|QL docs. Will report back here once I know more.