About action policies

Note

Looking for Kibana Classic Alerting? Refer to the Kibana Classic Alerting overview.

In Kibana Universal Alerting, an action policy is the gating layer between an alert and a workflow. It decides whether and when to invoke a workflow by running the alert through a sequence of gates, and a workflow runs only once the alert clears every gate.

Note

To use workflows, your role must have the appropriate privileges and your subscription must include workflows. Refer to the subscription page for Elastic Cloud and Elastic Stack/self-managed for a breakdown of available features by tier.

A rule detects a condition and opens alerts. A rule doesn't store which action policies apply to its alerts. Instead, Kibana evaluates each action policy in the space against every eligible alert, and invokes a workflow for the ones that pass every gate.

Because of that separation, a single action policy can apply to alerts from many rules. An action policy scoped to severity: "critical" applies to every critical alert, regardless of which rule produced it. The separation also means you change how alerts are routed by editing the action policy, not the rule's detection logic.

To narrow which alerts an action policy applies to, set its scope. An action policy with an empty scope applies to every eligible alert in the space.

To apply an action policy to specific rules, give the policy and those rules the same routing tag. A policy applies to alerts from every rule that has at least one of its routing tags, including rules you tag after you create the policy. The link doesn't depend on the rule's ID, name, or rule tags. You can rename a rule or reorganize its rule tags without changing which policies apply.

A workflow runs only when the alert passes every gate. Kibana checks the gates in this order:

Gate What it checks
Alert eligibility Whether the alert is acknowledged, snoozed, resolved, or in a maintenance window. Any of these stops it.
Policy scope Whether the alert's rule has at least one of the policy's routing tags, and whether the alert matches the policy's KQL expression. If the policy has both, the alert has to pass both. An empty scope passes every eligible alert in the space.
Match conditions Whether the alert matches the policy's KQL expression. An empty expression passes every eligible alert in the space.
Frequency Whether a workflow already ran for the alert's notification group within the policy's frequency interval. If it did, the alert waits.

If any gate stops the alert, Kibana doesn't invoke a workflow for that action policy. Multiple action policies can apply to the same alert, and Kibana checks the gates separately for each one, with no precedence or merging between them.

An alert blocked by one action policy can still invoke a workflow through a second action policy with different conditions. If no action policy applies to an alert, no workflow is invoked and no notification is sent.

Kibana runs a background process called the dispatcher that checks for eligible alerts on a short interval (around 5 seconds) and evaluates action policies against them. The dispatcher runs on its own cycle, separate from the rule schedule, so a notification can arrive a few seconds after the rule that produced the alert.

On each cycle, the dispatcher works through the following steps:

Step Action
1 Collect the alerts that pass the eligibility check, and the action policies that are enabled and not snoozed.
2 Run each action policy through the remaining gates, stopping that policy at the first gate the alert fails. A failure in one action policy doesn't stop the others.
3 Invoke the workflows for each notification group that clears every gate.
Tip

If an action policy already applied to an alert, a severity change does not re-trigger it. A severity change can still bring the alert into a different action policy's scope for the first time and invoke a workflow. For details and examples, refer to Manage severity escalation notifications.