Document the Rule Query Inspector for threshold rules

[nastasha-solomon]

Summary

Fixes #6555.

Documents the rule query inspector, a new feature in 9.5 and Serverless that lets users view the Elasticsearch request a rule sends during evaluation. The primary goal is not to explain how to open the inspector (the UI is self-explanatory) but to help users understand what they see: how the query structure maps to their rule configuration, and how to read the response to determine why an alert did or didn't fire.

Why the page lives in explore-analyze/alerting/alerts/

The queryInspector hook is part of the RuleType interface — it's a Kibana platform feature, not an Observability-specific one. Placing the reference page in the general Kibana alerting section means it's in the right long-term home when other rule types adopt the inspector. The Observability pages link to it as a cross-reference, which is already a common pattern in the docs. The page clearly notes that in 9.5 and on serverless, only custom threshold rules are supported.

Previews

• Diagnose rule behavior with the rule query inspector - New page that provides the following:
  • Two entry points to the inspector and the key difference between them: the rule details page uses current rule parameters, while an alert details page uses the historical parameters stored at the time that specific alert fired
  • Query anatomy for custom threshold rules: index/time range, query filter, aggregations (with a criterion-to-aggregation mapping table), and composite aggregation structure when Group alerts by is used
  • How to read the response: single-value (no group-by), bucketed (group-by), and null/no-data responses
  • Five common troubleshooting scenarios as expandable dropdowns
• Create and manage rules | Inspect the rule query: Added a brief "Inspect the rule query" section under "View rule details" with a link to the new "Diagnose rule behavior with the rule query inspector" page.
• Triage threshold breaches | Inspect the query behind an alert- Added an "Inspect the query behind an alert" section explaining the alert-details-specific inspector behavior (historical parameters) and linking to the reference page.

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes - Cursor + Claude
• No

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: queued.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

[github-actions]

🔍 Preview links for changed docs

• explore-analyze/alerting/alerts/inspect-rule-queries.md
• solutions/observability/incident-management/create-manage-rules.md
• solutions/observability/incident-management/triage-threshold-breaches.md

[github-actions]

Vale Linting Results

Summary: 5 suggestions found

💡 Suggestions (5)

File	Line	Rule	Message
explore-analyze/alerting/alerts/inspect-rule-queries.md	153	Elastic.HeadingColons	Capitalize ': s'.
explore-analyze/alerting/alerts/inspect-rule-queries.md	170	Elastic.HeadingColons	Capitalize ': b'.
solutions/observability/incident-management/create-manage-rules.md	112	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI.
solutions/observability/incident-management/create-manage-rules.md	114	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI.
solutions/observability/incident-management/triage-threshold-breaches.md	73	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.

---

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

[github-actions]

Docs review summary

Focus areas

• Style and clarity: Two minor issues found (one typo, one possessive error). Otherwise clear, well-structured, and follows style guide.
• Jargon: Appropriate use of technical terms with context. Elasticsearch, Kibana, and KQL are explained through usage.
• Frontmatter and applies_to: Correct. New page has proper description, navigation_title, products, and applies_to metadata. Version gates are properly applied.
• Content type fit: The new page functions as a reference/how-to hybrid explaining both what the inspector shows and how to interpret it. Structure fits the troubleshooting use case well with clear sections and practical examples.
• Parent issue satisfaction: Satisfied. The PR fully addresses issue #6555's requirements: explains query anatomy, documents both entry points and their differences (current vs. historical parameters), maps rule configuration to query structure, provides response interpretation guidance, and includes troubleshooting scenarios.

Notes

• The page appropriately uses present tense and active voice throughout.
• The dropdowns for troubleshooting scenarios are an effective pattern for progressive disclosure.
• Code examples are well-annotated with callout numbers.
• The distinction between the two inspector entry points is clearly explained and reinforced throughout.

Generated by Docs review agent for issue #6746 · ● 763.6K

[nastasha-solomon]

@benakansara would you mind validating the content on this page before I open the PR for review? Here's the HTML preview so you can also see the web-rendered version of the docs.

[benakansara]

@nastasha-solomon Thanks for documenting this! A few thoughts on the scope of the documentation:

I think the primary use of the query inspector is for users to quickly check what the query returned - either because they got an alert unexpectedly, or because they want to make small adjustments (like tweaking the time range) to understand why an alert didn't fire as expected.

Users are generally not interested in how we structure the query internally, nor are they expected to modify the query beyond adjusting the time range. The query can also be quite lengthy and its structure can change as we add new features to the rule type (we don't usually modify existing functionality, but new capabilities can affect how the query is built). Documenting the query anatomy in detail creates a maintenance burden.

I'd suggest to scope the documentation as:

• A brief introduction to the feature and where it's available
• The difference between the rule details page and alert details page inspector (current vs historical parameters)
• Examples of common troubleshooting scenarios

The "Anatomy of the query" section could be dropped or condensed into a short note that the request tab shows the full Elasticsearch query. The response tab shows the raw values Elasticsearch returned, which can help confirm whether data was found, whether expected groups are present, and what values the rule was working with.