116 lines
7.7 KiB
Plaintext
116 lines
7.7 KiB
Plaintext
[role="xpack"]
|
|
[[defining-alerts]]
|
|
== Defining rules
|
|
|
|
{kib} alerting rules can be created in a variety of apps including <<xpack-apm,*APM*>>, <<xpack-ml,*{ml-app}*>>, <<metrics-app,*Metrics*>>, <<xpack-siem,*Security*>>, <<uptime-app,*Uptime*>> and from the <<management,*Management*>> 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.
|
|
|
|
. <<defining-alerts-general-details, General rule details>>
|
|
. <<defining-alerts-type-conditions, Rule type and conditions>>
|
|
. <<defining-alerts-actions-details, Action type and action details>>
|
|
|
|
image::images/rule-flyout-sections.png[The three sections of a rule definition]
|
|
|
|
[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 <<alerting-production-considerations, Alerting production considerations>> for more information.
|
|
Notify:: This value limits how often actions are repeated when an alert remains active across rule checks. See <<alerting-concepts-suppressing-duplicate-notifications>> 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]
|
|
[[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 <<alerting-concepts-connectors, connector>> 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 <<action-types>> 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 <<server-publicBaseUrl, `server.publicBaseUrl`>>. 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 <<email-action-type, Email>> connector, the `message` action configuration property escapes any characters that would be interpreted as Markdown.
|
|
- For the <<slack-action-type, Slack>> connector, the `message` action configuration property escapes any characters that would be interpreted as Slack Markdown.
|
|
- For the <<webhook-action-type, Webhook>> 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 <<action-settings, configure actions>> later.
|
|
==============================================
|
|
|
|
[float]
|
|
=== Manage rules
|
|
|
|
To modify a rule after it was created, including muting or disabling it, use the <<alert-management, rule listing in the Management UI>>.
|