diff --git a/explore-analyze/alerting/kibana-alerting-experimental/notifications.md b/explore-analyze/alerting/kibana-alerting-experimental/notifications.md index 8b8d82b793..ee345ad611 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/notifications.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/notifications.md @@ -17,20 +17,25 @@ This page explains how action policies work. For creating and configuring them s ## What is an action policy [action-policies] -An action policy is a saved object in your space that controls notification routing. It's not attached to a rule. It's global within the space, so when an episode is produced, the system evaluates all enabled policies in the space that are not snoozed and decides which ones apply. +An action policy is a saved object in your space that controls notification routing. Policies can be **global** or **per-rule**: + +- **Global** policies apply to all episodes in the space, from any rule. When an episode is produced, the dispatcher evaluates all enabled global policies that are not snoozed. Global is the default type and suits most use cases. +- **Per-rule** policies are scoped to a single rule. They apply only to episodes produced by that specific rule. Use a per-rule policy when routing is specific to one rule and you don't want it to affect other rules in the space. The rule association is set at creation and cannot be changed. Each policy has four controls: | Control | What it does | | --- | --- | -| Match conditions (optional KQL) | Filters which episodes this policy applies to. An empty match condition matches all episodes in the space. | -| Notify per (grouping) | Controls how episodes batch into notifications: one per episode, one per notification group (Notify per **Group**), or one digest for all. | +| Match conditions (optional KQL) | Filters which episodes this policy applies to. An empty match condition matches all episodes covered by the policy's scope. | +| Notify per | Controls how episodes batch into notifications: one per episode, one per notification group using **Group** mode, or one digest for all. | | Frequency | Controls how often the policy can notify for the same notification group. | | Destinations | One or more workflows to invoke when all conditions are met. | ## How policies apply to rules -Action policies don't reference rules directly. You scope a policy using KQL over episode and rule fields, for example `rule.labels: "checkout"` or `data.severity: "critical"`. A policy applies to every matching episode in the space, from any rule. +**Global policies** don't reference rules directly. You scope them using KQL over episode and rule fields, for example `rule.tags: "checkout"` or `data.severity: "critical"`. A global policy applies to every matching episode in the space, from any rule. + +**Per-rule policies** are bound to a specific rule at creation. They apply only to episodes from that rule, and you can still use match conditions to filter further within that rule's episodes. Multiple policies can match the same episode, and each runs independently. There's no precedence or merging between them. If no policy matches an episode, no notification is sent. This is intentional. @@ -58,20 +63,20 @@ Each notification attempt results in one of the following outcomes. | --- | --- | | `dispatched` | A notification was sent. | | `throttled` | Dispatch was suppressed because the **frequency** interval had not elapsed. | -| `suppressed` | The episode was suppressed before dispatch (acknowledged, snoozed, or deactivated). | -| `unmatched` | No policy matched this episode; no workflow ran. | +| `suppressed` | Dispatch was blocked before the notification went out. The episode was acknowledged, snoozed, or deactivated, or the space is currently in a maintenance window. | +| `unmatched` | No policy matched this episode and no workflow ran. | | `error` | Processing failed. Check {{kib}} logs. | You can query these outcomes in Discover through the `.alert-actions` data stream. ## Why policies are separate from rules -Rules don't own policies. A rule can't say "notify team X when it fires." Instead, team X creates an action policy that uses a KQL matcher to pick up matching episodes. - -This design means: -- One policy can cover episodes from many rules. +Policies are independent of rules, which means: +- One global policy can cover episodes from many rules. For example, a policy matching `data.severity: "critical"` applies regardless of which rule produced the episode. - You can update routing without touching any rule. -- Rules can be created without any notification policy, which is useful for testing. +- Rules can be created without any action policy, which is useful for testing. + +When you do need routing that's specific to one rule, create a per-rule policy and bind it to that rule at creation. When you're ready to route notifications, go to [Create and configure an action policy](notifications/create-configure-action-policy.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/notifications/action-policy-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/notifications/action-policy-reference.md index 82baa4b8ab..74b5e4fb0a 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/notifications/action-policy-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/notifications/action-policy-reference.md @@ -23,6 +23,7 @@ Use these fields in the **Match conditions** expression to filter which episodes | `data.*` | Dynamic payload fields sent by the rule. Available fields depend on the rule type and configuration. | `data.severity: "critical"` or `data.host.name: "web-01"` | | `rule.id` | Unique identifier for the rule that generated the episode. | `rule.id: "rule-001"` | | `rule.name` | Display name of the rule. | `rule.name: "High CPU"` | +| `rule.tags` | Tags attached to the rule. Use to match episodes from rules with a specific tag. | `rule.tags: "payment-service"` | | `rule.labels` | Key-value labels attached to the rule. Use dot notation to target a specific label key. | `rule.labels.env: "production"` | @@ -46,7 +59,7 @@ Use match conditions to route different episodes to different policies, for exam | Notify per | What it does | Available Frequency options | |---|---|---| | Episode | One notification per episode. | - On status change
- On status change + repeat at interval
- Every evaluation | -| Group | Bundle episodes that share a field value. Specify **Group by** (for example `data.service.name` or `data.host.name`). | - At most once every…
- Every evaluation | +| Group | Bundle episodes that share a field value. Specify a **Group by** field such as `data.service.name` or `data.host.name`. | - At most once every…
- Every evaluation | | Digest | One notification for all matching episodes combined. | Every evaluation | ::: diff --git a/explore-analyze/alerting/kibana-alerting-experimental/notifications/manage-action-policies.md b/explore-analyze/alerting/kibana-alerting-experimental/notifications/manage-action-policies.md index 2380f0db3e..4039405c58 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/notifications/manage-action-policies.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/notifications/manage-action-policies.md @@ -5,21 +5,28 @@ applies_to: serverless: preview products: - id: kibana -description: "Enable, disable, snooze, maintenance windows, bulk actions, and API key rotation for action policies in the {{alerting-v2}}." +description: "View policy details, enable, disable, snooze, review execution history, and rotate API keys for action policies in the {{alerting-v2}}." --- # Manage action policies -Action policies are part of the {{alerting-v2}} in {{kib}}. This page covers how to enable and disable policies, snooze them during planned outages, and rotate their API keys. +Action policies are part of the {{alerting-v2}} in {{kib}}. This page covers how to view policy details, enable and disable policies, snooze them during planned outages, rotate their API keys, and review execution history. -## Enable, snooze, and maintenance +## View policy details + +From the **Action policies** list, you can open a policy to see its full configuration, including match conditions, grouping mode, frequency, and destinations. You can also edit, clone, delete, enable, disable, snooze, or update its API key without leaving the list page. + +## Execution history + +The dispatcher records the outcome of every notification attempt for each policy. To investigate delivery issues or audit which policies ran for an episode, query the `.alert-actions` data stream in Discover and filter by `outcome` or `policy_id`. For a description of each outcome, refer to [Dispatch outcomes](action-policy-reference.md#dispatch-outcomes). + +## Enable and snooze You can disable a policy so it is not evaluated for new episodes. You can snooze a policy for a defined window so that it does not dispatch notifications during that period. Policies that are not enabled or are snoozed are skipped when the dispatcher evaluates policies. ### Maintenance windows [maintenance-windows] - -Maintenance windows are scheduled periods during which a policy does not dispatch notifications. They are configured on the action policy alongside snooze and other policy controls, not on the rule. Rule evaluation continues and alert episodes can still be recorded in `.rule-events`. Only dispatch through that policy pauses. Use maintenance windows for planned deployments, infrastructure changes, or recurring quiet periods. +During a [maintenance window](../../alerts/maintenance-windows.md), action policies stop dispatching notifications automatically. No policy configuration is required. Rule evaluation continues and alert episodes are still recorded in `.rule-events`. Maintenance windows are configured separately, not on the action policy. ## Update API keys