Document the new Detection rule monitoring dashboard (#3600) (#3628)

* First draft

* Update Dashboards landing page

* Add frontmatter

* Address feedback from Georgii & Janeen

Mention time range & filters, and spaces
Edits

(cherry picked from commit 57f23c9)

Co-authored-by: Joe Peeples <[email protected]>

docs/dashboards/dashboards-overview.asciidoc

@@ -1,14 +1,16 @@
 [[dashboards-overview]]
-
 = Dashboards
 
-The following sections describe the {security-app}'s prebuilt dashboards, which provide visualizations of your security environment.
-
-You can also create and access custom security dashboards from the Dashboards landing page. To create one, click **Create Dashboard**. Once created, custom dashboards appear on the page:
+:frontmatter-description: Dashboards give you insight into your security environment.
+:frontmatter-tags-products: [security]
+:frontmatter-tags-content-type: [overview]
+:frontmatter-tags-user-goals: [visualize, monitor, analyze]
 
-image::images/custom-dashboard-setup.png[The dashboards landing page, with the "create dashboard" button and custom dashboards table highlighted]
+The following sections describe the {security-app}'s prebuilt dashboards, which provide visualizations of your security environment.
 
+You can also create and access custom security dashboards from the Dashboards landing page. To create one, click **Create Dashboard**. Custom dashboards must have the tag `Security Solution` to appear on the Dashboards page.
 
+image::images/dashboards-landing-page.png[The Dashboards landing page]
 
 
 include::overview-dashboard.asciidoc[leveloffset=+1]
@@ -24,3 +26,5 @@ include::entity-dashboard.asciidoc[leveloffset=+1]
 include::data-quality-dashboard.asciidoc[leveloffset=+1]
 
 include::vuln-management-dashboard-dash.asciidoc[leveloffset=+1]
+
+include::rule-monitoring-dashboard.asciidoc[leveloffset=+1]

docs/dashboards/rule-monitoring-dashboard.asciidoc

@@ -0,0 +1,67 @@
+[[rule-monitoring-dashboard]]
+= Detection rule monitoring dashboard
+
+:frontmatter-description: Visualize your detection rules' performance.
+:frontmatter-tags-products: [security]
+:frontmatter-tags-content-type: [how-to]
+:frontmatter-tags-user-goals: [visualize, monitor]
+
+The Detection rule monitoring dashboard provides visualizations to help you monitor the overall health and performance of {elastic-sec}'s detection rules. Consult this dashboard for a high-level view of whether your rules are running successfully and how long they're taking to run, search data, and create alerts.
+
+[role="screenshot"]
+image::images/rule-monitoring-overview.png[Overview of Detection rule monitoring dashboard]
+
+.Requirements
+[sidebar]
+--
+To access this dashboard and its data, you must have:
+
+* At least `Read` {kibana-ref}/kibana-role-management.html#adding_kibana_privileges[{kib} privileges] for both the *Analytics > Dashboard* and *Security > Security* {kib} features.
+
+* At least `read` {kibana-ref}/kibana-role-management.html#adding_index_privileges[index privileges] for the `.kibana-event-log-*` index.
+--
+
+[discrete]
+[[rule-monitoring-visualizations]]
+== Visualization data and types
+
+The dashboard presents a variety of information about your detection rules. Visualizations display and calculate data within the time range and filters selected at the top of the dashboard.
+
+The dashboard also includes data from all {kib} spaces. To display data only from specific spaces, open the dashboard in {kib} (*Analytics* -> *Dashboard*) and use the *Kibana space* drop-down filter.
+
+The following visualizations are included:
+
+* *Rule KPIs (key performance indicators)*: The total number of rules enabled, how many times they collectively ran, and their response statuses.
+* *Executions by rule type*: Rule executions over time, broken down by rule type.
+* *Executions by status*: Rule executions over time, broken down by status.
+* *Total rule execution duration*: How long rules take to run, from start to finish.
+* *Rule schedule delay*: The delay between a rule's scheduled start time and when it actually starts running.
+* *Search/query duration*: How long rules take to query source indices or data views.
+* *Indexing duration*: How long rules take to generate alerts and write them to the `.alerts-security.alerts-*` index.
+* *Top 10 rules*: Lists of the overall slowest rules, most delayed rules, and rules with the most *Failed* and *Warning* response statuses.
+
+[discrete]
+[[rule-visualization-actions]]
+== Visualization panel actions
+
+Open a panel's options menu (image:images/three-dot-icon.png[Options menu,18,18]) customize the panel or use its data for further analysis and investigation:
+
+* *Edit panel settings*: Customize the panel's display settings. Options vary by visualization type.
+* *Inspect*: Examine the panel's underlying data and queries.
+* *Explore data in Discover*: Open Discover with preloaded filters to display the panel's data.
+* *Maximize panel*: Expand the panel.
+* *Download as CSV*: Download the panel's data in a CSV file.
+* *Copy to dashboard*: Copy the panel to an existing or new dashboard.
+* *Add to existing case*: Add the panel to an existing case.
+* *Add to new case*: Create a new case and add the panel to it.
+* *Create anomaly detection job*: Create a {ml} anomaly detection job using the panel's data.
+
+[discrete]
+[[clone-edit-dashboard]]
+== Clone and edit the dashboard
+
+This dashboard is managed by {kib}, so any changes you make to it will not last. To make persistent changes, you can clone the dashboard and edit the cloned copy, but your copy will not get updates from Elastic.
+
+. Click *Edit*, then *Save as*.
+. On the *Save dashboard* dialog, enter a new *Title* for your cloned copy.
+. Make sure *Save as new dashboard* is selected, then click *Save*. You can now make additional changes and save them to your copy.

docs/detections/rules-ui-monitor.asciidoc

@@ -1,19 +1,20 @@
 [[alerts-ui-monitor]]
-[role="xpack"]
 == Monitor and troubleshoot rule executions
 
-:frontmatter-description: Monitor the status of your detection rules and troubleshoot common issues with rules and alerts.
+:frontmatter-description: Find out how your rules are performing, and troubleshoot common rule issues.
 :frontmatter-tags-products: [security]
 :frontmatter-tags-content-type: [how-to]
-:frontmatter-tags-user-goals: [manage, monitor]
+:frontmatter-tags-user-goals: [monitor, manage]
 
-The Rules page offers several ways to gain insight into the status of your detection rules:
+Several tools can help you gain insight into the performance of your detection rules:
 
 * <<rule-monitoring-tab, Rule Monitoring tab>> — The current state of all detection rules and their most recent executions. Go to the *Rule Monitoring* tab to get an overview of which rules are running, how long they're taking, and if they're having any trouble.
 
 * <<rule-execution-logs, Execution results>> — Historical data for a single detection rule's executions over time. Consult the execution results to understand how a particular rule is running and whether it's creating the alerts you expect.
 
-Refer to the <<troubleshoot-signals>> section below for strategies on using these tools.
+* <<rule-monitoring-dashboard, Detection rule monitoring dashboard>> — Visualizations to help you monitor the overall health and performance of {elastic-sec}'s detection rules. Consult this dashboard for a high-level view of whether your rules are running successfully and how long they're taking to run, search data, and create alerts.
+
+Refer to the <<troubleshoot-signals>> section below for strategies on adjusting rules if they aren't creating the expected alerts.
 
 [float]
 [[rule-monitoring-tab]]