diff --git a/docs/api/alerting/list_rule_types.asciidoc b/docs/api/alerting/list_rule_types.asciidoc index 98016c8cf82fa..31c8416e75059 100644 --- a/docs/api/alerting/list_rule_types.asciidoc +++ b/docs/api/alerting/list_rule_types.asciidoc @@ -8,7 +8,7 @@ Retrieve a list of alerting rule types that the user is authorized to access. Each rule type includes a list of consumer features. Within these features, users are authorized to perform either `read` or `all` operations on rules of that type. This helps determine which rule types users can read, but not create or modify. -NOTE: Some rule types are limited to specific features. These rule types are not available when <> in <>. +NOTE: Some rule types are limited to specific features. These rule types are not available when <> in <>. [[list-rule-types-api-request]] ==== Request diff --git a/docs/apm/apm-alerts.asciidoc b/docs/apm/apm-alerts.asciidoc index 0cee0c04d3fb6..3e3e2b178ff10 100644 --- a/docs/apm/apm-alerts.asciidoc +++ b/docs/apm/apm-alerts.asciidoc @@ -15,7 +15,7 @@ and enables central management of all alerts from <>. +see Kibana's <>. The APM app supports four different types of alerts: diff --git a/docs/management/connectors/action-types/index.asciidoc b/docs/management/connectors/action-types/index.asciidoc index 53819411ed78c..431031aa2f4d5 100644 --- a/docs/management/connectors/action-types/index.asciidoc +++ b/docs/management/connectors/action-types/index.asciidoc @@ -119,7 +119,7 @@ When creating a new rule, add an <> and select [role="screenshot"] image::images/pre-configured-alert-history-connector.png[Select pre-configured alert history connectors] -Documents are indexed using a preconfigured schema that captures the <> available for the rule. By default, these documents are indexed into the `kibana-alert-history-default` index, but you can specify a different index. Index names must start with `kibana-alert-history-` to take advantage of the preconfigured alert history index template. +Documents are indexed using a preconfigured schema that captures the <> available for the rule. By default, these documents are indexed into the `kibana-alert-history-default` index, but you can specify a different index. Index names must start with `kibana-alert-history-` to take advantage of the preconfigured alert history index template. [IMPORTANT] ============================================== diff --git a/docs/management/connectors/action-types/webhook.asciidoc b/docs/management/connectors/action-types/webhook.asciidoc index aa52e8a3bdb43..02c3de139e0d5 100644 --- a/docs/management/connectors/action-types/webhook.asciidoc +++ b/docs/management/connectors/action-types/webhook.asciidoc @@ -91,4 +91,4 @@ Body:: A JSON payload sent to the request URL. For example: Mustache template variables (the text enclosed in double braces, for example, `context.rule.name`) have their values escaped, so that the final JSON will be valid (escaping double quote characters). -For more information on Mustache template variables, refer to <>. +For more information on Mustache template variables, refer to <>. diff --git a/docs/rule-type-template.asciidoc b/docs/rule-type-template.asciidoc index 605bdd57c1492..5fe4de81bcddc 100644 --- a/docs/rule-type-template.asciidoc +++ b/docs/rule-type-template.asciidoc @@ -6,7 +6,7 @@ Include a short description of the rule type. [float] ==== Create the rule -Fill in the <>, then select **. +Fill in the <>, then select **. [float] ==== Define the conditions @@ -25,7 +25,7 @@ Condition2:: This is another condition the user must define. [float] ==== Add action variables -<> to run when the rule condition is met. The following variables are specific to the rule. You can also specify <>. +<> to run when the rule condition is met. The following variables are specific to the rule. You can also specify <>. `context.variableA`:: A short description of the context variable defined by the rule type. `context.variableB`:: A short description of the context variable defined by the rule type with an example. Example: `this is what variableB outputs`. diff --git a/docs/user/alerting/create-and-manage-rules.asciidoc b/docs/user/alerting/create-and-manage-rules.asciidoc new file mode 100644 index 0000000000000..af6714aef662f --- /dev/null +++ b/docs/user/alerting/create-and-manage-rules.asciidoc @@ -0,0 +1,184 @@ +[role="xpack"] +[[create-and-manage-rules]] +== Create and manage rules + +The *Rules* UI provides a cross-app view of alerting. Different {kib} apps like {observability-guide}/create-alerts.html[*Observability*], {security-guide}/prebuilt-rules.html[*Security*], <> and <> can offer their own rules. The *Rules* UI provides a central place to: + +* <> rules +* <> including enabling/disabling, muting/unmuting, and deleting +* Drill-down to <> + +[role="screenshot"] +image:images/rules-and-connectors-ui.png[Example rule listing in the Rules and Connectors UI] + +For more information on alerting concepts and the types of rules and connectors available, see <>. + +[float] +=== Required permissions + +Access to rules is granted based on your privileges to alerting-enabled features. See <> for more information. + +[float] +[[create-edit-rules]] +=== Create and edit rules + +Many rules must be created within the context of a {kib} app like <>, <>, or <>, but others are generic. Generic rule types can be created in the *Rules* management UI by clicking the *Create* button. This will launch a flyout that guides you through selecting a rule type and configuring its conditions and action type. Refer to <> for details on what types of rules are available and how to configure them. + +After a rule is created, you can re-open the flyout and change a rule's properties by clicking the *Edit* button shown on each row of the rule listing. + +[float] +[[defining-rules-general-details]] +==== General rule details + +All rules share the following four properties. + +Name:: The name of the rule. While this name does not have to be unique, the name can be referenced in actions and also appears in the searchable rule listing in the *Management* UI. A distinctive name can help identify and find a rule. +Tags:: A list of tag names that can be applied to a rule. Tags can help you organize and find rules, because tags appear in the rule listing in the *Management* UI, which is searchable by tag. +Check every:: This value determines how frequently the rule conditions are checked. Note that the timing of background rule checks is not guaranteed, particularly for intervals of less than 10 seconds. See <> for more information. +Notify:: This value limits how often actions are repeated when an alert remains active across rule checks. See <> for more information. + +- **Only on status change**: Actions are not repeated when an alert remains active across checks. Actions run only when the alert status changes. +- **Every time alert is active**: Actions are repeated when an alert remains active across checks. +- **On a custom action interval**: Actions are suppressed for the throttle interval, but repeat when an alert remains active across checks for a duration longer than the throttle interval. + +[float] +[[alerting-concepts-suppressing-duplicate-notifications]] +[NOTE] +============================================== +Since actions are executed per alert, a rule can end up generating a large number of actions. Take the following example where a rule is monitoring three servers every minute for CPU usage > 0.9, and the rule is set to notify **Every time alert is active**: + +* Minute 1: server X123 > 0.9. *One email* is sent for server X123. +* Minute 2: X123 and Y456 > 0.9. *Two emails* are sent, one for X123 and one for Y456. +* Minute 3: X123, Y456, Z789 > 0.9. *Three emails* are sent, one for each of X123, Y456, Z789. + +In the above example, three emails are sent for server X123 in the span of 3 minutes for the same rule. Often, it's desirable to suppress these re-notifications. If you set the rule **Notify** setting to **On a custom action interval** with an interval of 5 minutes, you reduce noise by only getting emails every 5 minutes for servers that continue to exceed the threshold: + +* Minute 1: server X123 > 0.9. *One email* is sent for server X123. +* Minute 2: X123 and Y456 > 0.9. *One email* is sent for Y456. +* Minute 3: X123, Y456, Z789 > 0.9. *One email* is sent for Z789. + +To get notified **only once** when a server exceeds the threshold, you can set the rule's **Notify** setting to **Only on status change**. +============================================== + +[role="screenshot"] +image::images/rule-flyout-general-details.png[alt='All rules have name, tags, check every, and notify properties in common'] + +[float] +[[defining-rules-type-conditions]] +==== Rule type and conditions + +Depending upon the {kib} app and context, you might be prompted to choose the type of rule to create. Some apps will pre-select the type of rule for you. + +[role="screenshot"] +image::images/rule-flyout-rule-type-selection.png[Choosing the type of rule to create] + +Each rule type provides its own way of defining the conditions to detect, but an expression formed by a series of clauses is a common pattern. Each clause has a UI control that allows you to define the clause. For example, in an index threshold rule, the `WHEN` clause allows you to select an aggregation operation to apply to a numeric field. + +[role="screenshot"] +image::images/rule-flyout-rule-conditions.png[UI for defining rule conditions on an index threshold rule] + +[float] +[[defining-rules-actions-details]] +==== Action type and details + +To receive notifications when a rule meets the defined conditions, you must add one or more actions. Start by selecting a type of connector for your action: + +[role="screenshot"] +image::images/rule-flyout-connector-type-selection.png[UI for selecting an action type] + +Each action must specify a <> instance. If no connectors exist for the selected type, click **Add connector** to create one. + +[role="screenshot"] +image::images/rule-flyout-action-no-connector.png[UI for adding connector] + +Once you have selected a connector, use the **Run When** dropdown to choose the action group to associate with this action. When a rule meets the defined condition, it is marked as **Active** and alerts are created and assigned to an action group. In addition to the action groups defined by the selected rule type, each rule also has a **Recovered** action group that is assigned when a rule's conditions are no longer detected. + +Each action type exposes different properties. For example, an email action allows you to set the recipients, the subject, and a message body in markdown format. See <> for details on the types of actions provided by {kib} and their properties. + +[role="screenshot"] +image::images/rule-flyout-action-details.png[UI for defining an email action] + +[float] +[[defining-rules-actions-variables]] +===== Action variables +Using the https://mustache.github.io/[Mustache] template syntax `{{variable name}}`, you can pass rule values at the time a condition is detected to an action. You can access the list of available variables using the "add variable" button. Although available variables differ by rule type, all rule types pass the following variables: + +`rule.id`:: The ID of the rule. +`rule.name`:: The name of the rule. +`rule.spaceId`:: The ID of the space for the rule. +`rule.tags`:: The list of tags applied to the rule. +`date`:: The date the rule scheduled the action, in ISO format. +`alert.id`:: The ID of the alert that scheduled the action. +`alert.actionGroup`:: The ID of the action group of the alert that scheduled the action. +`alert.actionSubgroup`:: The action subgroup of the alert that scheduled the action. +`alert.actionGroupName`:: The name of the action group of the alert that scheduled the action. +`kibanaBaseUrl`:: The configured <>. If not configured, this will be empty. + +[role="screenshot"] +image::images/rule-flyout-action-variables.png[Passing rule values to an action] + +Some cases exist where the variable values will be "escaped", when used in a context where escaping is needed: + +- For the <> connector, the `message` action configuration property escapes any characters that would be interpreted as Markdown. +- For the <> connector, the `message` action configuration property escapes any characters that would be interpreted as Slack Markdown. +- For the <> connector, the `body` action configuration property escapes any characters that are invalid in JSON string values. + +Mustache also supports "triple braces" of the form `{{{variable name}}}`, which indicates no escaping should be done at all. Care should be used when using this form, as it could end up rendering the variable content in such a way as to make the resulting parameter invalid or formatted incorrectly. + +Each rule type defines additional variables as properties of the variable `context`. For example, if a rule type defines a variable `value`, it can be used in an action parameter as `{{context.value}}`. + +For diagnostic or exploratory purposes, action variables whose values are objects, such as `context`, can be referenced directly as variables. The resulting value will be a JSON representation of the object. For example, if an action parameter includes `{{context}}`, it will expand to the JSON representation of all the variables and values provided by the rule type. + +You can attach more than one action. Clicking the "Add action" button will prompt you to select another rule type and repeat the above steps again. + +[role="screenshot"] +image::images/rule-flyout-add-action.png[You can add multiple actions on a rule] + +[NOTE] +============================================== +Actions are not required on rules. You can run a rule without actions to understand its behavior, and then <> later. +============================================== + +[float] +[[controlling-rules]] +=== Mute and disable rules + +The rule listing allows you to quickly mute/unmute, disable/enable, and delete individual rules by clicking menu button to open the actions menu. Muting means that the rule checks continue to run on a schedule, but that alert will not trigger any action. + +[role="screenshot"] +image:images/individual-mute-disable.png[The actions button allows an individual rule to be muted, disabled, or deleted] + +You can perform these operations in bulk by multi-selecting rules, and then clicking the *Manage rules* button: + +[role="screenshot"] +image:images/bulk-mute-disable.png[The Manage rules button lets you mute/unmute, enable/disable, and delete in bulk,width=75%] + +[float] +[[rule-details]] +=== Drilldown to rule details + +Select a rule name from the rule listing to access the *Rule details* page, which tells you about the state of the rule and provides granular control over the actions it is taking. + +[role="screenshot"] +image::images/rule-details-alerts-active.png[Rule details page with three alerts] + +In this example, the rule detects when a site serves more than a threshold number of bytes in a 24 hour period. Three sites are above the threshold. These are called alerts - occurrences of the condition being detected - and the alert name, status, time of detection, and duration of the condition are shown in this view. + +Upon detection, each alert can trigger one or more actions. If the condition persists, the same actions will trigger either on the next scheduled rule check, or (if defined) after the re-notify period on the rule has passed. To prevent re-notification, you can suppress future actions by clicking on the switch to mute an individual alert. + +[role="screenshot"] +image::images/rule-details-alert-muting.png[Muting an alert,width=50%] + +Alerts will come and go from the list depending on whether they meet the rule conditions or not - unless they are muted. If a muted instance no longer meets the rule conditions, it will appear as inactive in the list. This prevents an alert from triggering actions if it reappears in the future. + +[role="screenshot"] +image::images/rule-details-alerts-inactive.png[Rule details page with three inactive alerts] + +If you want to suppress actions on all current and future alerts, you can mute the entire rule. Rule checks continue to run and the alert list will update as alerts activate or deactivate, but no actions will be triggered. + +[role="screenshot"] +image::images/rule-details-muting.png[Use the mute toggle to suppress all actions on current and future alerts,width=50%] + +You can also disable a rule altogether. When disabled, the rule stops running checks altogether and will clear any alerts it is tracking. You may want to disable rules that are not currently needed to reduce the load on {kib} and {es}. + +[role="screenshot"] +image::images/rule-details-disabling.png[Use the disable toggle to turn off rule checks and clear alerts tracked] diff --git a/docs/user/alerting/defining-rules.asciidoc b/docs/user/alerting/defining-rules.asciidoc index c48108ca9acc0..686a7bbc8a37b 100644 --- a/docs/user/alerting/defining-rules.asciidoc +++ b/docs/user/alerting/defining-rules.asciidoc @@ -2,133 +2,10 @@ [[defining-alerts]] == Defining rules -{kib} alerting rules can be created in a variety of apps including <>, <>, <>, <>, <> and from the <> UI. While alerting details may differ from app to app, they share a common interface for defining and configuring rules that this section describes in more detail. - -[float] -=== Create a rule - -When you create a rule, you must define the rule details, conditions, and actions. - -. <> -. <> -. <> - -image::images/rule-flyout-sections.png[The three sections of a rule definition] +This content has been moved to <>. [float] [[defining-alerts-general-details]] -=== General rule details - -All rules share the following four properties. - -[role="screenshot"] -image::images/rule-flyout-general-details.png[alt='All rules have name, tags, check every, and notify properties in common'] - -Name:: The name of the rule. While this name does not have to be unique, the name can be referenced in actions and also appears in the searchable rule listing in the management UI. A distinctive name can help identify and find a rule. -Tags:: A list of tag names that can be applied to a rule. Tags can help you organize and find rules, because tags appear in the rule listing in the management UI which is searchable by tag. -Check every:: This value determines how frequently the rule conditions below are checked. Note that the timing of background rule checks are not guaranteed, particularly for intervals of less than 10 seconds. See <> for more information. -Notify:: This value limits how often actions are repeated when an alert remains active across rule checks. See <> for more information. + -- **Only on status change**: Actions are not repeated when an alert remains active across checks. Actions run only when the alert status changes. -- **Every time alert is active**: Actions are repeated when an alert remains active across checks. -- **On a custom action interval**: Actions are suppressed for the throttle interval, but repeat when an alert remains active across checks for a duration longer than the throttle interval. - -[float] -[[alerting-concepts-suppressing-duplicate-notifications]] -[NOTE] -============================================== -Since actions are executed per alert, a rule can end up generating a large number of actions. Take the following example where a rule is monitoring three servers every minute for CPU usage > 0.9, and the rule is set to notify **Every time alert is active**: - -* Minute 1: server X123 > 0.9. *One email* is sent for server X123. -* Minute 2: X123 and Y456 > 0.9. *Two emails* are sent, one for X123 and one for Y456. -* Minute 3: X123, Y456, Z789 > 0.9. *Three emails* are sent, one for each of X123, Y456, Z789. - -In the above example, three emails are sent for server X123 in the span of 3 minutes for the same rule. Often, it's desirable to suppress these re-notifications. If you set the rule **Notify** setting to **On a custom action interval** with an interval of 5 minutes, you reduce noise by only getting emails every 5 minutes for servers that continue to exceed the threshold: - -* Minute 1: server X123 > 0.9. *One email* is sent for server X123. -* Minute 2: X123 and Y456 > 0.9. *One email* is sent for Y456. -* Minute 3: X123, Y456, Z789 > 0.9. *One email* is sent for Z789. - -To get notified **only once** when a server exceeds the threshold, you can set the rule's **Notify** setting to **Only on status change**. -============================================== - - -[float] -[[defining-alerts-type-conditions]] -=== Rule type and conditions - -Depending upon the {kib} app and context, you may be prompted to choose the type of rule you wish to create. Some apps will pre-select the type of rule for you. - -[role="screenshot"] -image::images/rule-flyout-rule-type-selection.png[Choosing the type of rule to create] - -Each rule type provides its own way of defining the conditions to detect, but an expression formed by a series of clauses is a common pattern. Each clause has a UI control that allows you to define the clause. For example, in an index threshold rule the `WHEN` clause allows you to select an aggregation operation to apply to a numeric field. - -[role="screenshot"] -image::images/rule-flyout-rule-conditions.png[UI for defining rule conditions on an index threshold rule] - -[float] -[[defining-alerts-actions-details]] -=== Action type and action details - -To add an action to a rule, you first select the type of connector: - -[role="screenshot"] -image::images/rule-flyout-connector-type-selection.png[UI for selecting an action type] - -When an alert matches a condition, the rule is marked as _Active_ and assigned an action group. The actions in that group are triggered. -When the condition is no longer detected, the rule is assigned to the _Recovered_ action group, which triggers any actions assigned to that group. - -**Run When** allows you to assign an action to an action group. This will trigger the action in accordance with your **Notify** setting. - -Each action must specify a <> instance. If no connectors exist for that action type, click *Add connector* to create one. - -Each action type exposes different properties. For example an email action allows you to set the recipients, the subject, and a message body in markdown format. See <> for details on the types of actions provided by {kib} and their properties. - -[role="screenshot"] -image::images/rule-flyout-action-details.png[UI for defining an email action] - -[float] -[[defining-alerts-actions-variables]] -==== Action variables -Using the https://mustache.github.io/[Mustache] template syntax `{{variable name}}`, you can pass rule values at the time a condition is detected to an action. You can access the list of available variables using the "add variable" button. Although available variables differ by rule type, all rule types pass the following variables: - -`rule.id`:: The ID of the rule. -`rule.name`:: The name of the rule. -`rule.spaceId`:: The ID of the space for the rule. -`rule.tags`:: The list of tags applied to the rule. -`date`:: The date the rule scheduled the action, in ISO format. -`alert.id`:: The ID of the alert that scheduled the action. -`alert.actionGroup`:: The ID of the action group of the alert that scheduled the action. -`alert.actionSubgroup`:: The action subgroup of the alert that scheduled the action. -`alert.actionGroupName`:: The name of the action group of the alert that scheduled the action. -`kibanaBaseUrl`:: The configured <>. If not configured, this will be empty. - -[role="screenshot"] -image::images/rule-flyout-action-variables.png[Passing rule values to an action] - -Some cases exist where the variable values will be "escaped", when used in a context where escaping is needed: - -- For the <> connector, the `message` action configuration property escapes any characters that would be interpreted as Markdown. -- For the <> connector, the `message` action configuration property escapes any characters that would be interpreted as Slack Markdown. -- For the <> connector, the `body` action configuration property escapes any characters that are invalid in JSON string values. - -Mustache also supports "triple braces" of the form `{{{variable name}}}`, which indicates no escaping should be done at all. Care should be used when using this form, as it could end up rendering the variable content in such a way as to make the resulting parameter invalid or formatted incorrectly. - -Each rule type defines additional variables as properties of the variable `context`. For example, if a rule type defines a variable `value`, it can be used in an action parameter as `{{context.value}}`. - -For diagnostic or exploratory purposes, action variables whose values are objects, such as `context`, can be referenced directly as variables. The resulting value will be a JSON representation of the object. For example, if an action parameter includes `{{context}}`, it will expand to the JSON representation of all the variables and values provided by the rule type. - -You can attach more than one action. Clicking the "Add action" button will prompt you to select another rule type and repeat the above steps again. - -[role="screenshot"] -image::images/rule-flyout-add-action.png[You can add multiple actions on a rule] - -[NOTE] -============================================== -Actions are not required on rules. You can run a rule without actions to understand its behavior, and then <> later. -============================================== - -[float] -=== Manage rules +==== General rule details -To modify a rule after it was created, including muting or disabling it, use the <>. +This content has been moved to <>. \ No newline at end of file diff --git a/docs/user/alerting/images/individual-mute-disable.png b/docs/user/alerting/images/individual-mute-disable.png index 0ed2bfc0186c0..c9d8cd666f1d8 100644 Binary files a/docs/user/alerting/images/individual-mute-disable.png and b/docs/user/alerting/images/individual-mute-disable.png differ diff --git a/docs/user/alerting/images/rule-flyout-action-no-connector.png b/docs/user/alerting/images/rule-flyout-action-no-connector.png new file mode 100644 index 0000000000000..b8b0864e04226 Binary files /dev/null and b/docs/user/alerting/images/rule-flyout-action-no-connector.png differ diff --git a/docs/user/alerting/index.asciidoc b/docs/user/alerting/index.asciidoc index a331f1d5606f7..68cf3ee070b08 100644 --- a/docs/user/alerting/index.asciidoc +++ b/docs/user/alerting/index.asciidoc @@ -1,8 +1,8 @@ include::alerting-getting-started.asciidoc[] include::alerting-setup.asciidoc[] +include::create-and-manage-rules.asciidoc[] include::defining-rules.asciidoc[] include::rule-management.asciidoc[] -include::rule-details.asciidoc[] include::stack-rules.asciidoc[] include::domain-specific-rules.asciidoc[] include::alerting-troubleshooting.asciidoc[] diff --git a/docs/user/alerting/map-rules/geo-rule-types.asciidoc b/docs/user/alerting/map-rules/geo-rule-types.asciidoc index 4b17145c2d149..eee7b59252205 100644 --- a/docs/user/alerting/map-rules/geo-rule-types.asciidoc +++ b/docs/user/alerting/map-rules/geo-rule-types.asciidoc @@ -30,8 +30,8 @@ than the current time minus the amount of the interval. If data older than [float] ==== Creating a geo rule -Click the *Create* button in the <>. -Complete the <>. +Click the *Create* button in the <>. +Complete the <>. [role="screenshot"] image::user/alerting/images/alert-types-tracking-select.png[Choosing a tracking rule type] diff --git a/docs/user/alerting/rule-details.asciidoc b/docs/user/alerting/rule-details.asciidoc deleted file mode 100644 index 6e743595e5c33..0000000000000 --- a/docs/user/alerting/rule-details.asciidoc +++ /dev/null @@ -1,33 +0,0 @@ -[role="xpack"] -[[rule-details]] -== Rule details - - -The *Rule details* page tells you about the state of the rule and provides granular control over the actions it is taking. - -[role="screenshot"] -image::images/rule-details-alerts-active.png[Rule details page with three alerts] - -In this example, the rule detects when a site serves more than a threshold number of bytes in a 24 hour period. Three sites are above the threshold. These are called alerts - occurrences of the condition being detected - and the alert name, status, time of detection, and duration of the condition are shown in this view. - -Upon detection, each alert can trigger one or more actions. If the condition persists, the same actions will trigger either on the next scheduled rule check, or (if defined) after the re-notify period on the rule has passed. To prevent re-notification, you can suppress future actions by clicking on the eye icon to mute an individual alert. Muting means that the rule checks continue to run on a schedule, but that alert will not trigger any action. - -[role="screenshot"] -image::images/rule-details-alert-muting.png[Muting an alert] - -Alerts will come and go from the list depending on whether they meet the rule conditions or not - unless they are muted. If a muted instance no longer meets the rule conditions, it will appear as inactive in the list. This prevents an alert from triggering actions if it reappears in the future. - -[role="screenshot"] -image::images/rule-details-alerts-inactive.png[Rule details page with three inactive alerts] - -If you want to suppress actions on all current and future alerts, you can mute the entire rule. Rule checks continue to run and the alert list will update as alerts activate or deactivate, but no actions will be triggered. - -[role="screenshot"] -image::images/rule-details-muting.png[Use the mute toggle to suppress all actions on current and future alerts] - -You can also disable a rule altogether. When disabled, the rule stops running checks altogether and will clear any alerts it is tracking. You may want to disable rules that are not currently needed to reduce the load on {kib} and {es}. - -[role="screenshot"] -image::images/rule-details-disabling.png[Use the disable toggle to turn off rule checks and clear alerts tracked] - -* For further information on alerting concepts and examples, see <>. diff --git a/docs/user/alerting/rule-management.asciidoc b/docs/user/alerting/rule-management.asciidoc index b908bd03b0992..d6349a60e08eb 100644 --- a/docs/user/alerting/rule-management.asciidoc +++ b/docs/user/alerting/rule-management.asciidoc @@ -2,62 +2,4 @@ [[alert-management]] == Managing rules - -The *Rules* tab provides a cross-app view of alerting. Different {kib} apps like {observability-guide}/create-alerts.html[*Observability*], {security-guide}/prebuilt-rules.html[*Security*], <> and <> can offer their own rules. The *Rules* tab provides a central place to: - -* <> rules -* <> including enabling/disabling, muting/unmuting, and deleting -* Drill-down to <> - -[role="screenshot"] -image:images/rules-and-connectors-ui.png[Example rule listing in the Rules and Connectors UI] - -For more information on alerting concepts and the types of rules and connectors available, see <>. - -[float] -=== Finding rules - -The *Rules* tab lists all rules in the current space, including summary information about their execution frequency, tags, and type. - -The *search bar* can be used to quickly find rules by name or tag. - -[role="screenshot"] -image::images/rules-filter-by-search.png[Filtering the rules list using the search bar] - -The *type* dropdown lets you filter to a subset of rule types. - -[role="screenshot"] -image::images/rules-filter-by-type.png[Filtering the rules list by types of rule] - -The *Action type* dropdown lets you filter by the type of action used in the rule. - -[role="screenshot"] -image::images/rules-filter-by-action-type.png[Filtering the rule list by type of action] - -[float] -[[create-edit-rules]] -=== Creating and editing rules - -Many rules must be created within the context of a {kib} app like <>, <>, or <>, but others are generic. Generic rule types can be created in the *Rules* management UI by clicking the *Create* button. This will launch a flyout that guides you through selecting a rule type and configuring its properties. Refer to <> for details on what types of rules are available and how to configure them. - -After a rule is created, you can re-open the flyout and change a rule's properties by clicking the *Edit* button shown on each row of the rule listing. - - -[float] -[[controlling-rules]] -=== Controlling rules - -The rule listing allows you to quickly mute/unmute, disable/enable, and delete individual rules by clicking the action button. - -[role="screenshot"] -image:images/individual-mute-disable.png[The actions button allows an individual rule to be muted, disabled, or deleted] - -These operations can also be performed in bulk by multi-selecting rules and clicking the *Manage rules* button: - -[role="screenshot"] -image:images/bulk-mute-disable.png[The Manage rules button lets you mute/unmute, enable/disable, and delete in bulk] - -[float] -=== Required permissions - -Access to rules is granted based on your privileges to alerting-enabled features. See <> for more information. +This content has been moved to <>. \ No newline at end of file diff --git a/docs/user/alerting/stack-rules/es-query.asciidoc b/docs/user/alerting/stack-rules/es-query.asciidoc index c62ebbf4bf2bc..5615c79a6c9c7 100644 --- a/docs/user/alerting/stack-rules/es-query.asciidoc +++ b/docs/user/alerting/stack-rules/es-query.asciidoc @@ -7,7 +7,7 @@ The {es} query rule type runs a user-configured {es} query, compares the number [float] ==== Create the rule -Fill in the <>, then select *{es} query*. +Fill in the <>, then select *{es} query*. [float] ==== Define the conditions @@ -22,12 +22,12 @@ Size:: This clause specifies the number of documents to pass to the configured a {es} query:: This clause specifies the ES DSL query to execute. The number of documents that match this query will be evaulated against the threshold condition. Aggregations are not supported at this time. Threshold:: This clause defines a threshold value and a comparison operator (`is above`, `is above or equals`, `is below`, `is below or equals`, or `is between`). The number of documents that match the specified query is compared to this threshold. -Time window:: This clause determines how far back to search for documents, using the *time field* set in the *index* clause. Generally this value should be set to a value higher than the *check every* value in the <>, to avoid gaps in detection. +Time window:: This clause determines how far back to search for documents, using the *time field* set in the *index* clause. Generally this value should be set to a value higher than the *check every* value in the <>, to avoid gaps in detection. [float] ==== Add action variables -<> to run when the rule condition is met. The following variables are specific to the {es} query rule. You can also specify <>. +<> to run when the rule condition is met. The following variables are specific to the {es} query rule. You can also specify <>. `context.title`:: A preconstructed title for the rule. Example: `rule term match alert query matched`. `context.message`:: A preconstructed message for the rule. Example: + diff --git a/docs/user/alerting/stack-rules/index-threshold.asciidoc b/docs/user/alerting/stack-rules/index-threshold.asciidoc index e152ee7cb1deb..8c45c158414f4 100644 --- a/docs/user/alerting/stack-rules/index-threshold.asciidoc +++ b/docs/user/alerting/stack-rules/index-threshold.asciidoc @@ -7,7 +7,7 @@ The index threshold rule type runs an {es} query. It aggregates field values fro [float] ==== Create the rule -Fill in the <>, then select *Index Threshold*. +Fill in the <>, then select *Index Threshold*. [float] ==== Define the conditions @@ -21,7 +21,7 @@ Index:: This clause requires an *index or index pattern* and a *time field* that When:: This clause specifies how the value to be compared to the threshold is calculated. The value is calculated by aggregating a numeric field a the *time window*. The aggregation options are: `count`, `average`, `sum`, `min`, and `max`. When using `count` the document count is used, and an aggregation field is not necessary. Over/Grouped Over:: This clause lets you configure whether the aggregation is applied over all documents, or should be split into groups using a grouping field. If grouping is used, an <> will be created for each group when it exceeds the threshold. To limit the number of alerts on high cardinality fields, you must specify the number of groups to check against the threshold. Only the *top* groups are checked. Threshold:: This clause defines a threshold value and a comparison operator (one of `is above`, `is above or equals`, `is below`, `is below or equals`, or `is between`). The result of the aggregation is compared to this threshold. -Time window:: This clause determines how far back to search for documents, using the *time field* set in the *index* clause. Generally this value should be to a value higher than the *check every* value in the <>, to avoid gaps in detection. +Time window:: This clause determines how far back to search for documents, using the *time field* set in the *index* clause. Generally this value should be to a value higher than the *check every* value in the <>, to avoid gaps in detection. If data is available and all clauses have been defined, a preview chart will render the threshold value and display a line chart showing the value for the last 30 intervals. This can provide an indication of recent values and their proximity to the threshold, and help you tune the clauses. @@ -31,7 +31,7 @@ image::user/alerting/images/rule-types-index-threshold-preview.png[Five clauses [float] ==== Add action variables -<> to run when the rule condition is met. The following variables are specific to the index threshold rule. You can also specify <>. +<> to run when the rule condition is met. The following variables are specific to the index threshold rule. You can also specify <>. `context.title`:: A preconstructed title for the rule. Example: `rule kibana sites - high egress met threshold`. `context.message`:: A preconstructed message for the rule. Example: + diff --git a/docs/user/introduction.asciidoc b/docs/user/introduction.asciidoc index 25780d303eec4..82ca11f2162fd 100644 --- a/docs/user/introduction.asciidoc +++ b/docs/user/introduction.asciidoc @@ -195,7 +195,7 @@ When the rule triggers, you can send a notification to a system that is part of your daily workflow. {kib} integrates with email, Slack, PagerDuty, and ServiceNow, to name a few. -A dedicated view for creating, searching, and editing rules is in <>. +A dedicated view for creating, searching, and editing rules is in <>. [role="screenshot"] image::images/rules-and-connectors.png[Rules and Connectors view] @@ -437,7 +437,7 @@ the <>. |< Data>> |Set up rules -|< Rules and Connectors>> +|< Rules and Connectors>> |Organize your workspace and users |< Spaces>> diff --git a/docs/user/management.asciidoc b/docs/user/management.asciidoc index 72c1d6503ceb8..1fa8c1bffa502 100644 --- a/docs/user/management.asciidoc +++ b/docs/user/management.asciidoc @@ -75,7 +75,7 @@ You can add and remove remote clusters, and check their connectivity. |=== | <> -| Centrally <> across {kib}. Create and <> across {kib}. Create and <> for triggering actions. | <> diff --git a/docs/user/monitoring/kibana-alerts.asciidoc b/docs/user/monitoring/kibana-alerts.asciidoc index c8735f2fdf7c3..53a5a56f2883d 100644 --- a/docs/user/monitoring/kibana-alerts.asciidoc +++ b/docs/user/monitoring/kibana-alerts.asciidoc @@ -26,8 +26,6 @@ and display a notification in the UI. [role="screenshot"] image::user/monitoring/images/monitoring-kibana-alerting-notification.png["{kib} alerting notifications in {stack-monitor-app}"] -NOTE: To review and modify all available rules, use *Enter setup mode* on the *Cluster overview* page in *{stack-monitor-app}* - [role="screenshot"] image::user/monitoring/images/monitoring-kibana-alerting-setup-mode.png["Modify {kib} alerting rules in {stack-monitor-app}"] diff --git a/docs/user/production-considerations/alerting-production-considerations.asciidoc b/docs/user/production-considerations/alerting-production-considerations.asciidoc index 6294a4fe6f14a..bd19a11435a99 100644 --- a/docs/user/production-considerations/alerting-production-considerations.asciidoc +++ b/docs/user/production-considerations/alerting-production-considerations.asciidoc @@ -19,7 +19,7 @@ When relying on rules and actions as mission critical services, make sure you fo By default, each {kib} instance polls for work at three second intervals, and can run a maximum of ten concurrent tasks. These tasks are then run on the {kib} server. -Rules are recurring background tasks which are rescheduled according to the <> on completion. +Rules are recurring background tasks which are rescheduled according to the <> on completion. Actions are non-recurring background tasks which are deleted on completion. For more details on Task Manager, see <>. @@ -42,7 +42,7 @@ As rules and actions leverage background tasks to perform the majority of work, When estimating the required task throughput, keep the following in mind: -* Each rule uses a single recurring task that is scheduled to run at the cadence defined by its <>. +* Each rule uses a single recurring task that is scheduled to run at the cadence defined by its <>. * Each action uses a single task. However, because <>, alerts can generate a large number of non-recurring tasks. It is difficult to predict how much throughput is needed to ensure all rules and actions are executed at consistent schedules. diff --git a/src/core/public/doc_links/doc_links_service.ts b/src/core/public/doc_links/doc_links_service.ts index 5833f018c92f0..047eda86b538b 100644 --- a/src/core/public/doc_links/doc_links_service.ts +++ b/src/core/public/doc_links/doc_links_service.ts @@ -255,7 +255,7 @@ export class DocLinksService { guide: `${ELASTIC_WEBSITE_URL}guide/en/observability/${DOC_LINK_VERSION}/index.html`, }, alerting: { - guide: `${KIBANA_DOCS}alert-management.html`, + guide: `${KIBANA_DOCS}create-and-manage-rules.html`, actionTypes: `${KIBANA_DOCS}action-types.html`, emailAction: `${KIBANA_DOCS}email-action-type.html`, emailActionConfig: `${KIBANA_DOCS}email-action-type.html`, diff --git a/x-pack/plugins/triggers_actions_ui/public/application/home.test.tsx b/x-pack/plugins/triggers_actions_ui/public/application/home.test.tsx index 0e1c27c1e6768..3594374a54f16 100644 --- a/x-pack/plugins/triggers_actions_ui/public/application/home.test.tsx +++ b/x-pack/plugins/triggers_actions_ui/public/application/home.test.tsx @@ -37,7 +37,7 @@ describe('home', () => { const documentationLink = wrapper.find('[data-test-subj="documentationLink"]'); expect(documentationLink.exists()).toBeTruthy(); expect(documentationLink.first().prop('href')).toEqual( - 'https://www.elastic.co/guide/en/kibana/mocked-test-branch/alert-management.html' + 'https://www.elastic.co/guide/en/kibana/mocked-test-branch/create-and-manage-rules.html' ); }); });