=== What is a rule?

For example, when monitoring a set of servers, a rule might check for average CPU usage > 0.9 on each server for the last two minutes (condition), checked every minute (schedule), sending a warning email message via SMTP with subject `CPU on {{server}} is high` (action).

Under the hood, {kib} rules detect conditions by running a javascript function on the {kib} server, which gives it the flexibility to support a wide range of conditions, anything from the results of a simple {es} query to heavy computations involving data from multiple sources or external systems.

* the *connector type*: the type of service or integration to use

* the connection for that type by referencing a <<alerting-concepts-connectors, connector>>

* a mapping of rule values to properties exposed for that type of action

When the rule detects the condition, it creates an <<alerting-concepts-alert-instances, alert>> containing the details of the condition, renders the template with these details such as server name, and executes the action on the {kib} server by invoking the `email` connector type.

[[alerting-concepts-alert-instances]]

[float]

[[alerting-concepts-suppressing-duplicate-notifications]]

=== Suppressing duplicate notifications

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:

* 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 frequent re-notification. Operations like muting and throttling can be applied at the alert level. If we set the rule re-notify interval to 5 minutes, we reduce noise by only getting emails for new servers that 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.

=== Summary

== Setup and prerequisites

If you are using an *on-premises* Elastic Stack deployment:

* In the kibana.yml configuration file, add the <<general-alert-action-settings,`xpack.encryptedSavedObjects.encryptionKey`>> setting.

* For emails to have a footer with a link back to {kib}, set the <<server-publicBaseUrl, `server.publicBaseUrl`>> configuration setting.

If you are using an *on-premises* Elastic Stack deployment with <<using-kibana-with-security, *security*>>:

* You must enable Transport Layer Security (TLS) for communication <<configuring-tls-kib-es, between {es} and {kib}>>. {kib} alerting uses <<api-keys, API keys>> to secure background rule checks and actions, and API keys require {ref}/configuring-tls.html#tls-http[TLS on the HTTP interface]. A proxy will not suffice.

[float]

[[alerting-setup-production]]

== Production considerations and scaling guidance

When relying on alerting and actions as mission critical services, make sure you follow the <<alerting-production-considerations,Alerting production considerations>>.

See <<alerting-scaling-guidance>> for more information on the scalability of {kib} alerting.

[float]

[[alerting-security]]

== Security

To access alerting in a space, a user must have access to one of the following features:

* Alerting

* <<xpack-apm,*APM*>>

* <<logs-app,*Logs*>>

* <<xpack-ml,*{ml-cap}*>>

* <<metrics-app,*Metrics*>>

* <<xpack-siem,*Security*>>

* <<uptime-app,*Uptime*>>

See <<kibana-feature-privileges, feature privileges>> for more information on configuring roles that provide access to these features.

Also note that a user will need +read+ privileges for the *Actions and Connectors* feature to attach actions to a rule or to edit a rule that has an action attached to it.

[float]

[[alerting-spaces]]

=== Space isolation

Rules and connectors are isolated to the {kib} space in which they were created. A rule or connector created in one space will not be visible in another.

[float]

[[alerting-authorization]]

=== Authorization

Rules, including all background detection and the actions they generate are authorized using an <<api-keys, API key>> associated with the last user to edit the rule. Upon creating or modifying a rule, an API key is generated for that user, capturing a snapshot of their privileges at that moment in time. The API key is then used to run all background tasks associated with the rule including detection checks and executing actions.

[IMPORTANT]

[float]

[[alerting-restricting-actions]]

=== Restricting actions

For security reasons you may wish to limit the extent to which {kib} can connect to external services. <<action-settings>> allows you to disable certain <<action-types>> and allowlist the hostnames that {kib} can connect with.

--

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 <<alerting-concepts-alert-instances, alert>> 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.

setupPrerequisites: `${KIBANA_DOCS}alerting-getting-started.html#alerting-setup-prerequisites`,

`"https://www.elastic.co/guide/en/kibana/mocked-test-branch/alerting-getting-started.html#alerting-setup-prerequisites"`