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