Clarify rule notification values (#140457)

docs/api/alerting/create_rule.asciidoc

@@ -80,11 +80,21 @@ For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`,
 after it is created.
 
 `name`::
-(Required, string) A name to reference and search.
+(Required, string) The name of the rule. While this name does not have to be
+unique, a distinctive name can help you identify a rule.
 
 `notify_when`::
-(Required, string) The condition for throttling the notification:
-`onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`.
+(Required, string) Defines how often alerts generate actions. Valid values are: 
++
+--
+
+* `onActionGroupChange`: Actions run when the alert status changes.
+* `onActiveAlert`: Actions run when the alert becomes active and at each check
+interval while the rule conditions are met.
+* `onThrottleInterval`: Actions run when the alert becomes active and at the
+interval specified in the `throttle` property while the rule conditions are met.
+
+--
 
 `params`::
 (Required, object) The parameters to pass to the rule type executor `params`
@@ -98,32 +108,19 @@ is scheduled to run. For example, `.es-query`, `.index-threshold`,
 information, refer to <<rule-types>>.
 
 `schedule`::
-(Required, object) The schedule specifying when this rule should be run, using
-one of the available schedule formats.
-+
-.Schedule formats
-[%collapsible%open]
-=====
-A schedule is structured such that the key specifies the format you wish to use
-and its value specifies the schedule.
-
-We currently support the _interval format_ which specifies the interval in
-seconds, minutes, hours or days at which the rule should run. For example:
-`{ "interval": "10s" }`, `{ "interval": "5m" }`, `{ "interval": "1h" }`, or
-`{ "interval": "1d" }`.
-
-There are plans to support multiple other schedule formats in the near future.
-=====
+(Required, object) The check interval, which specifies how frequently the rule
+conditions are checked. The interval must be specified in seconds, minutes,
+hours or days. For example: `{ "interval": "10s" }`, `{ "interval": "5m" }`,
+`{ "interval": "1h" }`, or `{ "interval": "1d" }`.
 
 `tags`::
-(Optional, string array) A list of keywords to reference and search.
+(Optional, string array) A list of tag names that are applied to a rule.
 
 `throttle`::
-(Optional, string) How often this rule should fire the same actions. This will
-prevent the rule from sending out the same notification over and over. For
-example, if a rule with a `schedule` of 1 minute stays in a triggered state for
-90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending
-90 notifications during this period.
+(Optional, string) Defines how often an alert generates repeated actions.
+This custom action interval must be specified in seconds, minutes, hours, or
+days. For example, `10m` or `1h`. This property is used only if `notify_when`
+is `onThrottleInterval`.
 
 [[create-rule-api-request-codes]]
 ===  {api-response-codes-title}

docs/user/alerting/alerting-troubleshooting.asciidoc

@@ -44,7 +44,7 @@ When creating or editing an index threshold rule, you see a graph of the data th
 [role="screenshot"]
 image::images/index-threshold-chart.png[Index Threshold chart]
 
-The end date is related to the rule interval.
+The end date is related to the check interval for the rule.
 //(IIRC, 30 “intervals” worth of time)
 You can use this view to see if the rule is getting the data you expect, and visually compare to the threshold value (a horizontal line in the graph). If the graph does not contain any lines except for the threshold line, then the rule has an issue, for example, no data is available given the specified index and fields or there is a permission error.
 Diagnosing these may be difficult - but there may be log messages for error conditions. 

docs/user/alerting/create-and-manage-rules.asciidoc

@@ -44,35 +44,25 @@ to re-open the flyout and change the rule properties.
 
 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 *{rules-ui}*. A distinctive name can help identify and find a rule.
+Name:: The name of the rule. While this name does not have to be unique, a
+distinctive name can help you identify 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
-*{rules-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. For more information, go to
-<<alerting-production-considerations>>.
-Notify:: This value limits how often actions are repeated when an alert remains
-active across rule checks. For more information, go to
-<<alerting-concepts-suppressing-duplicate-notifications>>. +
-- **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]
+organize and find rules.
+Check every:: Defines how often to evaluate the rule condition. Checks are
+queued; they run as close to the defined value as capacity allows. For more
+details, go to <<alerting-production-considerations,Alerting production considerations>>.
+Notify:: Defines how often alerts generate actions. Options include running
+actions at each check interval, only when the alert status changes, or at a
+custom action interval.
++
+--
 [[alerting-concepts-suppressing-duplicate-notifications]]
-[NOTE]
+[TIP]
 ==============================================
 Since actions are triggered 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`:
+`On check intervals`:
 
 * 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.
@@ -80,7 +70,7 @@ servers every minute for CPU usage > 0.9, and the rule is set to notify
 
 In this 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
+you set the rule notify setting to `On custom action intervals` with an interval
 of 5 minutes, you reduce noise by getting emails only every 5 minutes for
 servers that continue to exceed the threshold:
 
@@ -89,8 +79,9 @@ servers that continue to exceed the threshold:
 * 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 notify setting to `Only on status change`. 
+rule notify setting to `On status changes`. 
 ==============================================
+--
 
 [role="screenshot"]
 image::images/rule-flyout-general-details.png[alt='All rules have name, tags, check every, and notify properties in common']
@@ -225,13 +216,15 @@ Select a rule name from the rule listing to access the *Rule details* page, whic
 [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. Four 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.
+In this example, the rule detects when a site serves more than a threshold number of bytes in a 24 hour period. Four 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. Alerts come and go from the list depending on whether the rule conditions are met.
 
-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 the toggle in the *Mute* column to mute an individual alert.
+When an alert is created, it generates actions. If the conditions that caused the alert persist, the actions run again according to the rule notification settings. There are two common alert statuses:
 
-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.
+`active`:: The conditions for the rule are met, and actions should be generated according to the notification settings.
+`recovered`:: The conditions for the rule are no longer met, and recovery actions should be generated.
 
-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}.
+You can suppress future actions for a specific alert by turning on the *Mute* toggle. If a muted alert no longer meets the rule conditions, it stays in the list to avoid generating actions if the conditions recur. You can also disable a rule, which stops it from running checks and clears any alerts it was 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]
+

x-pack/plugins/triggers_actions_ui/public/application/sections/rule_form/rule_notify_when.tsx

@@ -34,7 +34,7 @@ export const NOTIFY_WHEN_OPTIONS: Array<EuiSuperSelectOption<RuleNotifyWhenType>
     inputDisplay: i18n.translate(
       'xpack.triggersActionsUI.sections.ruleForm.ruleNotifyWhen.onActionGroupChange.display',
       {
-        defaultMessage: 'Only on status change',
+        defaultMessage: 'On status changes',
       }
     ),
     'data-test-subj': 'onActionGroupChange',
@@ -42,14 +42,14 @@ export const NOTIFY_WHEN_OPTIONS: Array<EuiSuperSelectOption<RuleNotifyWhenType>
       <>
         <strong>
           <FormattedMessage
-            defaultMessage="Only on status change"
+            defaultMessage="On status changes"
             id="xpack.triggersActionsUI.sections.ruleForm.ruleNotifyWhen.onActionGroupChange.label"
           />
         </strong>
         <EuiText size="s" color="subdued">
           <p>
             <FormattedMessage
-              defaultMessage="Actions run when the alert status changes."
+              defaultMessage="Actions run if the alert status changes."
               id="xpack.triggersActionsUI.sections.ruleForm.ruleNotifyWhen.onActionGroupChange.description"
             />
           </p>
@@ -62,7 +62,7 @@ export const NOTIFY_WHEN_OPTIONS: Array<EuiSuperSelectOption<RuleNotifyWhenType>
     inputDisplay: i18n.translate(
       'xpack.triggersActionsUI.sections.ruleForm.ruleNotifyWhen.onActiveAlert.display',
       {
-        defaultMessage: 'Every time alert is active',
+        defaultMessage: 'On check intervals',
       }
     ),
     'data-test-subj': 'onActiveAlert',
@@ -70,14 +70,14 @@ export const NOTIFY_WHEN_OPTIONS: Array<EuiSuperSelectOption<RuleNotifyWhenType>
       <>
         <strong>
           <FormattedMessage
-            defaultMessage="Every time alert is active"
+            defaultMessage="On check intervals"
             id="xpack.triggersActionsUI.sections.ruleForm.ruleNotifyWhen.onActiveAlert.label"
           />
         </strong>
         <EuiText size="s" color="subdued">
           <p>
             <FormattedMessage
-              defaultMessage="Actions repeat at the rule interval when the alert is active."
+              defaultMessage="Actions run if rule conditions are met."
               id="xpack.triggersActionsUI.sections.ruleForm.ruleNotifyWhen.onActiveAlert.description"
             />
           </p>
@@ -90,7 +90,7 @@ export const NOTIFY_WHEN_OPTIONS: Array<EuiSuperSelectOption<RuleNotifyWhenType>
     inputDisplay: i18n.translate(
       'xpack.triggersActionsUI.sections.ruleForm.ruleNotifyWhen.onThrottleInterval.display',
       {
-        defaultMessage: 'On a custom action interval',
+        defaultMessage: 'On custom action intervals',
       }
     ),
     'data-test-subj': 'onThrottleInterval',
@@ -98,14 +98,14 @@ export const NOTIFY_WHEN_OPTIONS: Array<EuiSuperSelectOption<RuleNotifyWhenType>
       <>
         <strong>
           <FormattedMessage
-            defaultMessage="On a custom action interval"
+            defaultMessage="On custom action intervals"
             id="xpack.triggersActionsUI.sections.ruleForm.ruleNotifyWhen.onThrottleInterval.label"
           />
         </strong>
         <EuiText size="s" color="subdued">
           <p>
             <FormattedMessage
-              defaultMessage="Actions run using the interval you set."
+              defaultMessage="Actions run if rule conditions are met."
               id="xpack.triggersActionsUI.sections.ruleForm.ruleNotifyWhen.onThrottleInterval.description"
             />
           </p>
@@ -165,7 +165,7 @@ export const RuleNotifyWhen = ({
         position="right"
         type="questionInCircle"
         content={i18n.translate('xpack.triggersActionsUI.sections.ruleForm.renotifyWithTooltip', {
-          defaultMessage: 'Define how often to repeat the action while the rule is active.',
+          defaultMessage: 'Define how often alerts generate actions.',
         })}
       />
     </>