From 085cf67b6da8e072b45fab255bac24be8e5dc0ec Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Fri, 15 May 2026 16:46:09 -0400 Subject: [PATCH 01/23] Add experimental alerting features rules pages Adds ten pages under kibana-alerting-experimental/rules/: - rules.md: section index - author-rules.md, esql-query-patterns.md: authoring guides - create-rule-from-rule-builder.md, create-rule-from-discover.md, create-rule-with-yaml.md: creation workflows - yaml-rule-schema-reference.md: complete YAML field reference - configure-a-rule.md, view-manage-rules.md: management pages - rule-event-field-reference.md: .rule-events document field reference Cross-references to pages in later PRs are commented out with TODO notes. Co-Authored-By: Claude Sonnet 4.6 --- .../kibana-alerting-experimental/rules.md | 41 +++++ .../rules/author-rules.md | 90 ++++++++++ .../rules/configure-a-rule.md | 123 ++++++++++++++ .../rules/create-rule-from-discover.md | 36 ++++ .../rules/create-rule-from-rule-builder.md | 19 +++ .../rules/create-rule-with-yaml.md | 21 +++ .../rules/esql-query-patterns.md | 159 ++++++++++++++++++ .../rules/rule-event-field-reference.md | 131 +++++++++++++++ .../rules/view-manage-rules.md | 47 ++++++ .../rules/yaml-rule-schema-reference.md | 108 ++++++++++++ explore-analyze/toc.yml | 12 ++ 11 files changed, 787 insertions(+) create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules.md new file mode 100644 index 0000000000..ec7de84354 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules.md @@ -0,0 +1,41 @@ +--- +navigation_title: Rules +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "What rules are in the experimental alerting features, how evaluation works, and how rules connect to alerts and notifications." +--- + +# Rules in the experimental alerting features + +Rules are part of the experimental alerting features in Kibana. For rules in the existing Kibana alerting system, see [Rules in Kibana alerting](../alerts/create-manage-rules.md). + +A rule is where the experimental alerting features start. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. + +## What rules do [detection-and-notification] + + +On each run, a rule executes an {{esql}} query against your data. If the query finds a match and the rule is in Detect mode, it writes a _signal_, a point-in-time record that the condition was met. In Alert mode, it also maintains an _alert episode_ for each matched series, tracking state from first breach through recovery. + +When creating a rule, choose Detect mode to record and query results without alerting anyone, or Alert mode when you want to track issues and route notifications. + +## What rules don't do + +Rules only define *what* to detect. They don't control notifications, who gets notified, or when. That's the job of action policies — global objects, scoped to your space, that match episodes from any rule. A rule has no say in which policies pick it up. + +This separation means you can build and test a rule without anyone getting paged, update notification routing without touching the rule, and have multiple action policies respond to the same rule independently. + +% ## How rule history works + +% Rules never overwrite old data. Each evaluation appends rows to `.rule-events`, giving you a complete, queryable history of every time the condition was met, when it cleared, and what the data looked like. + +% When a rule groups by fields (for example `BY host.name`), each unique combination is its own series, identified by `group_hash`. An episode spans one lifecycle arc on a series from first breach through recovery, identified by `episode_id`. + +% You can query this history in Discover, build dashboards from it, or write follow-on rules that read `.rule-events` as a data source. + +## Next steps + +- **[Author rules](rules/author-rules.md):** Write the {{esql}} query, choose Detect or Alert mode, and structure your data sources and conditions. +- **[View and manage rules](rules/view-manage-rules.md):** Enable, disable, clone, delete, and bulk-manage rules from the rules list. \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md new file mode 100644 index 0000000000..085911e402 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md @@ -0,0 +1,90 @@ +--- +navigation_title: Author rules +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "Learn how to write ES|QL queries for rules. Choose a rule mode, structure a base query and alert condition, set thresholds, and assign severity levels." +--- + +# Author rules for the experimental alerting features [author-rules] + + +Authoring rules is part of the experimental alerting features in Kibana. Authoring a rule means deciding three things: what condition in your data counts as a problem, whether you want the rule to silently record matches or actively track issues through to resolution, and which fields to carry forward onto each alert event so you can route and triage effectively. Getting these decisions right in the query is what makes the difference between a rule that fires on everything and one that surfaces the problems that actually need attention. + +This page covers the query concepts behind a rule definition. For settings beyond the query (such as schedules, grouping, and lifecycle thresholds), refer to [Configure a rule](configure-a-rule.md). Once you understand what goes into a rule, you can write one using the [rule builder](create-rule-from-rule-builder.md), [YAML editor](create-rule-with-yaml.md), or [a Discover session](create-rule-from-discover.md). + +## Choose a rule mode + +Before creating the rule, decide what you want it to do: + +| Mode | What it does | +| --- | --- | +| Detect (`kind: signal`) | Records query matches as signals. No episodes, no notifications. Good for testing a query or building a data history without alerting anyone. | +| Alert (`kind: alert`) | Records matches and maintains alert episodes with lifecycle states. Episodes appear on the **Alerts** page and can be matched by action policies for notifications. | + +You can switch a rule's mode after creation from the rule list or rule detail page. + +## The {{esql}} query [esql-query-structure] + +Every rule has two parts to its query: the base query and the alert conditions. + +### Base query (required) +The main {{esql}} expression. It runs on every evaluation, selects data from `FROM`, shapes results with `STATS`, `WHERE`, `EVAL`, and controls which fields are stored with `KEEP`. The base query always runs, even when no breach occurs, which is what enables no-data detection and recovery. + +### Alert conditions (optional) +A `WHERE` clause applied after the base query. Only rows that pass the alert condition are treated as breaches. Without an alert condition, every row returned by the base query is a breach. + +```esql +-- Base query: compute average CPU per host +FROM metrics-* +| STATS avg_cpu = AVG(system.cpu.total.pct) BY host.name + +-- Alert condition: only rows above the threshold count as breaches +WHERE avg_cpu > 0.9 +``` + +The `KEEP` command controls which fields appear on each stored alert event. Only the fields you `KEEP` are available for policy matchers, grouping keys, and triage in the Alerts UI. + +## Data sources + +Use `FROM` to point the rule at the indices or data streams to read. The query itself defines the scope. There is no separate data source step. + +```esql +FROM logs-checkout-service-* +| WHERE http.response.status_code >= 500 +| STATS error_count = COUNT(*) BY service.name +| KEEP service.name, error_count +``` + +The [{{esql}} reference](elasticsearch://reference/query-languages/esql.md) covers all available commands and processing functions. + +## Conditions and thresholds [conditions-and-thresholds] + +The alert condition in {{esql}} defines what counts as a breach in each evaluation. + +The activation and recovery thresholds on the rule are separate from the query. They control how many consecutive breaches must occur, or how long the condition must persist, before an episode becomes active or moves back to inactive. Those settings are in [Configure a rule](configure-a-rule.md#activation-recovery-thresholds). + + + +## Severity levels [severity-levels] + +Severity is carried by convention as a field under `data.*`, for example `data.severity` or `data.priority`. Include it in your `KEEP` so it is available as a matcher field on action policies, for example `data.severity: "critical"` in a policy KQL matcher. + +There is no required severity field name or fixed value set. Use whatever convention your team aligns on, and reference those same field names in your action policies. + + + +## Next steps + +Once you understand the query structure, explore [{{esql}} query patterns](esql-query-patterns.md) for advanced use cases including SLO burn rate queries, no-data detection, persistent breach detection, and unsupported operations. + + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md new file mode 100644 index 0000000000..109c60d67e --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -0,0 +1,123 @@ +--- +navigation_title: Configure a rule +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "Configure rules in the experimental alerting features: mode, ES|QL, grouping, schedule, lookback, activation and recovery, no-data handling, tags, and evaluation." +--- + +# Configure a rule in the experimental alerting features [rule-settings] + + +Configuring rules is part of the experimental alerting features in Kibana. The {{esql}} query defines what a rule detects. The settings on this page determine whether it behaves correctly in production: how often it runs, how it groups related problems, when it opens and closes alerts, and what it does when data stops arriving. + +For query authoring, refer to [Author rules](author-rules.md). + + +:::{note} +Action policies are not configured on the rule form. You create them separately in the **Action policies** area and use KQL matchers to scope them to the episodes you want to route. The rule builder form does not link to policies. +::: + +## Rule mode [rule-mode] + +Choose a mode that matches how you want to use results: + +| Mode | Behavior | +| --- | --- | +| Detect | Signals only: the rule produces detections without alert lifecycle tracking or notifications. | +| Alert | Lifecycle tracking and notifications: alerts move through states (pending, active, recovering, and so on), and you can attach action policies so episodes dispatch through workflows. | + +Several settings on this page apply only when the rule is in Alert mode (`kind: alert`). + +## {{esql}} query [esql-query-rule] + +The rule's {{esql}} query defines what to evaluate. It has a base query and an optional alert condition. Together they drive which rows become alert events and how no-data behavior applies. See [{{esql}} query structure](author-rules.md#esql-query-structure) for how those pieces interact with no-data behavior and `KEEP`. + +## Rule grouping [rule-grouping] + + +Rule grouping splits alert event generation by one or more group key fields so that each unique combination of field values produces its own alert series. Each series has independent lifecycle tracking, recovery detection, and per-series snooze. + +Group key fields must align with the `BY` clause in your {{esql}} query's `STATS` command. See [Author rules](author-rules.md) for query patterns. + +Note that rule grouping is separate from notification grouping on an action policy, which controls how episodes batch into messages. + + + +## Schedule and lookback [schedule-lookback] + + +The schedule and lookback settings control how often a rule runs and how far back it looks when evaluating data. + +### Execution interval + +The execution interval (`schedule.every`) determines how frequently the rule evaluates. + +{{kib}} enforces a minimum interval of 5 seconds and a maximum of 365 days for duration fields (including this one). Values outside that range are rejected. + +### Lookback window + +The lookback window (`schedule.lookback`) determines the time range that the {{esql}} query covers. + +The lookback must not exceed 365 days. If the lookback is shorter than the execution interval, evaluations can miss data between runs. Use a lookback at least as long as the execution interval unless you have a deliberate reason not to. + +## Activation and recovery thresholds [activation-recovery-thresholds] + + +Activation and recovery thresholds control when alerts transition between lifecycle states. They reduce noise from short spikes and from rapid flapping between active and recovered. + +These settings are only available for Alert-mode rules (`kind: alert`). + +### Activation thresholds + +Configure activation using count, timeframe, or both: + +| Field | Description | +| --- | --- | +| `pending_count` | Consecutive breaches required | +| `pending_timeframe` | Minimum duration the condition must persist | +| `pending_operator` | How to combine count and timeframe (`AND` or `OR`) | + +Each timeframe value must be between 5 seconds and 365 days. + +### Recovery thresholds + +| Field | Description | +| --- | --- | +| `recovering_count` | Consecutive recoveries required | +| `recovering_timeframe` | Minimum duration for recovery | +| `recovering_operator` | How to combine count and timeframe (`AND` or `OR`) | + +Time frame fields use the same 5 seconds to 365 days bounds as activation timeframes. + +## No-data handling [no-data-handling] + +No-data handling controls what happens when a rule executes and the base query returns no results. Proper configuration prevents false recoveries and misleading `no_data` events when data sources stop reporting. + +### Behaviors + +Set `no_data.behavior` to one of the following values: + +| Behavior | Effect | +| --- | --- | +| `no_data` | Record a no-data event (default) | +| `last_status` | Carry forward the previous status | +| `recover` | Treat absence as recovery | + +These behaviors apply when the base query returns zero rows. They do not help when you want to *detect* that a specific host or data source has gone silent. That requires a different query approach. See [No-data detection](esql-query-patterns.md#no-data-esql-query) in the authoring guide for an {{esql}} pattern that surfaces silent sources as alert rows. + +## Tags and investigation guide [tags-investigation] + +Alert-mode rules support two optional metadata fields: + +- **Tags**: Free-form labels for filtering and organization. +- **Investigation guide**: A runbook stored with the rule so responders have context when an alert fires. + +## Evaluate rule output [evaluate-rule-output] + +Before relying on a rule in production, evaluate it against recent data by running a preview. A full evaluation surfaces how many rows the query returns, how many alert events would be generated, sample alert event documents, and a histogram of matching row counts over time. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md new file mode 100644 index 0000000000..f7d5f567c2 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md @@ -0,0 +1,36 @@ +--- +navigation_title: Using Discover +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "Turn an {{esql}} query in Discover into a rule in the experimental alerting features with pre-filled evaluation and lookback." +--- + +# Create rules from Discover [create-rules-discover] + + +Creating rules from Discover is part of the experimental alerting features in Kibana. Create experimental alerting rules directly from Discover. When you build an {{esql}} query that surfaces interesting patterns, you can convert it into a rule without rewriting the query. For the full rule form including alert mode settings and YAML toggle, refer to [Create rules using the rule builder](create-rule-from-rule-builder.md). + +## How it works [discover-rule-flow] + +Starting a rule from Discover means your query is already tested and returns the shape you expect before the rule is ever saved. Instead of drafting a query in the rule builder and hoping it works, you iterate in Discover (where you can see real results immediately) and then create the rule when the query is ready. + +When you trigger rule creation from Discover, your {{esql}} query pre-fills the rule form. The rule creation form also shows a preview panel that reflects how your query partitions results into alert series. If your query uses a `BY` clause, the preview shows the series that would be evaluated on each run. This lets you verify grouping logic against live data before committing to a schedule. + +## Preview query results before creating the rule [preview-query-discover] + + +The query preview in the rule creation flow runs your {{esql}} query against current data and displays the resulting rows. Use this to: + +- **Confirm grouping**: Check that your `BY` clause produces the series you intend — for example, one distinct series per host or per service, not a single undifferentiated result. +- **Catch unexpected output**: Verify that the query returns data in the right shape for the alert condition you plan to set. A query that returns zero rows or an unexpected field name will not behave as expected once the rule runs on a schedule. +- **Refine before committing**: Edit the query in the preview panel and re-run it without leaving the rule creation form. Once the preview looks correct, proceed to fill in the remaining settings. + + \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md new file mode 100644 index 0000000000..47f7f1a3e7 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md @@ -0,0 +1,19 @@ +--- +navigation_title: Using the rule builder +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "Create a rule with the interactive rule builder" +--- + +# Create rules using the rule builder [create-rules-rule-builder] + + +The rule builder is part of the experimental alerting features in Kibana. It is the right starting point when you're creating a rule from scratch and want inline guidance through each setting. For a full description of what each setting does, refer to [Configure a rule](configure-a-rule.md). + +If you already have a working query in Discover, you can [create a rule directly from there](create-rule-from-discover.md) without re-entering it. If you're managing rules as code or need to version-control rule definitions, use the [YAML editor](create-rule-with-yaml.md) instead. + + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md new file mode 100644 index 0000000000..f80493b6d0 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md @@ -0,0 +1,21 @@ +--- +navigation_title: Using the YAML editor +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "Define rules as YAML in the experimental alerting features for version control, infrastructure-as-code, and bulk provisioning." +--- + +# Create rules using the YAML editor [create-rules-yaml] + + +The YAML editor is part of the experimental alerting features in Kibana. It lets you define rules as text documents rather than filling in a form. Use it when you want to version-control rule definitions alongside your other configuration, manage rules through infrastructure-as-code tooling, copy or adapt a rule quickly without re-entering settings by hand, or provision many rules at once. + +If you're creating a rule from scratch and want guidance through each setting, the [rule builder](create-rule-from-rule-builder.md) is the better starting point. If you have a query already working in Discover, you can [create a rule directly from there](create-rule-from-discover.md). + +For the full list of supported YAML fields and their accepted values, refer to [YAML rule schema reference](yaml-rule-schema-reference.md). + + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md new file mode 100644 index 0000000000..dfa9bf4a87 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md @@ -0,0 +1,159 @@ +--- +navigation_title: ES|QL query patterns +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "Advanced {{esql}} query patterns for rules in the experimental alerting features: SLO burn rate, no-data detection, persistent breach, and unsupported operations." +--- + +# {{esql}} query patterns for rules in the experimental alerting features [esql-query-patterns] + + +ES|QL query patterns for rules are part of the experimental alerting features in Kibana. Some detection problems can't be expressed as a single metric compared to a fixed threshold. You might need to know whether an SLO is burning through its error budget across multiple time windows at once. Or whether a specific host has gone silent, rather than whether the query returned nothing. Or whether a condition has persisted continuously across consecutive time buckets rather than appearing once. These are structurally different problems that require different query shapes. + +Use this page when a basic `STATS ... WHERE` pattern isn't enough, or when the detection logic itself requires multi-window calculation, last-seen reasoning, or bucket-level persistence checks. If you're still learning how rules in the experimental alerting features work, start with [Author rules](author-rules.md) first. + +## Basic threshold query [threshold-query] + +A threshold query evaluates one metric over one lookback window and fires if a value crosses a limit. It is the simplest rule shape: a `STATS` aggregation followed by a `WHERE` condition. + +```esql +FROM logs-* +| STATS + // Count only error responses; count all requests for the denominator + error_count = COUNT_IF(http.response.status_code >= 500), + total_count = COUNT(*) + BY service.name +| EVAL error_rate = error_count / total_count // Compute the error rate as a fraction (0–1) +| WHERE error_rate > 0.10 // Alert condition: services above 10% error rate are breaches +| KEEP service.name, error_rate, error_count, total_count +``` + +One window, one aggregate, one threshold check. The result is either a breach or no breach for each series. + +## SLO burn rate query [slo-burn-rate-query] + +An SLO burn rate query asks a different question than a basic threshold: are you consuming your error budget faster than you can afford to? Rather than checking a single metric at a fixed limit, it calculates error rates across multiple time windows simultaneously and returns a severity level. + +### Why multiple windows + +Checking both a short window (for example, 5 minutes) and a long window (for example, 1 hour) together filters out brief spikes that do not represent a real budget threat. CRITICAL fires only when *both* the short and long burn rates exceed the threshold. The two-window requirement is what separates a genuine budget emergency from a momentary blip. + +### Query structure + +A single {{esql}} query handles all window pairs at once using conditional aggregation: + +```esql +FROM metrics-* +| WHERE @timestamp >= NOW() - 3 days // Lookback must cover the longest window pair used below. + // Keep this value in sync with the rule's lookback setting. +| STATS + // CRITICAL window pair: 5 min catches the fast signal, 1 hour confirms it's sustained + errors_5m = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 5 minutes), + total_5m = COUNT_IF(@timestamp >= NOW() - 5 minutes), + errors_1h = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 1 hour), + total_1h = COUNT_IF(@timestamp >= NOW() - 1 hour), + // HIGH window pair: 30 min fast signal, 6 hours sustained confirmation + errors_30m = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 30 minutes), + total_30m = COUNT_IF(@timestamp >= NOW() - 30 minutes), + errors_6h = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 6 hours), + total_6h = COUNT_IF(@timestamp >= NOW() - 6 hours) + BY slo.id // Each SLO is evaluated independently +| EVAL + // Compute error rates (errors as a fraction of total requests) for each window + burn_5m = errors_5m / total_5m, + burn_1h = errors_1h / total_1h, + burn_30m = errors_30m / total_30m, + burn_6h = errors_6h / total_6h +| EVAL severity = CASE( + // CRITICAL: both the fast and sustained windows exceed 14.4x the baseline error rate. + // Requiring both prevents a single brief spike from triggering a critical alert. + burn_5m > 14.4 AND burn_1h > 14.4, "CRITICAL", + // HIGH: same two-window logic at a lower threshold + burn_30m > 6.0 AND burn_6h > 6.0, "HIGH", + "none" + ) +| WHERE severity != "none" // Only breaching SLOs become alert rows +| KEEP slo.id, severity, burn_5m, burn_1h, burn_30m, burn_6h // Store fields needed for routing and triage +``` + +The burn rate multipliers (14.4×, 6×) reflect standard SLO error budget consumption rates. Adjust them to match your SLO targets. + +Because the query computes several window pairs in one pass, the lookback window on the rule must cover the longest window in the query (3 days in the example above). + + + + + +## No-data detection [no-data-esql-query] + +No-data detection inverts the normal pattern. Instead of filtering for data that meets a condition, you query for when data was *last seen* and flag sources that have gone silent. + +The technique uses a broad lookback to find all known hosts, then surfaces only those that have not reported recently: + +```esql +FROM metrics-* +| WHERE @timestamp >= NOW() - 12 hours // Broad lookback: must be wide enough that all known hosts + // have at least one event in the window under normal conditions +| STATS last_seen = MAX(@timestamp) BY host.name // Find the most recent event timestamp per host +| WHERE last_seen < NOW() - 15 minutes // Keep only hosts that have NOT reported in the last 15 minutes +| KEEP host.name, last_seen // Each returned row is a silent host — the query result itself is the alert +``` + +Every row returned is a host that has gone silent, so the base query itself drives the alert. No separate alert condition is needed. + +### Variants + +| Variant | What it detects | +|---|---| +| Host-specific | Each host that stops reporting generates its own alert series (use `BY host.name` for grouping). | +| Global | No data from any source. Omit the `BY` clause and check whether the query returns any rows at all. | +| Combined | Flags both a high-metric condition *and* silent hosts in one query using a `CASE` expression to assign a `status` field (`"alert"`, `"no data"`, or `"ok"`), then filters to only the problematic rows. | + +### Lookback window sizing + +The lookback must be wide enough that known hosts appear in the result set. If the lookback is too short, a silent host falls outside the window and is never checked. However, large lookback windows on high-frequency data streams increase query cost significantly. Start with a lookback that comfortably covers the longest expected reporting gap for your hosts, not the full history of the index. + +For no-data behavior when the entire base query returns zero rows (as opposed to detecting specific silent sources), refer to [No-data handling](configure-a-rule.md#no-data-handling). + + + +## Limitations and workarounds [esql-limitations] + +Some patterns from the classic alerting aggregation API are not directly available in {{esql}}, and some require workarounds. + +### Persistent breach detection [persistent-breach] + +A persistent breach condition detects a metric that stays above a threshold across several consecutive time buckets (for example, "CPU above 90% in all 10 of the last 10 five-minute windows"). {{esql}} can express this with bucket counting: + +```esql +FROM metrics-* +| WHERE @timestamp >= NOW() - 50 minutes // Lookback must cover all 10 buckets (10 × 5 min = 50 min) +| EVAL bucket = BUCKET(@timestamp, 5 minutes) // Assign each event to its 5-minute time bucket +| STATS + total_buckets = COUNT_DISTINCT(bucket), // How many distinct buckets exist in the window + exceeding_buckets = COUNT_DISTINCT( + CASE(system.cpu.total.pct > 0.90, bucket, null) // Count only buckets where CPU exceeded the threshold; + ) // null values are excluded by COUNT_DISTINCT + BY host.name +| WHERE total_buckets >= 10 // Require a full window of data before firing — + AND exceeding_buckets == total_buckets // guards against gaps making a partial breach look persistent; + // every bucket in the window must have breached +| KEEP host.name, total_buckets, exceeding_buckets +``` + +The rule's lookback window must cover all the buckets you want to check (50 minutes for 10 five-minute buckets in this example). If any bucket is missing from the data because the host stopped reporting briefly mid-window, `total_buckets` drops below 10 and the condition does not fire. Design the query so that gaps in reporting produce the behavior you want: either treating partial coverage as a non-breach or adjusting the `WHERE` filter to allow it. + + + +### Derivative aggregation [derivative-aggregation] + +{{esql}} does not have a `DERIVATIVE` function. In the {{es}} aggregations API, a derivative pipeline aggregation calculates the rate of change between consecutive time buckets (for example, "how fast is this counter increasing per minute?"). There is no equivalent in {{esql}} today. + +Use cases that require true per-bucket deltas (such as detecting a sudden acceleration in error rate) cannot be expressed as an {{esql}} rule at this time. Consider pre-computing deltas in an ingest pipeline or using a transform to write derived metrics to a separate index that your rule can then query with a standard threshold pattern. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md new file mode 100644 index 0000000000..ddf9bdada4 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md @@ -0,0 +1,131 @@ +--- +navigation_title: Rule and event fields +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "Reference for rule configuration fields and documents written to `.rule-events` in the experimental alerting features." +--- + +# Rule event and field reference [rule-reference] + + +Rule event fields are part of the experimental alerting features in Kibana. This page lists technical fields for rule configuration and rule event documents written to `.rule-events`. + + +:::{important} +The `.rule-events` and `.alert-actions` data streams are [system indices](/reference/glossary/index.md#glossary-system-index). {{kib}} manages their versioning, retention, and lifecycle through ILM. Older backing indices are deleted automatically when the retention window expires. Do not change mappings or index settings for these streams yourself. +::: + +## Schedule and lookback + +These fields control when a rule runs and how far back its {{esql}} query looks on each evaluation. + +| Field | Description | +|---|---| +| `schedule.every` | Execution interval; minimum 5 seconds, maximum 365 days. | +| `schedule.lookback` | Time range the {{esql}} query covers; must not exceed 365 days; should be at least `schedule.every` to avoid gaps. | + +## Activation thresholds + +These fields are only available in Alert mode. They control how many consecutive breaches, or how long a condition must persist, before an episode transitions from `pending` to `active`. + +| Field | Description | +|---|---| +| `pending_count` | Consecutive breaches required. | +| `pending_timeframe` | Minimum duration the condition must persist. | +| `pending_operator` | How to combine count and timeframe (`AND` or `OR`). | + +## Recovery thresholds + +These fields are only available in Alert mode. They control how many consecutive recoveries, or how long the condition must be clear, before an episode transitions from `recovering` to `inactive`. + +| Field | Description | +|---|---| +| `recovering_count` | Consecutive recoveries required. | +| `recovering_timeframe` | Minimum duration for recovery. | +| `recovering_operator` | How to combine count and timeframe (`AND` or `OR`). | + +## No-data handling + +These settings determine what the rule records when the {{esql}} query returns no rows on an evaluation. + +| Behavior | Effect | +|---|---| +| `no_data` (default) | Record a no-data event. | +| `last_status` | Carry forward the previous status. | +| `recover` | Treat absence as recovery. | + +## Rule grouping + +Grouping is configured in YAML. The fields listed here control how the rule partitions results into independent series, each with its own lifecycle. + +| Key | Description | +|---|---| +| `grouping.fields` | Array of field names; must align with `STATS ... BY` in the {{esql}} query. | + + + +## Rule event documents + +Each time a rule evaluates, {{kib}} writes one document per matched series to `.rule-events`. The `type` field determines the document kind: + +- **signal:** A point-in-time record that the query matched. Useful for querying history or chaining into follow-on rules. Signal documents do not include `episode.*` fields. +- **alert:** A lifecycle-tracked episode visible in the alert inbox, episode details, and triage views. Alert documents include `episode.*` fields and represent a breach that stays open until the condition clears. + +Both kinds share the base fields below. Only `alert` documents add the [Episode fields](#episode-fields) listed further down. + +:::{note} +`.rule-events` is a data stream, so it is append-only. A new document is written on every rule evaluation — existing documents are never updated. Each document is a snapshot of that moment: the `episode.status` field records the lifecycle stage the episode was in at that evaluation. To view the full history of an episode, query all documents that share the same `episode.id`. + +::: + +### Signal and alert fields + +These fields appear on all `.rule-events` documents, regardless of whether the rule is in Detect or Alert mode. + +| Field | Type | Required | Description | +|---|---|---|---| +| `@timestamp` | date | Yes | When this document was written to `.rule-events`. | +| `scheduled_timestamp` | date | No | Scheduled execution time for this rule run. | +| `rule.id` | keyword | Yes | Rule identifier. | +| `rule.version` | long | Yes | Rule version at the time this event was emitted. | +| `group_hash` | keyword | Yes | Series identity key for grouped evaluations. | +| `data` | flattened | Yes | Payload from the {{esql}} query output. Shape depends on your rule. | +| `status` | keyword | Yes | One of: `breached`, `recovered`, `no_data`. | +| `source` | keyword | Yes | Origin of this event. Product-specific identifier. | +| `type` | keyword | Yes | `signal` or `alert`. Application field on each rule event document written by {{kib}}. | + + + +:::{admonition} Fields not stored as a dedicated column +There is no top-level or nested `duration` field on `.rule-events` documents. For triage or reporting, derive duration from the alert UI or your own queries over timestamps and episode identifiers. + +::: + +### Episode fields + +These fields only appear on documents with `type: alert`, written by rules running in Alert mode. They carry the lifecycle state for the episode associated with the matched series. + +| Field | Type | Description | +|---|---|---| +| `episode.id` | keyword | Episode identifier for this series. | +| `episode.status` | keyword | One of: `inactive`, `pending`, `active`, `recovering`. | +| `episode.status_count` | long | Count of consecutive evaluations in the current `episode.status`. Only set when `episode.status` is `pending` or `recovering`. | + + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md new file mode 100644 index 0000000000..1df14b889c --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md @@ -0,0 +1,47 @@ +--- +navigation_title: View and manage rules +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "Use the rules list and rule details page in the experimental alerting features: filters, search, bulk actions, and what you find in rule conditions." +--- + +# View and manage rules in the experimental alerting features [manage-rules] + + + +Viewing and managing rules is part of the experimental alerting features in Kibana. After a rule is created, edit its settings, pause it, remove it, and more from the page listing rules. The rules list gives you search, filter, sort, and bulk actions across all rules in the space. Selecting a rule name opens its details page, where you can review the full configuration and edit or act on it directly. + +## Find and filter rules [find-filter-rules] + + +Use the search bar at the top of the rules list to find rules by name. The search field accepts plain text and matches against rule names without requiring structured query syntax — type any part of a rule name to narrow the list. Combine text search with filter controls to narrow results further by rule type, status, or tags. + +Select any column header to sort the list. Use bulk actions when you need to enable, disable, or delete multiple rules at once. + +## Rule summary flyout [rule-summary-flyout] + + +To inspect a rule without navigating away from the rules list, select the expand icon on any row. The rule summary flyout opens alongside the list and shows a snapshot of the rule: its status, last run time, recent alert episode activity, and quick actions such as enable, disable, and snooze. + +Use the flyout when you want to confirm a rule is healthy or take a quick action without committing to a full page load. To open the complete rule configuration with all settings and edit controls, select the rule name in the table row or in the flyout header. + +## Rule details page + +- **Conditions**: The full {{esql}} base query, alert condition, schedule, lookback, grouping, and recovery settings. +- **Runbook**: If the rule has an investigation guide, it appears here alongside Conditions. + +Use **Edit** to modify the rule, or the actions menu to enable, disable, clone, or delete it. + +## Disable versus snooze + +Use **Disable** when you want the rule to stop running entirely until you re-enable it. This is different from snoozing, which suppresses notifications or quiets a series or policy without stopping rule evaluation. + + + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md new file mode 100644 index 0000000000..6684ad4ccb --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md @@ -0,0 +1,108 @@ +--- +navigation_title: YAML rule schema reference +applies_to: + stack: unavailable + serverless: preview +products: + - id: kibana +description: "Complete field reference for YAML rule definitions in the experimental alerting features: required fields, metadata, schedule, grouping, state transitions, no-data handling, and duration format." +--- + +# YAML rule schema reference [yaml-rule-schema-reference] + + +YAML rule schema is part of the experimental alerting features in Kibana. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create rules using the YAML editor](create-rule-with-yaml.md). + +## Required fields + +| Field | Type | Accepted values | Description | +|---|---|---|---| +| `kind` | string | `alert` or `signal` | Whether the rule tracks ongoing episodes (`alert`) or records point-in-time observations (`signal`). | +| `metadata.name` | string | Max 256 characters | The name of the rule. | +| `schedule.every` | duration | For example, `5s`, `1m`, `5m` | How often the rule runs. Minimum interval applies. | +| `evaluation.query.base` | string | Valid {{esql}} query, max 10,000 characters | The query that checks your data on each run. | + +## Metadata fields + +| Field | Type | Accepted values | Description | +|---|---|---|---| +| `metadata.description` | string | Max 1,024 characters | Optional description of what the rule monitors. | +| `metadata.owner` | string | Max 256 characters | Team or person responsible for the rule. | +| `metadata.tags` | array of strings | Max 100 tags | Labels for filtering and organization. | + +## Schedule fields + +| Field | Type | Accepted values | Description | +|---|---|---|---| +| `schedule.lookback` | duration | For example, `5m`, `24h` | How far back in time the query searches on each run. | +| `time_field` | string | Any valid field name, max 128 characters | The timestamp field used for the lookback window filter. Defaults to `@timestamp`. | + +## Recovery policy fields + +| Field | Type | Accepted values | Description | +|---|---|---|---| +| `recovery_policy.type` | string | `no_breach` or `query` | How recovery is detected. `no_breach` recovers when the query returns no results. `query` uses a separate recovery query. | +| `recovery_policy.query.base` | string | Valid {{esql}} query | Required when `recovery_policy.type` is `query`. The query that checks whether the condition has cleared. | + + + +## State transition fields + +Only valid when `kind: alert`. Controls how many consecutive detections are required before an episode becomes active or recovers. + +| Field | Type | Accepted values | Description | +|---|---|---|---| +| `state_transition.pending_operator` | string | `AND` or `OR` | Whether both the count and timeframe must be met (`AND`) or either one (`OR`) before becoming active. | +| `state_transition.pending_count` | integer | 0 or more | Number of consecutive breaches required before the episode becomes active. | +| `state_transition.pending_timeframe` | duration | For example, `5m` | Time window within which the breach count must be met. | +| `state_transition.recovering_operator` | string | `AND` or `OR` | Whether both the count and timeframe must be met (`AND`) or either one (`OR`) before recovering. | +| `state_transition.recovering_count` | integer | 0 or more | Number of consecutive clear evaluations required before the episode recovers. | +| `state_transition.recovering_timeframe` | duration | For example, `5m` | Time window within which the recovery count must be met. | + +## Grouping fields + +| Field | Type | Accepted values | Description | +|---|---|---|---| +| `grouping.fields` | array of strings | Max 16 fields, each max 256 characters | Fields to group results by. Each unique combination becomes its own series. | + + + +## No-data fields + +| Field | Type | Accepted values | Description | +|---|---|---|---| +| `no_data.behavior` | string | `no_data`, `last_status`, or `recover` | What happens when the query returns no results. `no_data` records a no-data event. `last_status` keeps the current status. `recover` closes any active episode. | +| `no_data.timeframe` | duration | For example, `5m` | How long the query must return no results before the no-data behavior applies. | + +## Artifact fields + +| Field | Type | Accepted values | Description | +|---|---|---|---| +| `artifacts[].type` | string | For example, `runbook` | The type of artifact being attached. | +| `artifacts[].value` | string | Markdown content | The content of the artifact. Runbooks are rendered as markdown in the rule detail view. | + +## Notification policy fields + +| Field | Type | Accepted values | Description | +|---|---|---|---| +| `notification_policies[].ref` | string | Format: `policies/` | Links a notification policy to the rule. | + +## Duration format + +All duration fields accept the following units: + +| Unit | Example | Meaning | +|---|---|---| +| `s` | `30s` | Seconds | +| `m` | `5m` | Minutes | +| `h` | `1h` | Hours | +| `d` | `7d` | Days | diff --git a/explore-analyze/toc.yml b/explore-analyze/toc.yml index 2a57f93a92..5b3741c129 100644 --- a/explore-analyze/toc.yml +++ b/explore-analyze/toc.yml @@ -380,6 +380,18 @@ toc: - file: report-and-share/reporting-troubleshooting-pdf.md - file: alerting.md children: + - file: alerting/kibana-alerting-experimental/rules.md + children: + - file: alerting/kibana-alerting-experimental/rules/author-rules.md + - file: alerting/kibana-alerting-experimental/rules/esql-query-patterns.md + - file: alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md + - file: alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md + - file: alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md + children: + - file: alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md + - file: alerting/kibana-alerting-experimental/rules/configure-a-rule.md + - file: alerting/kibana-alerting-experimental/rules/view-manage-rules.md + - file: alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md - file: alerting/alerts.md children: - file: alerting/alerts/alerting-getting-started.md From a0dd896273eb572d76e462a69a8412eae27b4fd7 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Fri, 15 May 2026 17:12:17 -0400 Subject: [PATCH 02/23] Add alerting-v2 variables and replace phrase throughout Co-Authored-By: Claude Sonnet 4.6 --- docset.yml | 2 ++ .../alerting/kibana-alerting-experimental/rules.md | 8 ++++---- .../kibana-alerting-experimental/rules/author-rules.md | 4 ++-- .../rules/configure-a-rule.md | 6 +++--- .../rules/create-rule-from-discover.md | 4 ++-- .../rules/create-rule-from-rule-builder.md | 2 +- .../rules/create-rule-with-yaml.md | 4 ++-- .../rules/esql-query-patterns.md | 8 ++++---- .../rules/rule-event-field-reference.md | 4 ++-- .../rules/view-manage-rules.md | 6 +++--- .../rules/yaml-rule-schema-reference.md | 4 ++-- 11 files changed, 27 insertions(+), 25 deletions(-) diff --git a/docset.yml b/docset.yml index 5ecf676ed5..a43cb177d5 100644 --- a/docset.yml +++ b/docset.yml @@ -123,6 +123,8 @@ subs: ls-pipelines-app: "Logstash Pipelines" maint-windows-app: "Maintenance Windows" maint-windows-cap: "Maintenance windows" + alerting-v2: "experimental alerting features" + alerting-v2-cap: "Experimental alerting features" custom-roles-app: "Custom Roles" data-source: "data view" data-sources: "data views" diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules.md index ec7de84354..683510ea82 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules.md @@ -5,14 +5,14 @@ applies_to: serverless: preview products: - id: kibana -description: "What rules are in the experimental alerting features, how evaluation works, and how rules connect to alerts and notifications." +description: "What rules are in the {{alerting-v2}}, how evaluation works, and how rules connect to alerts and notifications." --- -# Rules in the experimental alerting features +# Rules in the {{alerting-v2}} -Rules are part of the experimental alerting features in Kibana. For rules in the existing Kibana alerting system, see [Rules in Kibana alerting](../alerts/create-manage-rules.md). +Rules are part of the {{alerting-v2}} in Kibana. For rules in the existing Kibana alerting system, see [Rules in Kibana alerting](../alerts/create-manage-rules.md). -A rule is where the experimental alerting features start. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. +A rule is where the {{alerting-v2}} start. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. ## What rules do [detection-and-notification] diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md index 085911e402..f4f07c0f7d 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md @@ -8,10 +8,10 @@ products: description: "Learn how to write ES|QL queries for rules. Choose a rule mode, structure a base query and alert condition, set thresholds, and assign severity levels." --- -# Author rules for the experimental alerting features [author-rules] +# Author rules for the {{alerting-v2}} [author-rules] -Authoring rules is part of the experimental alerting features in Kibana. Authoring a rule means deciding three things: what condition in your data counts as a problem, whether you want the rule to silently record matches or actively track issues through to resolution, and which fields to carry forward onto each alert event so you can route and triage effectively. Getting these decisions right in the query is what makes the difference between a rule that fires on everything and one that surfaces the problems that actually need attention. +Authoring rules is part of the {{alerting-v2}} in Kibana. Authoring a rule means deciding three things: what condition in your data counts as a problem, whether you want the rule to silently record matches or actively track issues through to resolution, and which fields to carry forward onto each alert event so you can route and triage effectively. Getting these decisions right in the query is what makes the difference between a rule that fires on everything and one that surfaces the problems that actually need attention. This page covers the query concepts behind a rule definition. For settings beyond the query (such as schedules, grouping, and lifecycle thresholds), refer to [Configure a rule](configure-a-rule.md). Once you understand what goes into a rule, you can write one using the [rule builder](create-rule-from-rule-builder.md), [YAML editor](create-rule-with-yaml.md), or [a Discover session](create-rule-from-discover.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md index 109c60d67e..e2622b3205 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -5,13 +5,13 @@ applies_to: serverless: preview products: - id: kibana -description: "Configure rules in the experimental alerting features: mode, ES|QL, grouping, schedule, lookback, activation and recovery, no-data handling, tags, and evaluation." +description: "Configure rules in the {{alerting-v2}}: mode, ES|QL, grouping, schedule, lookback, activation and recovery, no-data handling, tags, and evaluation." --- -# Configure a rule in the experimental alerting features [rule-settings] +# Configure a rule in the {{alerting-v2}} [rule-settings] -Configuring rules is part of the experimental alerting features in Kibana. The {{esql}} query defines what a rule detects. The settings on this page determine whether it behaves correctly in production: how often it runs, how it groups related problems, when it opens and closes alerts, and what it does when data stops arriving. +Configuring rules is part of the {{alerting-v2}} in Kibana. The {{esql}} query defines what a rule detects. The settings on this page determine whether it behaves correctly in production: how often it runs, how it groups related problems, when it opens and closes alerts, and what it does when data stops arriving. For query authoring, refer to [Author rules](author-rules.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md index 1df14b889c..2426578385 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md @@ -5,14 +5,14 @@ applies_to: serverless: preview products: - id: kibana -description: "Use the rules list and rule details page in the experimental alerting features: filters, search, bulk actions, and what you find in rule conditions." +description: "Use the rules list and rule details page in the {{alerting-v2}}: filters, search, bulk actions, and what you find in rule conditions." --- -# View and manage rules in the experimental alerting features [manage-rules] +# View and manage rules in the {{alerting-v2}} [manage-rules] -Viewing and managing rules is part of the experimental alerting features in Kibana. After a rule is created, edit its settings, pause it, remove it, and more from the page listing rules. The rules list gives you search, filter, sort, and bulk actions across all rules in the space. Selecting a rule name opens its details page, where you can review the full configuration and edit or act on it directly. +Viewing and managing rules is part of the {{alerting-v2}} in Kibana. After a rule is created, edit its settings, pause it, remove it, and more from the page listing rules. The rules list gives you search, filter, sort, and bulk actions across all rules in the space. Selecting a rule name opens its details page, where you can review the full configuration and edit or act on it directly. ## Find and filter rules [find-filter-rules] diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md index 6684ad4ccb..84ba863d57 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md @@ -5,13 +5,13 @@ applies_to: serverless: preview products: - id: kibana -description: "Complete field reference for YAML rule definitions in the experimental alerting features: required fields, metadata, schedule, grouping, state transitions, no-data handling, and duration format." +description: "Complete field reference for YAML rule definitions in the {{alerting-v2}}: required fields, metadata, schedule, grouping, state transitions, no-data handling, and duration format." --- # YAML rule schema reference [yaml-rule-schema-reference] -YAML rule schema is part of the experimental alerting features in Kibana. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create rules using the YAML editor](create-rule-with-yaml.md). +YAML rule schema is part of the {{alerting-v2}} in Kibana. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create rules using the YAML editor](create-rule-with-yaml.md). ## Required fields From 34afcb618604c7bba79ce1d1fa8e3744ddf6ad08 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 3 Jun 2026 21:17:49 -0400 Subject: [PATCH 03/23] Updates applies_to tags --- .../alerting/kibana-alerting-experimental/rules.md | 4 ++-- .../kibana-alerting-experimental/rules/author-rules.md | 4 ++-- .../kibana-alerting-experimental/rules/configure-a-rule.md | 4 ++-- .../rules/create-rule-from-discover.md | 4 ++-- .../rules/create-rule-from-rule-builder.md | 4 ++-- .../rules/create-rule-with-yaml.md | 4 ++-- .../kibana-alerting-experimental/rules/esql-query-patterns.md | 4 ++-- .../rules/rule-event-field-reference.md | 4 ++-- .../kibana-alerting-experimental/rules/view-manage-rules.md | 4 ++-- .../rules/yaml-rule-schema-reference.md | 4 ++-- 10 files changed, 20 insertions(+), 20 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules.md index 683510ea82..92c7528224 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules.md @@ -1,8 +1,8 @@ --- navigation_title: Rules applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "What rules are in the {{alerting-v2}}, how evaluation works, and how rules connect to alerts and notifications." diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md index f4f07c0f7d..02ad753ce4 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md @@ -1,8 +1,8 @@ --- navigation_title: Author rules applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "Learn how to write ES|QL queries for rules. Choose a rule mode, structure a base query and alert condition, set thresholds, and assign severity levels." diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md index e2622b3205..b57c3f06ef 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -1,8 +1,8 @@ --- navigation_title: Configure a rule applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "Configure rules in the {{alerting-v2}}: mode, ES|QL, grouping, schedule, lookback, activation and recovery, no-data handling, tags, and evaluation." diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md index 6c1c5176e1..3fbfd2b0af 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md @@ -1,8 +1,8 @@ --- navigation_title: Using Discover applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "Turn an {{esql}} query in Discover into a rule in the {{alerting-v2}} with pre-filled evaluation and lookback." diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md index b62162d73c..18f05159c1 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md @@ -1,8 +1,8 @@ --- navigation_title: Using the rule builder applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "Create a rule with the interactive rule builder" diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md index 55534629d9..2c8691d655 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md @@ -1,8 +1,8 @@ --- navigation_title: Using the YAML editor applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "Define rules as YAML in the {{alerting-v2}} for version control, infrastructure-as-code, and bulk provisioning." diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md index b2ad379f76..b7807f94a5 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md @@ -1,8 +1,8 @@ --- navigation_title: ES|QL query patterns applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "Advanced {{esql}} query patterns for rules in the {{alerting-v2}}: SLO burn rate, no-data detection, persistent breach, and unsupported operations." diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md index b3a7139a7e..f2a5258b45 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md @@ -1,8 +1,8 @@ --- navigation_title: Rule and event fields applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "Reference for rule configuration fields and documents written to `.rule-events` in the {{alerting-v2}}." diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md index 2426578385..2f9f0013d9 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md @@ -1,8 +1,8 @@ --- navigation_title: View and manage rules applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "Use the rules list and rule details page in the {{alerting-v2}}: filters, search, bulk actions, and what you find in rule conditions." diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md index 84ba863d57..c8abe7326b 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md @@ -1,8 +1,8 @@ --- navigation_title: YAML rule schema reference applies_to: - stack: unavailable - serverless: preview + stack: experimental 9.5+ + serverless: experimental products: - id: kibana description: "Complete field reference for YAML rule definitions in the {{alerting-v2}}: required fields, metadata, schedule, grouping, state transitions, no-data handling, and duration format." From 183ac2dcb4ce06986cd1cea674d9dea975c1c74a Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Thu, 4 Jun 2026 00:43:05 -0400 Subject: [PATCH 04/23] [Alerting V2][Serverless & 9.5][M2] Rule feature changes from May 2026 (#6687) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Updates the rules docs for the experimental alerting features with content from doc issues addressed across two phases of work. Following the tech preview principle of accuracy over comprehensiveness, changes focus on stable concepts — what the system does, when to use each feature, how creation paths work — rather than UI-level procedures that are subject to change before GA. ### Naming conventions and variable corrections (all files) Systematic corrections across all nine rules pages and `docset.yml` to bring variable names, H1 titles, and anchor sentences into line with the naming guidelines. **`docset.yml`** — Renamed `alerting-v2` → `alerting-v2-system` and `alerting-v2-cap` → `alerting-v2-system-cap` to match the naming cheat sheet prescription ("experimental alerting system" in prose). **All rules files** — Updated all occurrences of `{{alerting-v2}}` to `{{alerting-v2-system}}`. Removed "the" from H1 titles where the variable appears (title convention: no article). Updated four anchor sentences that used gerund subjects (`Authoring rules is part of...`, `Configuring rules is part of...`, `Viewing and managing rules is part of...`, `Creating rules from Discover is part of...`) to concrete noun subjects (`Rule authoring is part of...`, `Rule configuration is part of...`, `Rule management is part of...`, `Discover-based rule creation is part of...`). Added the system name to H1 titles on three pages that were missing it (`create-rule-from-discover.md`, `create-rule-from-rule-builder.md`, `create-rule-with-yaml.md`). Added `{{alerting-v2-system}}` to the `rule-event-field-reference.md` H1, which was the only page missing the variable entirely. ### Rule kind label: "Detection only" renamed to "Signal" (#6837) PR #272140 renamed the rule kind label from "Detection only" to "Signal" in the action policy filter dropdown and the episode details rule overview panel. **`author-rules.md`** — Updated the rule mode table: `Detect (kind: signal)` → `Signal (kind: signal)`. **`configure-a-rule.md`** — Updated the rule mode table: `Detect` → `Signal`. Updated the action policy note: "Detect-mode rules" → "Signal-mode rules". **`rules.md`** — Updated all prose references from "Detect mode" to "Signal mode", including the conceptual description and the Next Steps link text. ### Flyout-only rule authoring and creation paths (#6612, #6500, #6607) PR #269629 removed standalone full-page rule form routes. All rule creation and editing now happens through a flyout. PR #267779 introduced the three-path onboarding panel, and PR #269156 wired the Create ES|QL rule card to open the flyout inline rather than navigate to a page. **`rules.md`** — Added a **Create a rule** section establishing that all rules are created through a flyout (never a full-page form) and describing the three starting points at a conceptual level: Create ES|QL rule, Create with AI Agent, and Start from a rule builder. Added a third Next Steps link pointing to `configure-a-rule.md`. **`create-rule-from-rule-builder.md`** — Added a **Creation paths** section documenting the three options on the rule creation panel, with guidance on when to choose each. ### Threshold Alert rule builder (#6832, #6835) **`create-rule-from-rule-builder.md`** — Added a **Threshold Alert** section documenting the first available rule builder type: structured form fields generate the ES|QL query automatically, rules created through the builder can be reopened in builder mode as long as the underlying ES|QL hasn't been edited directly, and a graceful fallback to the ES|QL editor applies when it has. Added a **Recovery conditions** subsection explaining that the builder auto-derives recovery conditions by flipping the alert comparators (a `greater than` alert condition produces a `less than or equal to` recovery condition), and that these are preserved correctly when reopening a rule for editing. ### Form/YAML toggle in the rule authoring flyout (#6606, #6418) PR #269150 added a YAML editing mode to the Compose Discover flyout, and PR #265929 added the toggle to the Discover-based flyout. Both share the same sync behavior. **`create-rule-from-rule-builder.md`** — Added an **ES|QL rule: form and YAML editing** section explaining that the Create ES|QL rule path supports both form and YAML modes, that edits are preserved when switching views, that Cancel YAML discards edits and restores prior form state, and that the YAML editor is not available within the Threshold Alert builder or other rule builder types. **`create-rule-from-discover.md`** — Added a matching **Form and YAML editing** section with the same behavioral description, plus a note that the YAML editor includes ES|QL autocomplete in the query field. ### Create rules from Discover (#6614, #6499) PR #260844 added the Create ES|QL rule entry point to the Discover Alerts menu, and PR #268774 introduced the Compose Discover stepped flyout from the rules list. **`create-rule-from-discover.md`** — Added an **Entry points** section documenting both paths into Discover-based rule creation: the Alerts menu in Discover (available only in ES|QL mode) and the rules list. Clarified that the Discover path pre-fills the **Create ES|QL rule** form, not the Threshold Alert builder. Removed a stale cross-reference implying the rule builder holds the YAML toggle. ### Separate alert and recovery conditions (#6605) PR #269023 introduced query splitting for the Compose Discover flow, separating the base data pipeline from the alert condition and adding an explicit Recovery Condition step. **`author-rules.md`** — Added a **Recovery condition** subsection documenting Default (auto-recover when alert condition clears), Custom (separate ES|QL expression), and No recovery (coming soon) types, with guidance on when to use a custom condition over the default. ### AI agent entry points for rule creation (#6604) PR #269588 added Create with agent entry points to both the rules list split button and the rule creation options panel. **`create-rule-from-rule-builder.md`** — Covered as part of the Creation paths section: the AI agent option is described with its use case (plain-language rule definition) and entry point. ### Severity as first-class episode fields (#6689) **`author-rules.md`** — Replaced the convention-based severity description with the M2 first-class `episode.severity` contract: include a `severity` column in ES|QL query output, add it to `KEEP`, and the framework maps it to one of five fixed levels (`info`, `low`, `medium`, `high`, `critical`). Includes an ES|QL example showing the `EVAL severity = CASE(...)` pattern. **`rule-event-field-reference.md`** — Added `episode.severity` and `episode.severity_max` to the episode fields table with descriptions of their behavior and constraints. Removed a stale content-needed comment. **`esql-query-patterns.md`** — Connected the `severity` column in ES|QL query output to the `episode.severity` field stored on the rule event document. Removed stale content-needed comments. ### Action policy creation from the rule form (#6833) **`configure-a-rule.md`** — Updated the action policy note to reflect that Alert-mode rules can now create and attach action policies directly from the rule form's **Actions** step. Clarified that the Actions step is not shown for Signal-mode rules, and that action policies can still be managed independently from the Action policies area. ### Optional recovery policy and no-recovery behavior (#6844) **`yaml-rule-schema-reference.md`** — Added a note to the Recovery policy fields section clarifying that `recovery_policy` is optional. When absent (API or Agent Builder only), the rule emits no recovery events and active alert episodes don't close automatically. Rules created through the Kibana UI always include `recovery_policy.type: no_breach` by default. Removed a stale content-needed comment. **`configure-a-rule.md`** — Added a note in the Recovery thresholds section cross-referencing the `recovery_policy.type` default (UI: `no_breach`) versus API omission behavior, with a link to the schema reference. ### Rule Doctor (#6841) **`rules.md`** — Added **Rule Doctor** to the Next Steps section, describing insight types (duplicates, stale conditions, threshold tuning opportunities, coverage gaps), the open → applied or dismissed lifecycle, and the impact and confidence ratings surface. ### Rule search behavior (#6420, #6615) PR #265303 rewrote the rules list search to use the Saved Objects client's `simple_query_string`, fixing special-character failures. PR #261154 expanded search to match `metadata.description` in addition to `metadata.name`. **`view-manage-rules.md`** — Updated the **Find and filter rules** section to document that search matches rule name and description only using prefix matching (terms AND'd), that tags and grouping fields are displayed in results but aren't full-text searched, and that special characters including consecutive hyphens are handled correctly. ### Quick-edit a rule (#6417) PR #268164 added the Quick Edit flyout, accessible from the pencil icon in a rule row or from the rule summary flyout header. **`view-manage-rules.md`** — Added a **Quick-edit a rule** section documenting editable fields (name, description, tags, grouping key, time field, interval, lookback, alert delay, recovery type, recovery delay) and read-only fields (ES|QL query, alert tracking behavior) in the inline editor. UI entry-point mechanics omitted as the IA is not yet stable. ### Group fields align with STATS...BY (#6415) PR #268522 added auto-population of the Group Fields combobox from the `STATS ... BY` clause as the user types. **`configure-a-rule.md`** — Added a note under **Rule grouping** explaining that writing the query first avoids mismatches between query output and grouping configuration, and that group fields in the form reflect the columns produced by the `STATS ... BY` clause. ## Out of scope for this PR * **#6831** (Alert Delay field in Compose Discover flyout): `configure-a-rule.md` connects `pending_timeframe` to the "Alert delay" UI label. The full Alert Condition step procedure in the Compose Discover flyout is deferred until the flyout UI is stable. * **#6839** (single_rule action policy type via Agent Builder): No docs update required at this time. The `set_type` operation is consumed internally by the AI agent; users interact only through natural language and a rendered card. The `single_rule` policy type and how it differs from a global policy will be documented when action policies reach GA. * **#6012** (no-data handling UI control, serverless only): `configure-a-rule.md` already documents the three `no_data.behavior` values accurately. UI control details deferred. * **#6018** (query preview/test in Discover): Covered by the existing query preview section in `create-rule-from-discover.md`. UI procedure deferred until IA is stable. * **#6603** (action policy support in Agent Builder): Belongs in the action policy docs, not the rules pages. * **#6611** (step indicator in the rule flyout): Minor UI chrome with no stable conceptual content to add at the tech preview stage. * **#6015**: Closed as not planned. ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? * Yes - Cursor + Claude sonnet * No --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docset.yml | 4 +- .../kibana-alerting-experimental/rules.md | 34 ++++++--- .../rules/author-rules.md | 69 +++++++++++++++---- .../rules/configure-a-rule.md | 26 ++++--- .../rules/create-rule-from-discover.md | 27 ++++++-- .../rules/create-rule-from-rule-builder.md | 35 ++++++++-- .../rules/create-rule-with-yaml.md | 6 +- .../rules/esql-query-patterns.md | 28 ++++---- .../rules/rule-event-field-reference.md | 23 +++---- .../rules/view-manage-rules.md | 20 ++++-- .../rules/yaml-rule-schema-reference.md | 13 ++-- 11 files changed, 192 insertions(+), 93 deletions(-) diff --git a/docset.yml b/docset.yml index bc3520a11f..d38d85bdce 100644 --- a/docset.yml +++ b/docset.yml @@ -124,8 +124,8 @@ subs: ls-pipelines-app: "Logstash Pipelines" maint-windows-app: "Maintenance Windows" maint-windows-cap: "Maintenance windows" - alerting-v2: "experimental alerting features" - alerting-v2-cap: "Experimental alerting features" + alerting-v2-system: "experimental alerting system" + alerting-v2-system-cap: "Experimental alerting system" custom-roles-app: "Custom Roles" data-source: "data view" data-sources: "data views" diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules.md index 92c7528224..3466834bbd 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules.md @@ -5,25 +5,25 @@ applies_to: serverless: experimental products: - id: kibana -description: "What rules are in the {{alerting-v2}}, how evaluation works, and how rules connect to alerts and notifications." +description: "Rules in Kibana's experimental alerting system define what to detect using ES|QL. Evaluation runs on a schedule; alerts, action policies, and notifications flow from rule detections." --- -# Rules in the {{alerting-v2}} +# Rules in the {{alerting-v2-system}} -Rules are part of the {{alerting-v2}} in Kibana. For rules in the existing Kibana alerting system, see [Rules in Kibana alerting](../alerts/create-manage-rules.md). +Rules are part of the {{alerting-v2-system}} in {{kib}}. For rules in the existing Kibana alerting system, see [Rules in Kibana alerting](../alerts/create-manage-rules.md). -A rule is where the {{alerting-v2}} start. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. +A rule is where the {{alerting-v2-system}} starts. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. ## What rules do [detection-and-notification] -On each run, a rule executes an {{esql}} query against your data. If the query finds a match and the rule is in Detect mode, it writes a _signal_, a point-in-time record that the condition was met. In Alert mode, it also maintains an _alert episode_ for each matched series, tracking state from first breach through recovery. +On each run, a rule executes an {{esql}} query against your data. If the query finds a match and the rule is in Signal mode, it writes a _signal_, a point-in-time record that the condition was met. In Alert mode, it also maintains an _alert episode_ for each matched series, tracking state from first breach through recovery. -When creating a rule, choose Detect mode to record and query results without alerting anyone, or Alert mode when you want to track issues and route notifications. +When creating a rule, choose Signal mode to record and query results without alerting anyone, or Alert mode when you want to track issues and route notifications. ## What rules don't do -Rules only define *what* to detect. They don't control notifications, who gets notified, or when. That's the job of action policies — global objects, scoped to your space, that match episodes from any rule. A rule has no say in which policies pick it up. +Rules only define *what* to detect. They don't control notifications, who gets notified, or when. That's the job of action policies — global objects, scoped to your space, that match alert episodes from any rule. A rule has no say in which policies pick it up. This separation means you can build and test a rule without anyone getting paged, update notification routing without touching the rule, and have multiple action policies respond to the same rule independently. @@ -31,11 +31,25 @@ This separation means you can build and test a rule without anyone getting paged % Rules never overwrite old data. Each evaluation appends rows to `.rule-events`, giving you a complete, queryable history of every time the condition was met, when it cleared, and what the data looked like. -% When a rule groups by fields (for example `BY host.name`), each unique combination is its own series, identified by `group_hash`. An episode spans one lifecycle arc on a series from first breach through recovery, identified by `episode_id`. +% When a rule groups by fields (for example `BY host.name`), each unique combination is its own series, identified by `group_hash`. An alert episode spans one lifecycle arc on a series from first breach through recovery, identified by `episode_id`. % You can query this history in Discover, build dashboards from it, or write follow-on rules that read `.rule-events` as a data source. +## Create a rule [create-a-rule] + +Rules in the {{alerting-v2-system}} are created through a flyout that opens from the **Create rule** button in the rules list. Three options are available: + +- **Create ES|QL rule**: Write the detection query as {{esql}} directly, with a live preview of results and a YAML editor also available. Use this when you want full control over the query. See [Create rules](rules/create-rule-from-rule-builder.md). +- **Create with AI Agent**: Describe what you want to detect in plain language. The AI agent generates a rule definition and walks you through reviewing and saving it. Use this when you know the problem but aren't sure how to write the {{esql}}. +- **Start from a rule builder**: Choose a structured rule type and fill in a guided form. The builder generates the {{esql}} query automatically. The [Threshold Alert](rules/create-rule-from-rule-builder.md#threshold-alert) type is available. Use this when you want to create a standard metric-threshold rule without writing {{esql}} by hand. + +If you already have an {{esql}} query working in Discover, you can also [create a rule directly from there](rules/create-rule-from-discover.md) to skip re-entering the query. + ## Next steps -- **[Author rules](rules/author-rules.md):** Write the {{esql}} query, choose Detect or Alert mode, and structure your data sources and conditions. -- **[View and manage rules](rules/view-manage-rules.md):** Enable, disable, clone, delete, and bulk-manage rules from the rules list. \ No newline at end of file +- **[Author rules](rules/author-rules.md):** Write the {{esql}} query, choose Signal or Alert mode, and structure your data sources and conditions. +- **[Configure a rule](rules/configure-a-rule.md):** Set the schedule, grouping, activation thresholds, recovery conditions, and no-data behavior. +- **[View and manage rules](rules/view-manage-rules.md):** Enable, disable, clone, delete, and bulk-manage rules from the rules list. +- **Rule Doctor:** Analyze your rules for duplicates, stale conditions, threshold tuning opportunities, and coverage gaps. Rule Doctor surfaces findings with impact and confidence ratings and tracks each insight through an open → applied or dismissed lifecycle. Access it from the {{alerting-v2-system}} navigation. + + \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md index 02ad753ce4..7fa4df90a1 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md @@ -5,13 +5,12 @@ applies_to: serverless: experimental products: - id: kibana -description: "Learn how to write ES|QL queries for rules. Choose a rule mode, structure a base query and alert condition, set thresholds, and assign severity levels." +description: "Write ES|QL detection queries for rules in Kibana's experimental alerting system. Choose Signal or Alert mode, structure base queries and conditions, and assign severity levels." --- -# Author rules for the {{alerting-v2}} [author-rules] +# Rule authoring in the {{alerting-v2-system}} [author-rules] - -Authoring rules is part of the {{alerting-v2}} in Kibana. Authoring a rule means deciding three things: what condition in your data counts as a problem, whether you want the rule to silently record matches or actively track issues through to resolution, and which fields to carry forward onto each alert event so you can route and triage effectively. Getting these decisions right in the query is what makes the difference between a rule that fires on everything and one that surfaces the problems that actually need attention. +Rule authoring is part of the {{alerting-v2-system}} in {{kib}}. Authoring a rule means deciding three things: what condition in your data counts as a problem, whether you want the rule to silently record matches or actively track issues through to resolution, and which fields to carry forward onto each alert event so you can route and triage effectively. Getting these decisions right in the query is what makes the difference between a rule that fires on everything and one that surfaces the problems that actually need attention. This page covers the query concepts behind a rule definition. For settings beyond the query (such as schedules, grouping, and lifecycle thresholds), refer to [Configure a rule](configure-a-rule.md). Once you understand what goes into a rule, you can write one using the [rule builder](create-rule-from-rule-builder.md), [YAML editor](create-rule-with-yaml.md), or [a Discover session](create-rule-from-discover.md). @@ -21,8 +20,8 @@ Before creating the rule, decide what you want it to do: | Mode | What it does | | --- | --- | -| Detect (`kind: signal`) | Records query matches as signals. No episodes, no notifications. Good for testing a query or building a data history without alerting anyone. | -| Alert (`kind: alert`) | Records matches and maintains alert episodes with lifecycle states. Episodes appear on the **Alerts** page and can be matched by action policies for notifications. | +| Signal (`kind: signal`) | Records query matches as signals. No alert episodes, no notifications. Good for testing a query or building a data history without alerting anyone. | +| Alert (`kind: alert`) | Records matches and maintains alert episodes with lifecycle states. Alert episodes appear on the **Alerts** page and can be matched by action policies for notifications. | You can switch a rule's mode after creation from the rule list or rule detail page. @@ -47,9 +46,22 @@ WHERE avg_cpu > 0.9 The `KEEP` command controls which fields appear on each stored alert event. Only the fields you `KEEP` are available for policy matchers, grouping keys, and triage in the Alerts UI. +### Recovery condition [recovery-condition] + +Recovery conditions are optional. They determine when an active alert episode closes. + +Three recovery types are available: + +| Type | Behavior | +| --- | --- | +| Default | The alert episode recovers automatically when the alert condition is no longer met. | +| Custom | Uses a separate {{esql}} expression you define. The alert episode recovers when that expression returns no rows. | + +When no recovery condition is configured, Default recovery applies. Use a custom recovery condition when the absence of a breach isn't a reliable recovery indicator — for example, when the alert condition uses a narrow lookback window and you want recovery to require the condition to stay clear across a longer period, or when the recovery logic requires a different query shape than the alert detection. + ## Data sources -Use `FROM` to point the rule at the indices or data streams to read. The query itself defines the scope. There is no separate data source step. +Use `FROM` to point the rule at the indices or data streams to read. The query itself defines the scope. There's no separate data source step. ```esql FROM logs-checkout-service-* @@ -64,7 +76,7 @@ The [{{esql}} reference](elasticsearch://reference/query-languages/esql.md) cove The alert condition in {{esql}} defines what counts as a breach in each evaluation. -The activation and recovery thresholds on the rule are separate from the query. They control how many consecutive breaches must occur, or how long the condition must persist, before an episode becomes active or moves back to inactive. Those settings are in [Configure a rule](configure-a-rule.md#activation-recovery-thresholds). +The activation and recovery thresholds on the rule are separate from the query. They control how many consecutive breaches must occur, or how long the condition must persist, before an alert episode becomes active or moves back to inactive. Those settings are in [Configure a rule](configure-a-rule.md#activation-recovery-thresholds). +Severity matching is case-insensitive. Values that don't match one of the five levels are silently ignored — the alert episode is still created, but `episode.severity` is not set. + +Severity is set only on `breached` rule events. `recovered` and `no_data` events don't carry a severity value. + +When severity is set, the framework stores two fields on the alert episode: + +- `episode.severity` — The severity value from the most recent breached event (current state). +- `episode.severity_max` — The highest severity level observed across the episode's lifetime. Useful for routing like "this episode peaked at critical." + +Both fields are available for action policy matchers. Refer to [Rule event and field reference](rule-event-field-reference.md#episode-fields) for more information about these fields. + +```esql +FROM metrics-* +| STATS + errors_5m = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 5 minutes), + total_5m = COUNT_IF(@timestamp >= NOW() - 5 minutes) + BY service.name +| EVAL burn_5m = errors_5m / total_5m +| EVAL severity = CASE( + burn_5m > 14.4, "critical", + burn_5m > 6.0, "high", + burn_5m > 1.0, "medium", + "low" + ) +| WHERE burn_5m > 1.0 +| KEEP service.name, burn_5m, severity +``` + +The `severity` column in `KEEP` is what tells the framework to set `episode.severity` on each resulting alert episode. ## Next steps diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md index b57c3f06ef..2dd23ec35b 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -5,13 +5,13 @@ applies_to: serverless: experimental products: - id: kibana -description: "Configure rules in the {{alerting-v2}}: mode, ES|QL, grouping, schedule, lookback, activation and recovery, no-data handling, tags, and evaluation." +description: "Configure rules in the experimental alerting system: mode, ES|QL, grouping, schedule, lookback, activation and recovery, no-data handling, tags, and evaluation." --- -# Configure a rule in the {{alerting-v2}} [rule-settings] +# Configure a rule in {{alerting-v2-system}} [rule-settings] -Configuring rules is part of the {{alerting-v2}} in Kibana. The {{esql}} query defines what a rule detects. The settings on this page determine whether it behaves correctly in production: how often it runs, how it groups related problems, when it opens and closes alerts, and what it does when data stops arriving. +Rule configuration is part of the {{alerting-v2-system}} in {{kib}}. The {{esql}} query defines what a rule detects. The settings on this page determine whether it behaves correctly in production: how often it runs, how it groups related problems, when it opens and closes alerts, and what it does when data stops arriving. For query authoring, refer to [Author rules](author-rules.md). :::{note} -Action policies are not configured on the rule form. You create them separately in the **Action policies** area and use KQL matchers to scope them to the episodes you want to route. The rule builder form does not link to policies. +For Alert-mode rules, you can create and attach action policies directly from the rule form's **Actions** step. Existing action policies that match the rule are listed on load. If none exist, an onboarding panel appears. Action policies are created or updated alongside the rule when you save. The **Actions** step is not shown for Signal-mode rules. + +You can also manage action policies independently from the **Action policies** area, using KQL matchers to scope them to any episodes you want to route. ::: ## Rule mode [rule-mode] @@ -28,8 +30,8 @@ Choose a mode that matches how you want to use results: | Mode | Behavior | | --- | --- | -| Detect | Signals only: the rule produces detections without alert lifecycle tracking or notifications. | -| Alert | Lifecycle tracking and notifications: alerts move through states (pending, active, recovering, and so on), and you can attach action policies so episodes dispatch through workflows. | +| Signal | Signals only: the rule produces detections without alert lifecycle tracking or notifications. | +| Alert | Lifecycle tracking and actions. Alerts move through states (pending, active, recovering, and so on), and you can attach action policies so alert episodes dispatch through workflows. | Several settings on this page apply only when the rule is in Alert mode (`kind: alert`). @@ -44,7 +46,9 @@ Rule grouping splits alert event generation by one or more group key fields so t Group key fields must align with the `BY` clause in your {{esql}} query's `STATS` command. See [Author rules](author-rules.md) for query patterns. -Note that rule grouping is separate from notification grouping on an action policy, which controls how episodes batch into messages. +When writing a rule that uses grouping, writing the query first and then specifying group fields avoids mismatches between the query output and the grouping configuration. The group fields in the rule form reflect the columns produced by the `STATS ... BY` clause, so if you add or remove a `BY` field in the query, the corresponding group field must be updated to match. + +Note that rule grouping is separate from notification grouping on an action policy, which controls how alert episodes batch into messages. @@ -80,7 +84,7 @@ Configure activation using count, timeframe, or both: | Field | Description | | --- | --- | | `pending_count` | Consecutive breaches required | -| `pending_timeframe` | Minimum duration the condition must persist | +| `pending_timeframe` | Minimum duration the condition must persist (shown as **Alert delay** in the UI) | | `pending_operator` | How to combine count and timeframe (`AND` or `OR`) | Each timeframe value must be between 5 seconds and 365 days. @@ -95,6 +99,10 @@ Each timeframe value must be between 5 seconds and 365 days. Time frame fields use the same 5 seconds to 365 days bounds as activation timeframes. +:::{note} +The `recovery_policy` field controls how recovery is detected, separately from how many recoveries are required. When creating a rule through the UI, `recovery_policy.type` defaults to `no_breach`, which recovers the alert episode when its active group no longer appears in the breach batch. When creating a rule through the API or Agent Builder, you can omit `recovery_policy` entirely to suppress recovery events and keep alert episodes active until closed manually. For the full field reference, go to [YAML rule schema reference](yaml-rule-schema-reference.md#recovery-policy-fields). +::: + ## No-data handling [no-data-handling] No-data handling controls what happens when a rule executes and the base query returns no results. Proper configuration prevents false recoveries and misleading `no_data` events when data sources stop reporting. @@ -109,7 +117,7 @@ Set `no_data.behavior` to one of the following values: | `last_status` | Carry forward the previous status | | `recover` | Treat absence as recovery | -These behaviors apply when the base query returns zero rows. They do not help when you want to *detect* that a specific host or data source has gone silent. That requires a different query approach. See [No-data detection](esql-query-patterns.md#no-data-esql-query) in the authoring guide for an {{esql}} pattern that surfaces silent sources as alert rows. +These behaviors apply when the base query returns zero rows. They don't help when you want to *detect* that a specific host or data source has gone silent. That requires a different query approach. See [No-data detection](esql-query-patterns.md#no-data-esql-query) in the authoring guide for an {{esql}} pattern that surfaces silent sources as alert rows. ## Tags and investigation guide [tags-investigation] diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md index 3fbfd2b0af..25a6aae0e1 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md @@ -5,19 +5,32 @@ applies_to: serverless: experimental products: - id: kibana -description: "Turn an {{esql}} query in Discover into a rule in the {{alerting-v2}} with pre-filled evaluation and lookback." +description: "Turn an ES|QL query in Discover into a rule in the experimental alerting system with pre-filled evaluation and lookback." --- -# Create rules from Discover [create-rules-discover] +# Create rules from Discover in the {{alerting-v2-system}} [create-rules-discover] -Creating rules from Discover is part of the {{alerting-v2}} in Kibana. Create experimental alerting rules directly from Discover. When you build an {{esql}} query that surfaces interesting patterns, you can convert it into a rule without rewriting the query. For the full rule form including alert mode settings and YAML toggle, refer to [Create rules using the rule builder](create-rule-from-rule-builder.md). +Discover-based rule creation is part of the {{alerting-v2-system}} in {{kib}}. When you build an {{esql}} query that surfaces interesting patterns, you can convert it into a rule without rewriting the query. For the full rule form including schedule and lifecycle settings, refer to [Configure a rule](configure-a-rule.md). + +## Entry points [discover-rule-entry-points] + +Two paths lead to Discover-based rule creation: + +- **Discover Alerts menu**: When you're in Discover with an active {{esql}} query and the {{alerting-v2-system}} is enabled, the Alerts menu includes a **Create ES|QL rule** option. The rule creation flyout opens pre-populated with the current query. This path is only available in ES|QL mode. +- **Rules list**: From the rules list, selecting the option to create a rule from Discover opens the Discover-based rule creation experience directly. The flyout embeds a live Discover session so you can compose and test the query before saving the rule. After saving, you return to the rules list. ## How it works [discover-rule-flow] Starting a rule from Discover means your query is already tested and returns the shape you expect before the rule is ever saved. Instead of drafting a query in the rule builder and hoping it works, you iterate in Discover (where you can see real results immediately) and then create the rule when the query is ready. -When you trigger rule creation from Discover, your {{esql}} query pre-fills the rule form. The rule creation form also shows a preview panel that reflects how your query partitions results into alert series. If your query uses a `BY` clause, the preview shows the series that would be evaluated on each run. This lets you verify grouping logic against live data before committing to a schedule. +When you trigger rule creation from Discover, your {{esql}} query pre-fills the **Create ES|QL rule** form. The rule creation form also shows a preview panel that reflects how your query partitions results into alert series. If your query uses a `BY` clause, the preview shows the series that would be evaluated on each run. This lets you verify grouping logic against live data before committing to a schedule. + +## Form and YAML editing [discover-form-yaml] + +The rule creation flyout supports both a step-by-step form and a YAML editing mode. You can switch between them at any point — edits in YAML mode are preserved when you return to the form view. To discard YAML edits and return to the prior form state, use the **Cancel YAML** option. The YAML editor includes {{esql}} autocomplete in the query field. + +Use YAML mode when you want to fine-tune the raw rule definition, copy a pattern from an existing rule, or work faster than filling in individual form fields allows. ## Preview query results before creating the rule [preview-query-discover] @@ -25,12 +38,12 @@ When you trigger rule creation from Discover, your {{esql}} query pre-fills the The query preview in the rule creation flow runs your {{esql}} query against current data and displays the resulting rows. Use this to: - **Confirm grouping**: Check that your `BY` clause produces the series you intend — for example, one distinct series per host or per service, not a single undifferentiated result. -- **Catch unexpected output**: Verify that the query returns data in the right shape for the alert condition you plan to set. A query that returns zero rows or an unexpected field name will not behave as expected once the rule runs on a schedule. +- **Catch unexpected output**: Verify that the query returns data in the right shape for the alert condition you plan to set. A query that returns zero rows or an unexpected field name won't behave as expected once the rule runs on a schedule. - **Refine before committing**: Edit the query in the preview panel and re-run it without leaving the rule creation form. Once the preview looks correct, proceed to fill in the remaining settings. - \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md index 18f05159c1..3822417ea8 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md @@ -5,15 +5,40 @@ applies_to: serverless: experimental products: - id: kibana -description: "Create a rule with the interactive rule builder" +description: "Create ES|QL rules, AI-assisted rules, and Threshold Alert rules in Kibana's experimental alerting system using the rule builder flyout." --- -# Create rules using the rule builder [create-rules-rule-builder] +# Create rules in the {{alerting-v2-system}} [create-rules-rule-builder] +The rule builder is part of the {{alerting-v2-system}} in {{kib}}. For a full description of what each setting does, refer to [Configure a rule](configure-a-rule.md). -The rule builder is part of the {{alerting-v2}} in Kibana. It is the right starting point when you're creating a rule from scratch and want inline guidance through each setting. For a full description of what each setting does, refer to [Configure a rule](configure-a-rule.md). +## Creation paths [rule-creation-paths] -If you already have a working query in Discover, you can [create a rule directly from there](create-rule-from-discover.md) without re-entering it. If you're managing rules as code or need to version-control rule definitions, use the [YAML editor](create-rule-with-yaml.md) instead. +All rules are created through a flyout that opens from the **Create rule** button in the rules list. Three options are available: - diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md index 2c8691d655..89834259e3 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md @@ -5,13 +5,13 @@ applies_to: serverless: experimental products: - id: kibana -description: "Define rules as YAML in the {{alerting-v2}} for version control, infrastructure-as-code, and bulk provisioning." +description: "Define rules as YAML in Kibana's experimental alerting system for version control, infrastructure-as-code, and bulk provisioning of detection logic." --- -# Create rules using the YAML editor [create-rules-yaml] +# Create rules using the YAML editor in {{alerting-v2-system}} [create-rules-yaml] -The YAML editor is part of the {{alerting-v2}} in Kibana. It lets you define rules as text documents rather than filling in a form. Use it when you want to version-control rule definitions alongside your other configuration, manage rules through infrastructure-as-code tooling, copy or adapt a rule quickly without re-entering settings by hand, or provision many rules at once. +The YAML editor is part of the {{alerting-v2-system}} in {{kib}}. It lets you define rules as text documents rather than filling in a form. Use it when you want to version-control rule definitions alongside your other configuration, manage rules through infrastructure-as-code tooling, copy or adapt a rule quickly without re-entering settings by hand, or provision many rules at once. If you're creating a rule from scratch and want guidance through each setting, the [rule builder](create-rule-from-rule-builder.md) is the better starting point. If you have a query already working in Discover, you can [create a rule directly from there](create-rule-from-discover.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md index b7807f94a5..2cddc60b1d 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md @@ -5,15 +5,15 @@ applies_to: serverless: experimental products: - id: kibana -description: "Advanced {{esql}} query patterns for rules in the {{alerting-v2}}: SLO burn rate, no-data detection, persistent breach, and unsupported operations." +description: "Advanced ES|QL query patterns for rules in the experimental alerting system: SLO burn rate, no-data detection, persistent breach, and unsupported operations." --- -# {{esql}} query patterns for rules in the {{alerting-v2}} [esql-query-patterns] +# {{esql}} query patterns for rules in the {{alerting-v2-system}} [esql-query-patterns] -ES|QL query patterns for rules are part of the {{alerting-v2}} in Kibana. Some detection problems can't be expressed as a single metric compared to a fixed threshold. You might need to know whether an SLO is burning through its error budget across multiple time windows at once. Or whether a specific host has gone silent, rather than whether the query returned nothing. Or whether a condition has persisted continuously across consecutive time buckets rather than appearing once. These are structurally different problems that require different query shapes. +ES|QL query patterns for rules are part of the {{alerting-v2-system}} in {{kib}}. Some detection problems can't be expressed as a single metric compared to a fixed threshold. You might need to know whether an SLO is burning through its error budget across multiple time windows at once. Or whether a specific host has gone silent, rather than whether the query returned nothing. Or whether a condition has persisted continuously across consecutive time buckets rather than appearing once. These are structurally different problems that require different query shapes. -Use this page when a basic `STATS ... WHERE` pattern isn't enough, or when the detection logic itself requires multi-window calculation, last-seen reasoning, or bucket-level persistence checks. If you're still learning how rules in the {{alerting-v2}} work, start with [Author rules](author-rules.md) first. +Use this page when a basic `STATS ... WHERE` pattern isn't enough, or when the detection logic itself requires multi-window calculation, last-seen reasoning, or bucket-level persistence checks. If you're still learning how rules in the {{alerting-v2-system}} work, start with [Author rules](author-rules.md) first. ## Basic threshold query [threshold-query] @@ -39,7 +39,7 @@ An SLO burn rate query asks a different question than a basic threshold: are you ### Why multiple windows -Checking both a short window (for example, 5 minutes) and a long window (for example, 1 hour) together filters out brief spikes that do not represent a real budget threat. CRITICAL fires only when *both* the short and long burn rates exceed the threshold. The two-window requirement is what separates a genuine budget emergency from a momentary blip. +Checking both a short window (for example, 5 minutes) and a long window (for example, 1 hour) together filters out brief spikes that don't represent a real budget threat. A `critical`-severity alert episode fires only when *both* the short and long burn rates exceed the threshold. The two-window requirement is what separates a genuine budget emergency from a momentary blip. ### Query structure @@ -68,11 +68,11 @@ FROM metrics-* burn_30m = errors_30m / total_30m, burn_6h = errors_6h / total_6h | EVAL severity = CASE( - // CRITICAL: both the fast and sustained windows exceed 14.4x the baseline error rate. + // critical: both the fast and sustained windows exceed 14.4x the baseline error rate. // Requiring both prevents a single brief spike from triggering a critical alert. - burn_5m > 14.4 AND burn_1h > 14.4, "CRITICAL", - // HIGH: same two-window logic at a lower threshold - burn_30m > 6.0 AND burn_6h > 6.0, "HIGH", + burn_5m > 14.4 AND burn_1h > 14.4, "critical", + // high: same two-window logic at a lower threshold + burn_30m > 6.0 AND burn_6h > 6.0, "high", "none" ) | WHERE severity != "none" // Only breaching SLOs become alert rows @@ -83,11 +83,7 @@ The burn rate multipliers (14.4×, 6×) reflect standard SLO error budget consum Because the query computes several window pairs in one pass, the lookback window on the rule must cover the longest window in the query (3 days in the example above). - - - +The `severity` column in `KEEP` maps directly to `episode.severity` on each resulting alert episode. For the accepted values and matching rules, see [Severity levels](author-rules.md#severity-levels). ## No-data detection [no-data-esql-query] @@ -147,13 +143,13 @@ FROM metrics-* | KEEP host.name, total_buckets, exceeding_buckets ``` -The rule's lookback window must cover all the buckets you want to check (50 minutes for 10 five-minute buckets in this example). If any bucket is missing from the data because the host stopped reporting briefly mid-window, `total_buckets` drops below 10 and the condition does not fire. Design the query so that gaps in reporting produce the behavior you want: either treating partial coverage as a non-breach or adjusting the `WHERE` filter to allow it. +The rule's lookback window must cover all the buckets you want to check (50 minutes for 10 five-minute buckets in this example). If any bucket is missing from the data because the host stopped reporting briefly mid-window, `total_buckets` drops below 10 and the condition doesn't fire. Design the query so that gaps in reporting produce the behavior you want: either treating partial coverage as a non-breach or adjusting the `WHERE` filter to allow it. ### Derivative aggregation [derivative-aggregation] -{{esql}} does not have a `DERIVATIVE` function. In the {{es}} aggregations API, a derivative pipeline aggregation calculates the rate of change between consecutive time buckets (for example, "how fast is this counter increasing per minute?"). There is no equivalent in {{esql}} today. +{{esql}} does not have a `DERIVATIVE` function. In the {{es}} aggregations API, a derivative pipeline aggregation calculates the rate of change between consecutive time buckets (for example, "how fast is this counter increasing per minute?"). There is no equivalent in {{esql}}. Use cases that require true per-bucket deltas (such as detecting a sudden acceleration in error rate) cannot be expressed as an {{esql}} rule at this time. Consider pre-computing deltas in an ingest pipeline or using a transform to write derived metrics to a separate index that your rule can then query with a standard threshold pattern. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md index f2a5258b45..dc275b3e35 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md @@ -5,13 +5,12 @@ applies_to: serverless: experimental products: - id: kibana -description: "Reference for rule configuration fields and documents written to `.rule-events` in the {{alerting-v2}}." +description: "Field reference for rule configuration and .rule-events documents in Kibana's experimental alerting system. Covers schedule, activation thresholds, and rule event output fields." --- -# Rule event and field reference [rule-reference] +# Rule event and field reference in the {{alerting-v2-system}} [rule-reference] - -Rule event fields are part of the {{alerting-v2}} in Kibana. This page lists technical fields for rule configuration and rule event documents written to `.rule-events`. +Rule event fields are part of the {{alerting-v2-system}} in {{kib}}. This page lists technical fields for rule configuration and rule event documents written to `.rule-events`. @@ -74,7 +73,7 @@ Grouping is configured in YAML. The fields listed here control how the rule part Each time a rule evaluates, {{kib}} writes one document per matched series to `.rule-events`. The `type` field determines the document kind: -- **signal:** A point-in-time record that the query matched. Useful for querying history or chaining into follow-on rules. Signal documents do not include `episode.*` fields. +- **signal:** A point-in-time record that the query matched. Useful for querying history or chaining into follow-on rules. Signal documents don't include `episode.*` fields. - **alert:** A lifecycle-tracked episode visible in the alert inbox, episode details, and triage views. Alert documents include `episode.*` fields and represent a breach that stays open until the condition clears. Both kinds share the base fields below. Only `alert` documents add the [Episode fields](#episode-fields) listed further down. @@ -88,7 +87,7 @@ Refer to [Query alerts and signals in Discover](../alerts/query-alerts-and-signa ### Signal and alert fields -These fields appear on all `.rule-events` documents, regardless of whether the rule is in Detect or Alert mode. +These fields appear on all `.rule-events` documents, regardless of whether the rule is in Signal or Alert mode. | Field | Type | Required | Description | |---|---|---|---| @@ -106,7 +105,7 @@ These fields appear on all `.rule-events` documents, regardless of whether the r --> :::{admonition} Fields not stored as a dedicated column -There is no top-level or nested `duration` field on `.rule-events` documents. For triage or reporting, derive duration from the alert UI or your own queries over timestamps and episode identifiers. +There's no top-level or nested `duration` field on `.rule-events` documents. For triage or reporting, derive duration from the alert UI or your own queries over timestamps and episode identifiers. @@ -121,11 +120,5 @@ These fields only appear on documents with `type: alert`, written by rules runni | `episode.id` | keyword | Episode identifier for this series. | | `episode.status` | keyword | One of: `inactive`, `pending`, `active`, `recovering`. | | `episode.status_count` | long | Count of consecutive evaluations in the current `episode.status`. Only set when `episode.status` is `pending` or `recovering`. | - - +| `episode.severity` | keyword | Severity level from the most recent breached event. One of: `info`, `low`, `medium`, `high`, `critical`. Not set when the query output does not include a `severity` column, or when the value does not match a recognized level. Never set on `recovered` or `no_data` events. | +| `episode.severity_max` | keyword | Highest severity level observed across the episode's lifetime (high-water mark). Enables routing or display based on peak severity, for example, "this episode peaked at `critical`". | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md index 2f9f0013d9..1803f0bd96 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md @@ -5,24 +5,30 @@ applies_to: serverless: experimental products: - id: kibana -description: "Use the rules list and rule details page in the {{alerting-v2}}: filters, search, bulk actions, and what you find in rule conditions." +description: "Search, filter, sort, and bulk-manage rules from the rules list in Kibana's experimental alerting system. Inline editing and a summary flyout let you update settings without a full page reload." --- -# View and manage rules in the {{alerting-v2}} [manage-rules] +# View and manage rules in the {{alerting-v2-system}} [manage-rules] +Rule management is part of the {{alerting-v2-system}} in {{kib}}. After a rule is created, edit its settings, pause it, remove it, and more from the page listing rules. The rules list gives you search, filter, sort, and bulk actions across all rules in the space. Selecting a rule name opens its details page, where you can review the full configuration and edit or act on it directly. +## Find and filter rules [find-filter-rules] -Viewing and managing rules is part of the {{alerting-v2}} in Kibana. After a rule is created, edit its settings, pause it, remove it, and more from the page listing rules. The rules list gives you search, filter, sort, and bulk actions across all rules in the space. Selecting a rule name opens its details page, where you can review the full configuration and edit or act on it directly. +Use the search bar at the top of the rules list to find rules by name or description. The search field accepts plain text. Each space-separated term is matched independently (terms are AND'd) using prefix matching. Type any part of a rule name or description to narrow the list. -## Find and filter rules [find-filter-rules] +Search matches rule name and description only. Tags and grouping fields are displayed in search results but aren't included in free-text search. Special characters in rule names and descriptions, including consecutive hyphens, are handled correctly. +Combine text search with filter controls to narrow results further by rule type, status, or tags. Select any column header to sort the list. Use bulk actions when you need to enable, disable, or delete multiple rules at once. -Use the search bar at the top of the rules list to find rules by name. The search field accepts plain text and matches against rule names without requiring structured query syntax — type any part of a rule name to narrow the list. Combine text search with filter controls to narrow results further by rule type, status, or tags. +## Quick-edit a rule [quick-edit-rule] -Select any column header to sort the list. Use bulk actions when you need to enable, disable, or delete multiple rules at once. +To update common rule settings without opening the full rule details page, use the inline edit option on any row in the rules list. The inline editor also opens from the rule summary flyout header. -## Rule summary flyout [rule-summary-flyout] +Editable fields in this view include name, description, tags, grouping key, time field, interval, lookback window, alert delay, recovery type, and recovery delay. The {{esql}} query and alert tracking behavior are read-only in this view. For changes to the query or rule mode, open the full rule details page. +Use inline edit when you need to adjust metadata or scheduling settings quickly without navigating away from the list. + +## Rule summary flyout [rule-summary-flyout] To inspect a rule without navigating away from the rules list, select the expand icon on any row. The rule summary flyout opens alongside the list and shows a snapshot of the rule: its status, last run time, recent alert episode activity, and quick actions such as enable, disable, and snooze. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md index c8abe7326b..8937f0c0cd 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md @@ -5,13 +5,13 @@ applies_to: serverless: experimental products: - id: kibana -description: "Complete field reference for YAML rule definitions in the {{alerting-v2}}: required fields, metadata, schedule, grouping, state transitions, no-data handling, and duration format." +description: "YAML rule definitions in Kibana's experimental alerting system support fields for detection mode, schedule, query, grouping, and recovery. Reference tables list all valid field values." --- -# YAML rule schema reference [yaml-rule-schema-reference] +# YAML rule schema reference for the {{alerting-v2-system}} [yaml-rule-schema-reference] -YAML rule schema is part of the {{alerting-v2}} in Kibana. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create rules using the YAML editor](create-rule-with-yaml.md). +YAML rule schema is part of the {{alerting-v2-system}} in {{kib}}. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create rules using the YAML editor](create-rule-with-yaml.md). ## Required fields @@ -39,14 +39,13 @@ YAML rule schema is part of the {{alerting-v2}} in Kibana. This page lists valid ## Recovery policy fields +The `recovery_policy` field is optional. When absent, the rule emits no recovery events and active alert episodes don't close automatically. Omitting `recovery_policy` is only possible when creating a rule via the API or Agent Builder. Rules created through the Kibana UI always include `recovery_policy.type: no_breach` by default. + | Field | Type | Accepted values | Description | |---|---|---|---| -| `recovery_policy.type` | string | `no_breach` or `query` | How recovery is detected. `no_breach` recovers when the query returns no results. `query` uses a separate recovery query. | +| `recovery_policy.type` | string | `no_breach` or `query` | How recovery is detected. `no_breach` recovers when the query returns no breach results for the active group. `query` uses a separate recovery query. | | `recovery_policy.query.base` | string | Valid {{esql}} query | Required when `recovery_policy.type` is `query`. The query that checks whether the condition has cleared. | - - ## State transition fields Only valid when `kind: alert`. Controls how many consecutive detections are required before an episode becomes active or recovers. From 2979014639068dcb2ca88ec01d8a3204bd587609 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Tue, 30 Jun 2026 16:14:53 -0400 Subject: [PATCH 05/23] [Alerting V2][Serverless & 9.5][M2] Rule changes from June 22, 2026 (#7077) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Updates rules docs for the experimental alerting system with content from M2 doc issues. Following the tech preview principle of accuracy over comprehensiveness, additions focus on stable concepts — why to choose certain options, when to use features, and how the system works. UI step-by-step procedures and incomplete API schemas are deferred to post-preview docs. --- ### ES|QL rule schema corrections: query, recovery, and no-data fields (#7004) PR #271758 replaced the old `evaluation.query.base` + `recovery_policy` schema with a new `query` discriminated union on `format`, plus `recovery_strategy` and `no_data_strategy`. **`yaml-rule-schema-reference.md`** — Replaced `evaluation.query.base` and `evaluation.query.blocks` with the new `query` discriminated union. Added a required top-level `query.format` field (`composed` or `standalone`) and separate field tables for each format: `query.base`, `query.breach.segment`, `query.recovery.segment` for composed rules, and `query.breach.query`, `query.recovery.query`, `query.no_data.query` for standalone rules. Replaced the "Recovery policy fields" section with a "Recovery strategy" section documenting the `recovery_strategy` field and its three accepted values (`no_breach`, `query`, `none`), including a constraint note for signal-mode rules. Replaced the "No-data fields" section with "No-data strategy" documenting `no_data_strategy` and its four values (`emit`, `last_known_status`, `recover`, `none`), with notes on the standalone-only constraint and the signal-mode restriction. Added the missing required `artifacts[].id` field to the artifacts table. ### `?param` placeholder syntax (#7004) **`configure-rule-query.md`** (new child page, see below) — Documented `?param` placeholder syntax, distinguishing reserved runtime parameters (`?_tstart`, `?_tend`) from UI form variables. Added code examples for both. ### Alert delay / activation thresholds (#7008) PR #273501 added an alert delay field to the threshold rule builder inside the rule form flyout. **`configure-rule-thresholds.md`** (new child page, see below) — Replaced the bare activation threshold field table with a mode table (Immediate, Breaches, Duration) that explains what each mode does and when to use it. Added a concrete example for combining Breaches and Duration with `AND`/`OR`. Added a Type column to both activation and recovery field tables. Linked to the duration format reference for timeframe fields. ### Alert activity timeline on the rule details page (#6874) PR #267866 added an alert activity timeline widget to the rule details overview tab. **`view-manage-rules.md`** — Added an Overview tab entry to the rule details page section, documenting the alert activity timeline, per-series state history, summary statistics (alert episodes started, recovered, still open, median duration), the "View all episodes" link filtered to the current rule and time range, and the behavior difference between grouped and ungrouped rules. Notes that the Overview tab is not shown for Signal-mode rules. ### Query preview tab in the rule summary flyout (#7007) PR #270484 added a query preview tab to the rule attachment sidebar, restricted to Agent Builder rule types. **`view-manage-rules.md`** — The rule summary flyout section notes that AI Agent builder rules include a query preview tab that renders the rule's underlying ES|QL in an interactive sandbox. --- ### Structural changes: rule creation pages consolidated and split The three separate rule creation pages (`create-rule-from-rule-builder.md`, `create-rule-with-yaml.md`, `create-rule-from-discover.md`) were consolidated into a single `create-a-rule.md` overview page, then split into four dedicated child pages — one per creation path. None of these pages were previously published, so no redirects are needed. **Deleted:** `create-rule-from-rule-builder.md`, `create-rule-with-yaml.md` **`create-a-rule.md`** (restructured to overview) — Now a brief overview table linking to each creation path. **`create-esql-rule.md`** (new) — Covers creating a rule using the ES|QL editor, including the query sandbox and YAML editor. **`create-rule-ai-agent.md`** (new) — Covers creating a rule using the AI Agent, including the proposal card, flyout tabs, save flow, and example prompts. **`use-rule-builder.md`** (new) — Covers the guided rule builder. Describes it as form-based setup with additional rule types planned. **`create-rule-from-discover.md`** (re-created as child page) — Covers creating a rule directly from a Discover session. **`rules.md`** — Updated links to point to the four new child pages. Renamed the "Create a rule" section to "Rule creation options" to avoid conflation with `create-a-rule.md`. Integrated the previously commented-out "How rule history works" content into the "What rules do" section as a closing paragraph, with a cross-reference to the field reference. --- ### Structural changes: ES|QL query patterns split into child pages `esql-query-patterns.md` was converted from a single long page into an index page with five child pages, ordered by complexity. Each child page carries the alerting system name in its `h1` heading for discoverability. The section was moved in the TOC to appear after `view-manage-rules.md`, so the navigation follows a create → configure → manage → reference flow. **`esql-query-patterns.md`** (restructured to index) — Now a brief intro sentence and a table linking to each pattern page with complexity labels. **`esql-first-rule-query.md`** (new) — Beginner page covering the simplest filter-only query structure. Includes an annotated example and an "adapt this query" section. **`esql-threshold-queries.md`** (new) — Covers single-series and grouped threshold queries using `STATS` aggregation. **`esql-no-data-detection.md`** (new) — Covers the last-seen pattern for detecting silent hosts. Lookback sizing and sensitivity guidance folded into inline code comments. **`esql-slo-burn-rate.md`** (new) — Covers SLO burn rate detection. Restructured with a simple single-tier example first, followed by the full multi-tier version. **`esql-persistent-breach.md`** (new) — Covers persistent breach detection using bucket counting. Added a variant showing how to relax the all-buckets requirement to allow gaps. --- ### Structural changes: configure-a-rule.md split into child pages `configure-a-rule.md` was converted from a single long page into an overview page with eight child pages — one per configuration setting. Alert-mode-only pages are labeled in both the heading and the intro. Each child page carries the alerting system name in its `h1` heading. **`configure-a-rule.md`** (restructured to overview) — Now an overview table linking to each setting page, with a Required column and Alert-mode-only entries labeled inline. **`configure-rule-mode.md`** (new) — Documents Signal and Alert mode, including a Best for column in the mode table and YAML field values. **`configure-rule-query.md`** (new) — Documents the base query and alert condition with inline examples showing the progression from a standalone base query to a query with an alert condition. Dynamic values (time bounds and form variables) are in a dedicated subsection with descriptive headings. **`configure-rule-severity.md`** (new) — Documents the five severity levels with Description and Urgency columns, how the system maps severity values, stored fields, and two examples (static and dynamic). **`configure-rule-grouping.md`** (new) — Documents grouping fields, BY clause alignment, and two examples with group fields annotated directly in the query. **`configure-rule-schedule.md`** (new) — Documents execution interval and lookback window with duration format, min/max bounds, and two examples showing how schedule choices affect the query window. **`configure-rule-thresholds.md`** (new, Alert mode only) — Documents activation and recovery thresholds with a mode table, typed field tables (positive integer / duration string / AND or OR), duration format links, and three examples. **`configure-no-data-handling.md`** (new) — Documents the four `no_data_strategy` values with descriptions, a limitation note, and two examples. **`configure-rule-tags.md`** (new, Alert mode only) — Documents tags (max 20, each max 128 characters) and runbooks with examples. --- ### Duplicate content removed and pages trimmed **`author-rules.md`** (deleted) — Content was progressively migrated to the new configuration child pages. Base query and alert condition documentation moved to `configure-rule-query.md`. Signal vs. Alert mode explanation moved to `configure-rule-mode.md`. The page contained no remaining unique content and was removed. No redirects needed as it was not previously published. **`rule-event-field-reference.md`** (trimmed) — Removed five opening sections that duplicated configuration content already covered by the new child pages (schedule, activation thresholds, recovery thresholds, no-data strategy, grouping). The page now focuses solely on `.rule-events` document fields. Added a clarifying note that episode fields are stored in `.rule-events` on the same document as the base fields, not in a separate index. Intro and frontmatter description updated to reflect the narrowed scope. --- ### Content quality improvements across new pages - **Em dashes removed** throughout. Replaced with semicolons, colons, commas, or sentence breaks depending on context. - **Examples sections** added to all new configuration pages. Examples describe realistic scenarios, explain the reasoning behind the configuration, and use ES|QL queries rather than YAML where the setting relates to detection logic. - **Accepted values and data types** added to configuration field tables where missing: count fields labeled as positive integers, operator fields show `AND` or `OR`, duration fields link to the duration format reference. - **Explicit anchors** added to `## Recovery strategy` and `### Episode fields` in existing reference pages to fix broken cross-references. - **`## Duration format`** section in `yaml-rule-schema-reference.md` given an explicit `[duration-format]` anchor for cross-linking. --- ### Issues confirmed as already covered or out of scope - **#6837** (Signal label renamed from "Detection only"): docs already use "Signal". No changes needed. - **#6870** (Alert/Signal mode select replaces toggle): Alert and Signal modes are already documented. UI control details are deferred. - **#6875** (Rules list empty state redesign): the creation paths in `rules.md` already match the redesigned empty state panels. No changes needed. - **#7005** (Simple actions from rule form): already covered by the existing note in `configure-rule-mode.md`. No changes needed. - **#6871** (Manage rules button on the episodes list): navigation element on the episodes list page, not the rules docs. Out of scope. - **#7015** (Query sandbox auto-opens on create): UI behavior detail about flyout initialization state. Deferred to post-preview step-by-step procedure docs. - **#7092** (YAML-only mode for non-representable rule configurations): deferred. The UI behavior and the list of non-representable configurations may change before tech preview ships. No changes included. ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - Cursor + Claude - [ ] No --- .../kibana-alerting-experimental/rules.md | 31 +--- .../rules/author-rules.md | 135 ---------------- .../rules/configure-a-rule.md | 130 ++------------- .../rules/configure-no-data-handling.md | 40 +++++ .../rules/configure-rule-grouping.md | 61 +++++++ .../rules/configure-rule-mode.md | 28 ++++ .../rules/configure-rule-query.md | 96 +++++++++++ .../rules/configure-rule-schedule.md | 53 ++++++ .../rules/configure-rule-severity.md | 85 ++++++++++ .../rules/configure-rule-tags.md | 42 +++++ .../rules/configure-rule-thresholds.md | 67 ++++++++ .../rules/create-a-rule.md | 24 +++ .../rules/create-esql-rule.md | 32 ++++ .../rules/create-rule-ai-agent.md | 34 ++++ .../rules/create-rule-from-discover.md | 38 ++--- .../rules/create-rule-from-rule-builder.md | 44 ----- .../rules/create-rule-with-yaml.md | 21 --- .../rules/esql-first-rule-query.md | 47 ++++++ .../rules/esql-no-data-detection.md | 32 ++++ .../rules/esql-persistent-breach.md | 45 ++++++ .../rules/esql-query-patterns.md | 152 ++---------------- .../rules/esql-slo-burn-rate.md | 75 +++++++++ .../rules/esql-threshold-queries.md | 59 +++++++ .../rules/rule-event-field-reference.md | 66 +------- .../rules/use-rule-builder.md | 17 ++ .../rules/view-manage-rules.md | 23 ++- .../rules/yaml-rule-schema-reference.md | 101 +++++++----- explore-analyze/toc.yml | 29 +++- 28 files changed, 976 insertions(+), 631 deletions(-) delete mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md delete mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md delete mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules.md index 3466834bbd..921cbb53c0 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules.md @@ -10,46 +10,25 @@ description: "Rules in Kibana's experimental alerting system define what to dete # Rules in the {{alerting-v2-system}} -Rules are part of the {{alerting-v2-system}} in {{kib}}. For rules in the existing Kibana alerting system, see [Rules in Kibana alerting](../alerts/create-manage-rules.md). +A rule is where the {{alerting-v2-system}} starts. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. -A rule is where the {{alerting-v2-system}} starts. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. +This page explains what rules do, what they don't control, and how to choose a creation path. ## What rules do [detection-and-notification] - On each run, a rule executes an {{esql}} query against your data. If the query finds a match and the rule is in Signal mode, it writes a _signal_, a point-in-time record that the condition was met. In Alert mode, it also maintains an _alert episode_ for each matched series, tracking state from first breach through recovery. When creating a rule, choose Signal mode to record and query results without alerting anyone, or Alert mode when you want to track issues and route notifications. ## What rules don't do -Rules only define *what* to detect. They don't control notifications, who gets notified, or when. That's the job of action policies — global objects, scoped to your space, that match alert episodes from any rule. A rule has no say in which policies pick it up. +Rules only define *what* to detect. They don't control notifications, who gets notified, or when. That's the job of action policies, which are global objects scoped to your space that match alert episodes from any rule. A rule has no say in which policies pick it up. This separation means you can build and test a rule without anyone getting paged, update notification routing without touching the rule, and have multiple action policies respond to the same rule independently. -% ## How rule history works - -% Rules never overwrite old data. Each evaluation appends rows to `.rule-events`, giving you a complete, queryable history of every time the condition was met, when it cleared, and what the data looked like. - -% When a rule groups by fields (for example `BY host.name`), each unique combination is its own series, identified by `group_hash`. An alert episode spans one lifecycle arc on a series from first breach through recovery, identified by `episode_id`. - -% You can query this history in Discover, build dashboards from it, or write follow-on rules that read `.rule-events` as a data source. - -## Create a rule [create-a-rule] - -Rules in the {{alerting-v2-system}} are created through a flyout that opens from the **Create rule** button in the rules list. Three options are available: - -- **Create ES|QL rule**: Write the detection query as {{esql}} directly, with a live preview of results and a YAML editor also available. Use this when you want full control over the query. See [Create rules](rules/create-rule-from-rule-builder.md). -- **Create with AI Agent**: Describe what you want to detect in plain language. The AI agent generates a rule definition and walks you through reviewing and saving it. Use this when you know the problem but aren't sure how to write the {{esql}}. -- **Start from a rule builder**: Choose a structured rule type and fill in a guided form. The builder generates the {{esql}} query automatically. The [Threshold Alert](rules/create-rule-from-rule-builder.md#threshold-alert) type is available. Use this when you want to create a standard metric-threshold rule without writing {{esql}} by hand. - -If you already have an {{esql}} query working in Discover, you can also [create a rule directly from there](rules/create-rule-from-discover.md) to skip re-entering the query. - ## Next steps -- **[Author rules](rules/author-rules.md):** Write the {{esql}} query, choose Signal or Alert mode, and structure your data sources and conditions. +- **[Create a rule](rules/create-a-rule.md):** Compare creation paths and choose the one that fits your workflow. - **[Configure a rule](rules/configure-a-rule.md):** Set the schedule, grouping, activation thresholds, recovery conditions, and no-data behavior. - **[View and manage rules](rules/view-manage-rules.md):** Enable, disable, clone, delete, and bulk-manage rules from the rules list. -- **Rule Doctor:** Analyze your rules for duplicates, stale conditions, threshold tuning opportunities, and coverage gaps. Rule Doctor surfaces findings with impact and confidence ratings and tracks each insight through an open → applied or dismissed lifecycle. Access it from the {{alerting-v2-system}} navigation. - - \ No newline at end of file +- **[ES|QL query patterns](rules/esql-query-patterns.md):** Browse query patterns ordered by complexity, from a basic event filter to SLO burn rate and persistent breach detection. \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md deleted file mode 100644 index 7fa4df90a1..0000000000 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -navigation_title: Author rules -applies_to: - stack: experimental 9.5+ - serverless: experimental -products: - - id: kibana -description: "Write ES|QL detection queries for rules in Kibana's experimental alerting system. Choose Signal or Alert mode, structure base queries and conditions, and assign severity levels." ---- - -# Rule authoring in the {{alerting-v2-system}} [author-rules] - -Rule authoring is part of the {{alerting-v2-system}} in {{kib}}. Authoring a rule means deciding three things: what condition in your data counts as a problem, whether you want the rule to silently record matches or actively track issues through to resolution, and which fields to carry forward onto each alert event so you can route and triage effectively. Getting these decisions right in the query is what makes the difference between a rule that fires on everything and one that surfaces the problems that actually need attention. - -This page covers the query concepts behind a rule definition. For settings beyond the query (such as schedules, grouping, and lifecycle thresholds), refer to [Configure a rule](configure-a-rule.md). Once you understand what goes into a rule, you can write one using the [rule builder](create-rule-from-rule-builder.md), [YAML editor](create-rule-with-yaml.md), or [a Discover session](create-rule-from-discover.md). - -## Choose a rule mode - -Before creating the rule, decide what you want it to do: - -| Mode | What it does | -| --- | --- | -| Signal (`kind: signal`) | Records query matches as signals. No alert episodes, no notifications. Good for testing a query or building a data history without alerting anyone. | -| Alert (`kind: alert`) | Records matches and maintains alert episodes with lifecycle states. Alert episodes appear on the **Alerts** page and can be matched by action policies for notifications. | - -You can switch a rule's mode after creation from the rule list or rule detail page. - -## The {{esql}} query [esql-query-structure] - -Every rule has two parts to its query: the base query and the alert conditions. - -### Base query (required) -The main {{esql}} expression. It runs on every evaluation, selects data from `FROM`, shapes results with `STATS`, `WHERE`, `EVAL`, and controls which fields are stored with `KEEP`. The base query always runs, even when no breach occurs, which is what enables no-data detection and recovery. - -### Alert conditions (optional) -A `WHERE` clause applied after the base query. Only rows that pass the alert condition are treated as breaches. Without an alert condition, every row returned by the base query is a breach. - -```esql --- Base query: compute average CPU per host -FROM metrics-* -| STATS avg_cpu = AVG(system.cpu.total.pct) BY host.name - --- Alert condition: only rows above the threshold count as breaches -WHERE avg_cpu > 0.9 -``` - -The `KEEP` command controls which fields appear on each stored alert event. Only the fields you `KEEP` are available for policy matchers, grouping keys, and triage in the Alerts UI. - -### Recovery condition [recovery-condition] - -Recovery conditions are optional. They determine when an active alert episode closes. - -Three recovery types are available: - -| Type | Behavior | -| --- | --- | -| Default | The alert episode recovers automatically when the alert condition is no longer met. | -| Custom | Uses a separate {{esql}} expression you define. The alert episode recovers when that expression returns no rows. | - -When no recovery condition is configured, Default recovery applies. Use a custom recovery condition when the absence of a breach isn't a reliable recovery indicator — for example, when the alert condition uses a narrow lookback window and you want recovery to require the condition to stay clear across a longer period, or when the recovery logic requires a different query shape than the alert detection. - -## Data sources - -Use `FROM` to point the rule at the indices or data streams to read. The query itself defines the scope. There's no separate data source step. - -```esql -FROM logs-checkout-service-* -| WHERE http.response.status_code >= 500 -| STATS error_count = COUNT(*) BY service.name -| KEEP service.name, error_count -``` - -The [{{esql}} reference](elasticsearch://reference/query-languages/esql.md) covers all available commands and processing functions. - -## Conditions and thresholds [conditions-and-thresholds] - -The alert condition in {{esql}} defines what counts as a breach in each evaluation. - -The activation and recovery thresholds on the rule are separate from the query. They control how many consecutive breaches must occur, or how long the condition must persist, before an alert episode becomes active or moves back to inactive. Those settings are in [Configure a rule](configure-a-rule.md#activation-recovery-thresholds). - - - -## Severity levels [severity-levels] - -Severity is a first-class field on alert episodes in the {{alerting-v2-system}}. To set severity, include a column named `severity` in your ES|QL query output and add it to your `KEEP` list. The framework reads that column after each evaluation and maps it to one of five fixed levels: - -| Value | Meaning | -| --- | --- | -| `info` | Informational; lowest urgency | -| `low` | Low-severity condition | -| `medium` | Moderate-severity condition | -| `high` | High-severity condition | -| `critical` | Critical; highest urgency | - -Severity matching is case-insensitive. Values that don't match one of the five levels are silently ignored — the alert episode is still created, but `episode.severity` is not set. - -Severity is set only on `breached` rule events. `recovered` and `no_data` events don't carry a severity value. - -When severity is set, the framework stores two fields on the alert episode: - -- `episode.severity` — The severity value from the most recent breached event (current state). -- `episode.severity_max` — The highest severity level observed across the episode's lifetime. Useful for routing like "this episode peaked at critical." - -Both fields are available for action policy matchers. Refer to [Rule event and field reference](rule-event-field-reference.md#episode-fields) for more information about these fields. - -```esql -FROM metrics-* -| STATS - errors_5m = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 5 minutes), - total_5m = COUNT_IF(@timestamp >= NOW() - 5 minutes) - BY service.name -| EVAL burn_5m = errors_5m / total_5m -| EVAL severity = CASE( - burn_5m > 14.4, "critical", - burn_5m > 6.0, "high", - burn_5m > 1.0, "medium", - "low" - ) -| WHERE burn_5m > 1.0 -| KEEP service.name, burn_5m, severity -``` - -The `severity` column in `KEEP` is what tells the framework to set `episode.severity` on each resulting alert episode. - -## Next steps - -Once you understand the query structure, explore [{{esql}} query patterns](esql-query-patterns.md) for advanced use cases including SLO burn rate queries, no-data detection, persistent breach detection, and unsupported operations. - - diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md index 2dd23ec35b..9ebce4c2b9 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -5,127 +5,23 @@ applies_to: serverless: experimental products: - id: kibana -description: "Configure rules in the experimental alerting system: mode, ES|QL, grouping, schedule, lookback, activation and recovery, no-data handling, tags, and evaluation." +description: "Configure rules in the experimental alerting system: mode, ES|QL query, grouping, schedule, activation and recovery thresholds, no-data handling, tags, and evaluation." --- -# Configure a rule in {{alerting-v2-system}} [rule-settings] +# Configure a rule in the {{alerting-v2-system}} [rule-settings] - -Rule configuration is part of the {{alerting-v2-system}} in {{kib}}. The {{esql}} query defines what a rule detects. The settings on this page determine whether it behaves correctly in production: how often it runs, how it groups related problems, when it opens and closes alerts, and what it does when data stops arriving. - -For query authoring, refer to [Author rules](author-rules.md). +Rules in the {{alerting-v2-system}} have three required settings and several optional ones. The table below lists each setting, what it controls, and whether it is required to save a rule. -:::{note} -For Alert-mode rules, you can create and attach action policies directly from the rule form's **Actions** step. Existing action policies that match the rule are listed on load. If none exist, an onboarding panel appears. Action policies are created or updated alongside the rule when you save. The **Actions** step is not shown for Signal-mode rules. - -You can also manage action policies independently from the **Action policies** area, using KQL matchers to scope them to any episodes you want to route. -::: - -## Rule mode [rule-mode] - -Choose a mode that matches how you want to use results: - -| Mode | Behavior | -| --- | --- | -| Signal | Signals only: the rule produces detections without alert lifecycle tracking or notifications. | -| Alert | Lifecycle tracking and actions. Alerts move through states (pending, active, recovering, and so on), and you can attach action policies so alert episodes dispatch through workflows. | - -Several settings on this page apply only when the rule is in Alert mode (`kind: alert`). - -## {{esql}} query [esql-query-rule] - -The rule's {{esql}} query defines what to evaluate. It has a base query and an optional alert condition. Together they drive which rows become alert events and how no-data behavior applies. See [{{esql}} query structure](author-rules.md#esql-query-structure) for how those pieces interact with no-data behavior and `KEEP`. - -## Rule grouping [rule-grouping] - - -Rule grouping splits alert event generation by one or more group key fields so that each unique combination of field values produces its own alert series. Each series has independent lifecycle tracking, recovery detection, and per-series snooze. - -Group key fields must align with the `BY` clause in your {{esql}} query's `STATS` command. See [Author rules](author-rules.md) for query patterns. - -When writing a rule that uses grouping, writing the query first and then specifying group fields avoids mismatches between the query output and the grouping configuration. The group fields in the rule form reflect the columns produced by the `STATS ... BY` clause, so if you add or remove a `BY` field in the query, the corresponding group field must be updated to match. - -Note that rule grouping is separate from notification grouping on an action policy, which controls how alert episodes batch into messages. - - - -## Schedule and lookback [schedule-lookback] - - -The schedule and lookback settings control how often a rule runs and how far back it looks when evaluating data. - -### Execution interval - -The execution interval (`schedule.every`) determines how frequently the rule evaluates. - -{{kib}} enforces a minimum interval of 5 seconds and a maximum of 365 days for duration fields (including this one). Values outside that range are rejected. - -### Lookback window - -The lookback window (`schedule.lookback`) determines the time range that the {{esql}} query covers. - -The lookback must not exceed 365 days. If the lookback is shorter than the execution interval, evaluations can miss data between runs. Use a lookback at least as long as the execution interval unless you have a deliberate reason not to. - -## Activation and recovery thresholds [activation-recovery-thresholds] - - -Activation and recovery thresholds control when alerts transition between lifecycle states. They reduce noise from short spikes and from rapid flapping between active and recovered. - -These settings are only available for Alert-mode rules (`kind: alert`). - -### Activation thresholds - -Configure activation using count, timeframe, or both: - -| Field | Description | -| --- | --- | -| `pending_count` | Consecutive breaches required | -| `pending_timeframe` | Minimum duration the condition must persist (shown as **Alert delay** in the UI) | -| `pending_operator` | How to combine count and timeframe (`AND` or `OR`) | - -Each timeframe value must be between 5 seconds and 365 days. - -### Recovery thresholds - -| Field | Description | -| --- | --- | -| `recovering_count` | Consecutive recoveries required | -| `recovering_timeframe` | Minimum duration for recovery | -| `recovering_operator` | How to combine count and timeframe (`AND` or `OR`) | - -Time frame fields use the same 5 seconds to 365 days bounds as activation timeframes. - -:::{note} -The `recovery_policy` field controls how recovery is detected, separately from how many recoveries are required. When creating a rule through the UI, `recovery_policy.type` defaults to `no_breach`, which recovers the alert episode when its active group no longer appears in the breach batch. When creating a rule through the API or Agent Builder, you can omit `recovery_policy` entirely to suppress recovery events and keep alert episodes active until closed manually. For the full field reference, go to [YAML rule schema reference](yaml-rule-schema-reference.md#recovery-policy-fields). -::: - -## No-data handling [no-data-handling] - -No-data handling controls what happens when a rule executes and the base query returns no results. Proper configuration prevents false recoveries and misleading `no_data` events when data sources stop reporting. - -### Behaviors - -Set `no_data.behavior` to one of the following values: - -| Behavior | Effect | -| --- | --- | -| `no_data` | Record a no-data event (default) | -| `last_status` | Carry forward the previous status | -| `recover` | Treat absence as recovery | - -These behaviors apply when the base query returns zero rows. They don't help when you want to *detect* that a specific host or data source has gone silent. That requires a different query approach. See [No-data detection](esql-query-patterns.md#no-data-esql-query) in the authoring guide for an {{esql}} pattern that surfaces silent sources as alert rows. - -## Tags and investigation guide [tags-investigation] - -Alert-mode rules support two optional metadata fields: - -- **Tags**: Free-form labels for filtering and organization. -- **Investigation guide**: A runbook stored with the rule so responders have context when an alert fires. - -## Evaluate rule output [evaluate-rule-output] - -Before relying on a rule in production, evaluate it against recent data by running a preview. A full evaluation surfaces how many rows the query returns, how many alert events would be generated, sample alert event documents, and a histogram of matching row counts over time. +| Setting | Description | Required | +| --- | --- | --- | +| [Rule mode](configure-rule-mode.md) | Signal or Alert. Controls whether matching rows generate signal documents or tracked alert episodes. | Required | +| [ES\|QL query](configure-rule-query.md) | The detection logic and the parameters available in query expressions. | Required | +| [Schedule and lookback](configure-rule-schedule.md) | How often the rule evaluates and how far back the query looks. | Required | +| [Severity](configure-rule-severity.md) | Assign severity levels to alert episodes using a `severity` column in query output. | Optional | +| [Grouping](configure-rule-grouping.md) | Track multiple subjects (hosts, services, users) as independent alert series in one rule. | Optional | +| [Activation and recovery thresholds](configure-rule-thresholds.md) | Reduce noise with delay modes for opening and closing alert episodes. (Alert mode only) | Optional | +| [No-data handling](configure-no-data-handling.md) | What the rule records when the base query returns no results. | Optional | +| [Tags and runbooks](configure-rule-tags.md) | Free-form labels and investigation guides attached to the rule. (Alert mode only) | Optional | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md new file mode 100644 index 0000000000..3e47fc0622 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md @@ -0,0 +1,40 @@ +--- +navigation_title: No-data handling +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Configure no-data handling for rules in Kibana's experimental alerting system to control what happens when a query returns no results." +--- + +# No-data handling in the {{alerting-v2-system}} [no-data-handling] + +No-data handling is an optional setting for rules in the {{alerting-v2-system}}. Use `no_data_strategy` to control what the rule records when the base query returns no results. Setting this correctly prevents false recoveries and misleading `no_data` events when data sources stop reporting. + +Set `no_data_strategy` to one of the following values: + +| Value | Description | +| --- | --- | +| `emit` | Record a no-data event. | +| `last_known_status` | Hold the last known lifecycle state. An active breach stays active; a recovered episode stays recovered. | +| `recover` | Treat absence as recovery. | +| `none` | Turn off no-data detection | + +:::{note} +`no_data_strategy` does not detect when a specific host or data source stops reporting while others continue. Refer to [No-data detection](esql-no-data-detection.md) for an {{esql}} pattern that surfaces silent sources as alert rows. +::: + +## Examples + +### Maintain alert state during a metrics collection outage + +This rule monitors infrastructure CPU. If the metrics collection agent stops sending data, you don't want an active CPU breach to auto-recover just because the query returned nothing. Set `no_data_strategy` to `last_known_status`. The rule holds the alert in its current state until data resumes. + +Use this when an empty query result most likely means a pipeline problem rather than a genuine recovery. + +### Surface a broken data pipeline as an alert + +This rule monitors for login events from an identity provider. If no events appear in the lookback window, it's unusual enough to warrant attention: either the pipeline is broken or something has suppressed activity. Set `no_data_strategy` to `emit`. The absence is recorded as a `no_data` event in `.rule-events`, making it visible alongside other rule activity. + +Use this when receiving no data is itself a signal worth investigating. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md new file mode 100644 index 0000000000..50fd62d759 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md @@ -0,0 +1,61 @@ +--- +navigation_title: Grouping +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Configure rule grouping in Kibana's experimental alerting system to track multiple subjects as independent alert series." +--- + +# Rule grouping in the {{alerting-v2-system}} [rule-grouping] + +Rule grouping is an optional setting in the {{alerting-v2-system}} that lets a single rule track multiple things independently. For example, a rule monitoring CPU usage across hosts can produce a separate alert series for each host, rather than one alert for everything combined. + + + +:::{note} +Rule grouping controls how alert series are created. Notification grouping (configured on an action policy) controls how those alert episodes are batched into messages. These are separate settings. +::: + +## Aligning `BY` fields with your rule's query + +The `BY` fields you specify for grouping must match the columns in the `BY` clause of your {{esql}} `STATS` command. If they don't match, the grouping configuration won't work as expected. + +:::{tip} +Write the query first, then set the group fields. That way the `BY` columns are already defined and you can select them directly. If you later add or remove a `BY` field in the query, update the group fields to match. +::: + + + +## Examples + +### Track error rates per service + +This rule counts HTTP errors per service and opens a separate alert series for each service that exceeds the threshold. Each service gets its own lifecycle: if the checkout service recovers but the payments service stays critical, those are tracked independently. + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend +| STATS error_count = COUNT_IF(http.response.status_code >= 500) BY service.name // Group field: one series per service +| WHERE error_count > 10 +| KEEP service.name, error_count +``` + +Without a matching `grouping.fields` entry, the rule treats all services as a single combined series. A spike in one service would activate the alert for everything, and recovery requires all services to drop below the threshold at the same time. + +### Track CPU usage per host and region + +When the query groups by multiple fields, include all of them in `grouping.fields` to create one alert series per unique combination. + +```esql +FROM metrics-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend +| STATS avg_cpu = AVG(system.cpu.total.pct) BY host.name, cloud.region // Group fields: one series per host+region pair +| WHERE avg_cpu > 0.90 +| KEEP host.name, cloud.region, avg_cpu +``` diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md new file mode 100644 index 0000000000..495a65c905 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md @@ -0,0 +1,28 @@ +--- +navigation_title: Rule mode +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Choose between Signal and Alert mode for rules in Kibana's experimental alerting system." +--- + +# Rule mode in the {{alerting-v2-system}} [rule-mode] + +Rule mode is a required setting for rules in the {{alerting-v2-system}}. Rule mode set by the rule creation method and some creation paths only support one mode. Refer to [Create a rule](create-a-rule.md) for available options. + +| Mode | Behavior | Best for | +| --- | --- | --- | +| Signal | Records each matching row as a signal document. No alert episodes, no notifications. | Testing a new query, building detection history, or observing matches without notifying anyone. | +| Alert | Creates an alert episode for each matching row. Episodes are tracked through lifecycle states, appear on the **Alerts** page, and can be routed to notifications by action policies. | Production rules where breaches should be tracked, escalated, or routed to a notification channel. | + +## Examples + +### Build detection history before enabling alerts + +You're writing a new detection query and want to verify it produces the results you expect before anyone gets paged. Create the rule in Signal mode so matches are recorded in `.rule-events` and you can inspect them in Discover without opening any alert episodes or triggering notifications. Once the matches look correct, edit the rule and switch it to Alert mode. + +### Route critical episodes to an on-call workflow + +You have a checkout service error rate rule and want on-call engineers notified when it fires. Create the rule in Alert mode so each breach opens a tracked episode that action policies can route to a notification channel. The rule's episodes appear on the **Alerts** page and are visible to any action policy whose KQL matcher matches the episode fields. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md new file mode 100644 index 0000000000..5263a262a5 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md @@ -0,0 +1,96 @@ +--- +navigation_title: ES|QL query +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Configure the ES|QL query and query parameters for rules in Kibana's experimental alerting system." +--- + +# {{esql}} query in the {{alerting-v2-system}} [esql-query-rule] + +Every rule in the {{alerting-v2-system}} uses an {{esql}} query to define what to evaluate. The query has two parts: a base query that shapes and filters the data, and an optional alert condition that determines which rows become alert events. For more advanced use cases, the query also supports [dynamic values](#dynamic-query-values) for filtering by the evaluation window or setting configurable thresholds through the rule form. + +## Base query [query-base] + +The base query is the main {{esql}} expression. Use `FROM` to point the rule at the indices or data streams to read. Shape results with `STATS`, `WHERE`, and `EVAL`, and control which fields are stored with `KEEP`. The base query runs on every evaluation, even when no match occurs, which is what enables no-data detection and recovery. The [{{esql}} reference](elasticsearch://reference/query-languages/esql.md) covers all available commands and processing functions. + +This query counts HTTP 5xx errors per service over the lookback window and stores only the fields needed for triage: + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend +| STATS error_count = COUNT_IF(http.response.status_code >= 500) BY service.name +| KEEP service.name, error_count +``` + +Without an alert condition, every row returned by this query is treated as a breach, so the rule fires for every service that logged at least one 5xx error. + +## Alert condition [query-alert-condition] + +The alert condition is an optional `WHERE` clause appended after the base query. Only rows that pass the condition are treated as breaches. Use an alert condition when the base query returns aggregate results and you only want to alert when a value crosses a threshold. + +This example extends the base query above to only fire when a service exceeds 10 errors: + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend +| STATS error_count = COUNT_IF(http.response.status_code >= 500) BY service.name +| KEEP service.name, error_count +// Alert condition: only services with more than 10 errors become breaches +| WHERE error_count > 10 +``` + +The `KEEP` command controls which fields appear on each stored alert event. Only the fields in `KEEP` are available for action policy matchers, grouping keys, and triage. + +## Use dynamic values in your rule query [dynamic-query-values] + +{{esql}} rule queries support two kinds of parameters that make queries more dynamic: time bounds that the executor injects automatically, and form variables you define when creating a rule. You don't need either to write a working rule, but they're useful for scoping queries precisely to the evaluation window or making thresholds configurable without editing the query. + +### Filter your query to the evaluation window (`?_tstart` and `?_tend`) [time-bound-parameters] + +`?_tstart` and `?_tend` are reserved parameter names that the rule executor binds automatically on every evaluation. They hold the start and end timestamps of the lookback window, so you can scope a query to exactly the period the rule is evaluating: + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend +| STATS error_count = COUNT(*) BY service.name +| WHERE error_count > 10 +``` + +These parameters work across all rule creation methods. + +### Set configurable values in the rule form (`?param`) [form-variables] + +When creating a rule through the form, you can use `?param` placeholders, such as `?threshold`, as {{esql}} Control variables. The form resolves these variables and inlines their values into the query before saving. The stored rule and the YAML representation of it contains the resolved values, not the placeholder tokens. + +## Examples + +### Scoping a query to the evaluation window + +This query counts HTTP errors per service over the rule's lookback window. `?_tstart` and `?_tend` are bound automatically at runtime, so the query always covers exactly the configured window regardless of when the rule runs. + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend +| STATS error_count = COUNT_IF(http.response.status_code >= 500) BY service.name +| WHERE error_count > 0 +| KEEP service.name, error_count +``` + +If you omit the time filter, the query scans the full index on every evaluation, which increases query cost and can return stale matches from earlier runs. + +### Using a form variable for a configurable threshold + +This query uses `?threshold` as a form variable so the threshold can be set in the rule form UI without editing the query directly. When the rule is saved, the form resolves `?threshold` to its configured value and inlines it. The stored query contains the literal number, not the placeholder. + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend +| STATS p99_latency = PERCENTILE(http.response_time, 99) BY service.name +| WHERE p99_latency > ?threshold +| KEEP service.name, p99_latency +``` + +Because `?threshold` is resolved before saving, YAML and API representations of this rule always show the resolved value. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md new file mode 100644 index 0000000000..9bbc393fc6 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md @@ -0,0 +1,53 @@ +--- +navigation_title: Schedule and lookback +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Configure the execution schedule and lookback window for rules in Kibana's experimental alerting system." +--- + +# Schedule and lookback in the {{alerting-v2-system}} [schedule-lookback] + +Schedule and lookback are required settings for rules in the {{alerting-v2-system}}. They control how often a rule runs and how far back it looks when evaluating data. + +Both fields accept duration strings such as `30s`, `5m`, `2h`, or `7d`. Refer to [Duration format](yaml-rule-schema-reference.md#duration-format) for supported units. + +## Execution interval + +The execution interval (`schedule.every`) determines how frequently the rule evaluates. The minimum is `5s` and the maximum is `365d`. Values outside that range are rejected. + +## Lookback window + +The lookback window (`schedule.lookback`) determines the time range that the {{esql}} query covers. The minimum is `5s` and the maximum is `365d`. + +If the lookback is shorter than the execution interval, evaluations can miss data between runs. Use a lookback at least as long as the execution interval unless you have a deliberate reason not to. + +## Examples + +### High-frequency security rule + +This rule detects a burst of failed login attempts. Because the threat can develop quickly and needs fast detection, the interval is set to **1 minute** and the lookback to **5 minutes**. The 5-minute lookback is five times the interval, so a burst that straddles two evaluation windows is never missed. + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend // Covers the 5-minute lookback on each evaluation +| STATS failed_logins = COUNT_IF(event.outcome == "failure") BY user.name +| WHERE failed_logins > 10 +| KEEP user.name, failed_logins +``` + +The `?_tstart` and `?_tend` parameters are automatically bound to the lookback window, so the query always covers exactly the configured 5-minute range. + +### Cost-optimized infrastructure rule + +This rule monitors disk utilization for capacity planning. Fast response isn't critical, so the interval is set to **15 minutes** and the lookback to **30 minutes**. The wider window smooths out brief spikes that don't indicate a real capacity problem, reducing evaluation cost without sacrificing coverage. + +```esql +FROM metrics-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend // Covers the 30-minute lookback on each evaluation +| STATS max_disk_pct = MAX(system.filesystem.used.pct) BY host.name, system.filesystem.mount_point +| WHERE max_disk_pct > 0.90 +| KEEP host.name, system.filesystem.mount_point, max_disk_pct +``` diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md new file mode 100644 index 0000000000..0c5dfa27c8 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md @@ -0,0 +1,85 @@ +--- +navigation_title: Severity +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Assign severity levels to alert episodes in Kibana's experimental alerting system using a severity column in ES|QL query output." +--- + +# Severity in the {{alerting-v2-system}} [rule-severity] + +Severity is an optional setting for rules in the {{alerting-v2-system}}. To set it, include a column named `severity` in your {{esql}} query output and add it to your `KEEP` list. The framework reads that column after each evaluation and maps it to one of five fixed levels: + +| Value | Description | Urgency | +| --- | --- | --- | +| `info` | Informational event worth recording. | No action required. | +| `low` | Minor condition that may need monitoring. | Review when convenient. | +| `medium` | Notable condition that warrants investigation. | Investigate soon. | +| `high` | Serious condition requiring prompt attention. | Address promptly. | +| `critical` | Severe condition requiring immediate action. | Act immediately. | + +## How the {{alerting-v2-system}} maps severity values + +The {{alerting-v2-system}} maps the `severity` column to an internal level after each evaluation using the following rules: + +- Matching is case-insensitive. +- Values that don't match one of the five levels are silently ignored. The alert episode is still created, but `severity` isn't set. +- Severity is only set on `breached` events. `recovered` and `no_data` events don't carry a severity value. + +## Stored fields + +When severity is set, the {{alerting-v2-system}} stores the following field on the alert episode, available to action policy matchers: + +| Field | Description | +| --- | --- | +| `severity` | The severity value from the most recent breached event. | + +Refer to [Rule event and field reference](rule-event-field-reference.md#episode-fields) for more information about this field. + +## Examples + +### Static severity for a simple threshold rule + +If every breach of a rule is equally urgent, assign a fixed severity rather than computing it dynamically. The `EVAL` command adds a constant `severity` column to every row the query returns. + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend +| STATS error_count = COUNT_IF(http.response.status_code >= 500) BY service.name +| WHERE error_count > 100 +| EVAL severity = "critical" +| KEEP service.name, error_count, severity +``` + +Every breach from this rule produces a `critical` episode. Use this when the threshold itself represents a critical condition and intermediate severity levels don't apply. + +### Dynamic severity based on burn rate + +Use `CASE` to map a computed metric to different severity levels. This query grades each service's error rate: services consuming error budget at 14.4× baseline or above are `critical`; those between 6× and 14.4× are `high`; and so on. Only services above 1× are returned, so below-threshold services don't generate alert rows. + +```esql +FROM metrics-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend // Bind to the rule's configured lookback window +| STATS + errors = COUNT_IF(outcome == "failure"), + total = COUNT(*) + BY service.name +| EVAL burn_rate = errors / total +| EVAL severity = CASE( + burn_rate > 14.4, "critical", + burn_rate > 6.0, "high", + burn_rate > 1.0, "medium", + "low" + ) +| WHERE burn_rate > 1.0 +| KEEP service.name, burn_rate, severity +``` + +- **`WHERE`** (time filter): Scopes the query to the rule's configured lookback window using the reserved `?_tstart` and `?_tend` parameters. +- **`STATS`**: Counts failures and total requests, grouped by service. +- **`EVAL burn_rate`**: Computes the error rate as a fraction of failures to total requests. +- **`EVAL severity`**: Maps the burn rate to a severity level. +- **`WHERE burn_rate`**: Only services above the minimum threshold count as breaches. +- **`KEEP`**: Includes `severity` in the output so the {{alerting-v2-system}} reads and stores it. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md new file mode 100644 index 0000000000..75bcd88429 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md @@ -0,0 +1,42 @@ +--- +navigation_title: Tags and runbooks (Alert mode only) +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Add tags and runbooks to Alert-mode rules in Kibana's experimental alerting system for filtering and investigation context." +--- + +# Tags and runbooks in the {{alerting-v2-system}} (Alert mode only) [tags-investigation] + +Tags and runbooks are optional metadata fields for Alert-mode rules in the {{alerting-v2-system}}. + +- **Tags**: Free-form labels for filtering and organization. Maximum 20 tags per rule; each tag can be up to 128 characters. +- **Runbooks**: An investigation guide stored with the rule so responders have context when alerts are generated. + +## Examples + +### Tag a rule for team ownership and severity + +Tags make it easy to filter alerts by team, environment, or severity tier. For a checkout service rule, you might add tags like: + +- `team:payments` +- `env:production` +- `sev:p1` + +On-call engineers can then narrow the alerts view to rules their team owns without scanning every active episode. + +### Add a runbook with triage steps + +A runbook gives responders immediate context when an alert fires. Write it as plain text in the rule's description field. Include enough detail that an engineer unfamiliar with the service can triage without asking for help: + +``` +Fires when checkout error rate exceeds 10% for 3 consecutive evaluations. + +Triage steps: +1. Check the checkout service deployment history in the last 30 minutes. +2. Review the error breakdown dashboard: https://kibana.example.com/dashboards/checkout-errors +3. If errors are concentrated in one region, escalate to the infra team. +4. If errors are global, page the payments on-call lead. +``` diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md new file mode 100644 index 0000000000..b0e2865a9a --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md @@ -0,0 +1,67 @@ +--- +navigation_title: Activation and recovery thresholds (Alert mode only) +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Configure activation and recovery thresholds for Alert-mode rules in Kibana's experimental alerting system to reduce noise from spikes and flapping." +--- + +# Activation and recovery thresholds in the {{alerting-v2-system}} (Alert mode only) [activation-recovery-thresholds] + +Activation and recovery thresholds are optional settings for Alert-mode rules in the {{alerting-v2-system}}. They control when alerts transition between lifecycle states, reducing noise from short spikes and rapid flapping between active and recovered. + +## Activation thresholds + +Activation thresholds control when a breached rule transitions from pending to active. Three delay modes are available: + +| Mode | Behavior | When to use | +| --- | --- | --- | +| Immediate | Opens an alert episode as soon as the threshold is breached on the first evaluation. | Use when any single breach warrants attention and latency matters. | +| Breaches | Opens an alert episode after the threshold is breached a set number of times in a row. | Use when a single breach isn't enough reason to act, for example when brief spikes are normal and you only care if the condition keeps firing. | +| Duration | Opens an alert episode after the threshold has been continuously breached for a set time. | Use when duration of the problem matters more than how many evaluations caught it, for example sustained high CPU rather than a momentary spike. | + +### Activation fields + +Use the following fields to configure the Breaches and Duration modes. Timeframe fields accept duration strings between `5s` and `365d`. Refer to [Duration format](yaml-rule-schema-reference.md#duration-format) for supported units. + +| Field | Type | Description | +| --- | --- | --- | +| `pending_count` | Positive integer | Number of consecutive breach evaluations required before the alert episode opens. | +| `pending_timeframe` | Duration string | How long the condition must remain breached before the alert episode opens. | +| `pending_operator` | `AND` or `OR` | When both `pending_count` and `pending_timeframe` are set, controls whether both must be satisfied (`AND`) or either one is enough (`OR`). | + +You can combine Breaches and Duration. For example, require the threshold to be breached five times in a row _and_ persist for at least two minutes before an alert episode opens. Set `pending_operator` to `AND` to require both, or `OR` if either is enough. + +## Recovery thresholds + +Recovery thresholds control when an active alert episode transitions back to inactive. The same delay modes available for activation apply here: consecutive recoveries required, minimum recovery duration, or both. + +| Field | Type | Description | +| --- | --- | --- | +| `recovering_count` | Positive integer | Number of consecutive non-breaching evaluations required before the alert episode closes. | +| `recovering_timeframe` | Duration string | How long the condition must remain non-breaching before the alert episode closes. | +| `recovering_operator` | `AND` or `OR` | When both `recovering_count` and `recovering_timeframe` are set, controls whether both must be satisfied (`AND`) or either one is enough (`OR`). | + +Timeframe fields accept the same `5s` to `365d` bounds as activation timeframes. Refer to [Duration format](yaml-rule-schema-reference.md#duration-format) for supported units. + +:::{note} +The `recovery_strategy` field controls how recovery is detected, separately from how many recoveries are required. When creating a rule through the UI, `recovery_strategy` defaults to `no_breach`, which recovers the alert episode when its active group no longer appears in the breach batch. + +When creating a rule through Agent Builder, you can omit `recovery_strategy` entirely to suppress recovery events and keep alert episodes active until closed manually. For the full field reference, go to [YAML rule schema reference](yaml-rule-schema-reference.md#recovery-strategy). +::: + +## Examples + +### Ignore brief CPU spikes + +This rule monitors CPU usage and runs every minute. A single high reading is often just a process starting up. Set `pending_count` to `3` so the rule requires 3 consecutive breaches before opening an episode, meaning the condition has been true for at least 3 minutes. This filters out noise without losing real signals. + +### Require sustained breach before escalating + +This rule monitors a payment error rate. Brief spikes happen during deployments and are expected. Set `pending_count` to `5`, `pending_timeframe` to `2m`, and `pending_operator` to `AND`. The rule only fires when the error rate has breached on 5 consecutive evaluations and has been continuously elevated for at least 2 minutes. Either condition alone isn't enough. + +### Prevent flapping on recovery + +This rule monitors database connection pool saturation. After the condition clears, set `recovering_count` to `3` to require 3 consecutive non-breaching evaluations before closing the episode. Without this, a rule that alternates between breaching and recovering on consecutive evaluations generates a constant stream of open and closed notifications. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md new file mode 100644 index 0000000000..4bf9217191 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md @@ -0,0 +1,24 @@ +--- +navigation_title: Create a rule +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Create rules in Kibana's experimental alerting system using the ES|QL editor, AI Agent, rule builder, or directly from a Discover session." +--- + +# Create a rule in the {{alerting-v2-system}} [create-a-rule] + +The {{alerting-v2-system}} in {{kib}} provides several ways to create rules. For descriptions of configurable rule setting, refer to [Configure a rule](configure-a-rule.md). + +| Option | Best for | +| --- | --- | +| [Create an ES\|QL rule](create-esql-rule.md) | Full control over the query. Supports both a step-by-step form and a YAML editor. | +| [Create with AI Agent](create-rule-ai-agent.md) | When you know what you want to detect but aren't sure how to write the ES\|QL. | +| [Use the rule builder](use-rule-builder.md) | Rules that follow a guided, form-based setup. | +| [Create from Discover](create-rule-from-discover.md) | When you already have an ES\|QL query working in Discover and want to convert it into a rule. | + +:::{note} +For query examples ranging from a basic event filter to SLO burn rate and persistent breach detection, refer to [ES|QL query patterns](esql-query-patterns.md). +::: \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md new file mode 100644 index 0000000000..49f78bcce2 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md @@ -0,0 +1,32 @@ +--- +navigation_title: Create an ES|QL rule +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Write ES|QL detection queries for rules in Kibana's experimental alerting system using the rule form or YAML editor, with a live query sandbox for previewing results." +--- + +# Create an {{esql}} rule in the {{alerting-v2-system}} [create-esql-rule] + +The {{esql}} rule path lets you write the detection query directly. There are two ways to define the rule: + +- **Rule form** - Fill in the step-by-step form with a live preview of results. +- **YAML mode** - Switch to YAML and edit the raw rule definition. You can switch between form and YAML at any point; edits are preserved. + +For descriptions of each rule setting, refer to [Configure a rule](configure-a-rule.md). For a list of supported YAML fields, refer to [YAML rule schema reference](yaml-rule-schema-reference.md). + +## Preview query results in the sandbox [rule-builder-query-sandbox] + +The query sandbox lets you run your {{esql}} query against current data and preview the results before applying them to the rule form. Use the time field selector and date picker to control the time range, then select **Search** (or press ⌘↵) to execute. When the results look correct, select **Apply changes** to populate the form. + +Use the sandbox to: + +- **Confirm grouping** - Check that your `BY` clause produces the series you intend, for example, one distinct series per host or per service, not a single undifferentiated result. +- **Catch unexpected output** - Verify that the query returns data in the right shape for the alert condition you plan to set. A query that returns zero rows or an unexpected field name won't behave as expected once the rule runs on a schedule. +- **Refine before committing** - Edit the query and re-run it as many times as needed without leaving the rule creation form. + +## Using the YAML editor [yaml-editor] + +Use the YAML editor when you want to copy or adapt a rule quickly without re-entering settings by hand, or provision many rules at once. The YAML editor isn't available within the Threshold Alert builder. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md new file mode 100644 index 0000000000..cc0b010742 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md @@ -0,0 +1,34 @@ +--- +navigation_title: Create with AI Agent +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Use the Elastic AI Agent to generate ES|QL rules from plain-language descriptions in Kibana's experimental alerting system." +--- + +# Create a rule with AI Agent in the {{alerting-v2-system}} [create-rule-ai-agent] + +The AI Agent option opens the Elastic AI agent pre-loaded with rule management knowledge. Describe what you want to monitor in plain language and the agent resolves the relevant data source and builds a rule proposal. + +The proposal appears as an inline attachment card in the conversation showing the rule name, type, schedule, and tags. Select the card to open a flyout with three tabs: + +- **Conditions** - The full rule configuration, including query, thresholds, grouping, and schedule. +- **Query preview** - Runs the {{esql}} query and shows results inline so you can verify the detection logic without leaving the conversation. +- **Runbook** - A free-text runbook associated with the rule. + +The agent doesn't save the rule automatically. When the proposal looks correct, select **Save as rule** from the flyout header to persist it. After saving, you can ask the agent to configure notifications, which creates an action policy scoped to that rule. + +:::{note} +Signal-mode rules don't support notifications. If you ask the agent to set up notifications on a signal rule, the agent will explain the limitation and offer to convert the rule to Alert mode or create a new Alert-mode rule. +::: + +## Example prompts [ai-agent-sample-prompts] + +Use these prompts as a starting point, then adjust them to your data and thresholds: + +- Create an error threshold rule on my checkout service data. Alert when there are more than 3 HTTP 5xx errors in the past 5 minutes, grouped by URL path. +- Monitor average CPU usage across all hosts. Alert when any host exceeds 90% for more than 10 minutes. +- Alert me when log volume from the payments service drops below 100 events in a 5-minute window. This likely means data has stopped flowing. +- Set up a rule that tracks error rate by service. Alert at medium severity when the rate exceeds 1%, and critical when it exceeds 5%. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md index 25a6aae0e1..131b0e9e53 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md @@ -1,49 +1,31 @@ --- -navigation_title: Using Discover +navigation_title: Create from Discover applies_to: stack: experimental 9.5+ serverless: experimental products: - id: kibana -description: "Turn an ES|QL query in Discover into a rule in the experimental alerting system with pre-filled evaluation and lookback." +description: "Convert an ES|QL query from a Discover session into a rule in Kibana's experimental alerting system, with the query pre-filled and a preview panel for verifying grouping." --- -# Create rules from Discover in the {{alerting-v2-system}} [create-rules-discover] +# Create a rule from Discover in the {{alerting-v2-system}} [create-from-discover] - -Discover-based rule creation is part of the {{alerting-v2-system}} in {{kib}}. When you build an {{esql}} query that surfaces interesting patterns, you can convert it into a rule without rewriting the query. For the full rule form including schedule and lifecycle settings, refer to [Configure a rule](configure-a-rule.md). +When you build an {{esql}} query in Discover that surfaces interesting patterns, you can convert it into a rule without rewriting the query. Starting from Discover means your query is already tested and returns the shape you expect before the rule is ever saved. ## Entry points [discover-rule-entry-points] Two paths lead to Discover-based rule creation: - **Discover Alerts menu**: When you're in Discover with an active {{esql}} query and the {{alerting-v2-system}} is enabled, the Alerts menu includes a **Create ES|QL rule** option. The rule creation flyout opens pre-populated with the current query. This path is only available in ES|QL mode. -- **Rules list**: From the rules list, selecting the option to create a rule from Discover opens the Discover-based rule creation experience directly. The flyout embeds a live Discover session so you can compose and test the query before saving the rule. After saving, you return to the rules list. +- **Rules list**: Selecting the option to create a rule from Discover opens a flyout that embeds a live Discover session so you can compose and test the query before saving the rule. ## How it works [discover-rule-flow] -Starting a rule from Discover means your query is already tested and returns the shape you expect before the rule is ever saved. Instead of drafting a query in the rule builder and hoping it works, you iterate in Discover (where you can see real results immediately) and then create the rule when the query is ready. - -When you trigger rule creation from Discover, your {{esql}} query pre-fills the **Create ES|QL rule** form. The rule creation form also shows a preview panel that reflects how your query partitions results into alert series. If your query uses a `BY` clause, the preview shows the series that would be evaluated on each run. This lets you verify grouping logic against live data before committing to a schedule. - -## Form and YAML editing [discover-form-yaml] - -The rule creation flyout supports both a step-by-step form and a YAML editing mode. You can switch between them at any point — edits in YAML mode are preserved when you return to the form view. To discard YAML edits and return to the prior form state, use the **Cancel YAML** option. The YAML editor includes {{esql}} autocomplete in the query field. - -Use YAML mode when you want to fine-tune the raw rule definition, copy a pattern from an existing rule, or work faster than filling in individual form fields allows. - -## Preview query results before creating the rule [preview-query-discover] - - -The query preview in the rule creation flow runs your {{esql}} query against current data and displays the resulting rows. Use this to: - -- **Confirm grouping**: Check that your `BY` clause produces the series you intend — for example, one distinct series per host or per service, not a single undifferentiated result. -- **Catch unexpected output**: Verify that the query returns data in the right shape for the alert condition you plan to set. A query that returns zero rows or an unexpected field name won't behave as expected once the rule runs on a schedule. -- **Refine before committing**: Edit the query in the preview panel and re-run it without leaving the rule creation form. Once the preview looks correct, proceed to fill in the remaining settings. +When you trigger rule creation from Discover, your {{esql}} query pre-fills the **Create ES|QL rule** form. The rule creation form also shows a preview panel that reflects how your query partitions results into alert series. If your query uses a `BY` clause, the preview shows the series that would be evaluated on each run, letting you verify grouping logic against live data before committing to a schedule. - \ No newline at end of file + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md deleted file mode 100644 index 3822417ea8..0000000000 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -navigation_title: Using the rule builder -applies_to: - stack: experimental 9.5+ - serverless: experimental -products: - - id: kibana -description: "Create ES|QL rules, AI-assisted rules, and Threshold Alert rules in Kibana's experimental alerting system using the rule builder flyout." ---- - -# Create rules in the {{alerting-v2-system}} [create-rules-rule-builder] - -The rule builder is part of the {{alerting-v2-system}} in {{kib}}. For a full description of what each setting does, refer to [Configure a rule](configure-a-rule.md). - -## Creation paths [rule-creation-paths] - -All rules are created through a flyout that opens from the **Create rule** button in the rules list. Three options are available: - -- **Create ES|QL rule**: Write the detection query as {{esql}} directly, with a live preview of results. A YAML editor is also available within this path. Use this when you want full control over the query. If you already have a query working in Discover, you can [start from there instead](create-rule-from-discover.md) to skip re-entering it. -- **Create with AI Agent**: Describe what you want to detect in plain language. The AI agent generates a rule definition and walks you through reviewing and saving it. Use this when you know the problem but aren't sure how to write the {{esql}}. -- **Start from a rule builder**: Choose a structured rule type and fill in a guided form. The builder generates the {{esql}} query automatically. Use this when you want to create a standard rule type without writing {{esql}} by hand. Refer to [Threshold Alert](#threshold-alert) for the available type. - -## Threshold Alert - -Threshold Alert is the rule type available under **Start from a rule builder**. Use it to monitor one or more metrics and alert when they cross a threshold, with multi-condition support and custom aggregations. - -You define the rule by filling in structured fields for the data source, aggregation, filters, and alert conditions. The builder generates the {{esql}} query automatically from those inputs. Rules created through the builder can be reopened and edited in builder mode as long as the underlying {{esql}} hasn't been edited directly. - -Use the **Create ES|QL rule** path when the detection logic requires more than a single metric threshold, such as multi-window burn rates or cross-series correlation. - -### Recovery conditions [threshold-builder-recovery] - -When you define alert conditions in the Threshold Alert builder, the builder automatically derives corresponding recovery conditions by flipping the comparators. For example, a `greater than` alert condition produces a `less than or equal to` recovery condition. You can customize the derived conditions or leave the defaults as generated. Recovery conditions are preserved correctly when you reopen an existing rule in builder mode for editing. - -## ES|QL rule: form and YAML editing [rule-builder-form-yaml] - -The **Create ES|QL rule** path supports both a step-by-step form and a YAML editing mode. You can switch between them at any point. Edits in YAML mode are preserved when you return to the form view. To discard YAML edits and return to the prior form state, use the **Cancel YAML** option. - -Use YAML mode when you want to fine-tune the raw rule definition, copy a configuration from an existing rule, or work faster than filling in individual form fields allows. The YAML editor isn't available within the Threshold Alert builder or other rule builder types. - -For a list of supported YAML fields, refer to [YAML rule schema reference](yaml-rule-schema-reference.md). - - diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md deleted file mode 100644 index 89834259e3..0000000000 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -navigation_title: Using the YAML editor -applies_to: - stack: experimental 9.5+ - serverless: experimental -products: - - id: kibana -description: "Define rules as YAML in Kibana's experimental alerting system for version control, infrastructure-as-code, and bulk provisioning of detection logic." ---- - -# Create rules using the YAML editor in {{alerting-v2-system}} [create-rules-yaml] - - -The YAML editor is part of the {{alerting-v2-system}} in {{kib}}. It lets you define rules as text documents rather than filling in a form. Use it when you want to version-control rule definitions alongside your other configuration, manage rules through infrastructure-as-code tooling, copy or adapt a rule quickly without re-entering settings by hand, or provision many rules at once. - -If you're creating a rule from scratch and want guidance through each setting, the [rule builder](create-rule-from-rule-builder.md) is the better starting point. If you have a query already working in Discover, you can [create a rule directly from there](create-rule-from-discover.md). - -For the full list of supported YAML fields and their accepted values, refer to [YAML rule schema reference](yaml-rule-schema-reference.md). - - diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md new file mode 100644 index 0000000000..0d7f3fa700 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md @@ -0,0 +1,47 @@ +--- +navigation_title: Your first rule query +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Write your first ES|QL rule query in Kibana's experimental alerting system. Covers the minimum query structure and how to adapt it to your data." +--- + +# Your first rule query in the {{alerting-v2-system}} [esql-first-rule-query] + +If you're new to {{esql}} or to writing rules, this page shows the simplest query structure that a rule needs. It requires only a basic familiarity with your data. + +## The simplest rule query + +This query returns one row for every log entry at `ERROR` level in the lookback window. No aggregation happens; each matching event becomes its own alert event. Use this pattern when any single occurrence of a condition is worth alerting on: any critical error log, any failed authentication attempt, any payment rejection. + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend // Scope to the rule's configured lookback window +| WHERE level == "ERROR" // The alert condition: every match is a breach +| KEEP service.name, message, @timestamp // Fields stored on each alert event +``` + +Every row the query returns is treated as a breach. If the query returns nothing, no alert fires. + +### What each part does + +| Part | Purpose in a rule | +| --- | --- | +| `FROM logs-*` | The index or data stream to query. | +| `WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend` | Scopes the query to the rule's lookback window. `?_tstart` and `?_tend` are bound automatically at runtime. Always include this filter to avoid scanning your entire index on every evaluation. | +| `WHERE level == "ERROR"` | The alert condition. Only rows that pass this filter generate an alert event. | +| `KEEP service.name, message, @timestamp` | The fields stored on each alert event. Only fields in `KEEP` are available for routing, grouping, and triage. | + +### How to adapt this query + +To use this query with your own data, change three things: + +1. **Index**: Replace `logs-*` with the index or data stream that holds your data. +2. **Alert condition**: Replace `level == "ERROR"` with the field name and value that defines a breach in your data. For example: `event.outcome == "failure"`, `http.response.status_code >= 500`, or `process.name == "malware.exe"`. +3. **KEEP fields**: Replace the field list with whatever you need for triage. Include any fields you plan to use for grouping, routing, or displaying in the alert detail view. + +## Next steps + +This pattern alerts on individual events. If you want to alert only when a count or rate crosses a threshold rather than on individual occurrences, the [threshold query pattern](esql-threshold-queries.md) is the next step. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md new file mode 100644 index 0000000000..7ff031fae9 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md @@ -0,0 +1,32 @@ +--- +navigation_title: No-data detection +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Detect silent hosts and stopped data sources in Kibana's experimental alerting system using ES|QL last-seen queries." +--- + +# No-data detection in the {{alerting-v2-system}} [no-data-esql-query] + +No-data detection solves a different problem from threshold alerting. A threshold query evaluates data that's present. No-data detection identifies sources that have gone silent. Threshold queries can't do this. A silent host produces no rows at all, so there's nothing to evaluate a condition against. + +The pattern inverts the normal approach: use a broad lookback to find all known hosts, then surface only those that have not reported recently. + +```esql +FROM metrics-* +| WHERE @timestamp >= NOW() - 12 hours // Cover the longest expected reporting gap for your hosts. + // Too short: silent hosts fall outside the window and are never checked. + // Too long: increases query cost on high-frequency data streams. +| STATS last_seen = MAX(@timestamp) BY host.name // Find the most recent event timestamp per host +| WHERE last_seen < NOW() - 15 minutes // Silence threshold: set slightly above your expected maximum reporting interval + // to avoid false positives from brief gaps +| KEEP host.name, last_seen // Each returned row is a silent host +``` + +Every row returned is a host that has gone silent. The query result itself drives the alert; no separate alert condition is needed. + +:::{note} +This pattern detects specific silent sources. For controlling what the rule records when the entire base query returns zero rows, for example when an index is completely empty, refer to [No-data handling](configure-no-data-handling.md). +::: diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md new file mode 100644 index 0000000000..d6471397ed --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md @@ -0,0 +1,45 @@ +--- +navigation_title: Persistent breach detection +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Detect conditions that persist across consecutive time buckets in Kibana's experimental alerting system using ES|QL bucket counting." +--- + +# Persistent breach detection in the {{alerting-v2-system}} [persistent-breach] + +A persistent breach condition detects a metric that stays above a threshold across several consecutive time buckets, for example CPU above 90% in all 10 of the last 10 five-minute windows. This filters out transient spikes and fires only when a problem has been sustained. + +{{esql}} can express this with bucket counting: + +```esql +FROM metrics-* +| WHERE @timestamp >= NOW() - 50 minutes // Lookback must cover all 10 buckets (10 × 5 min = 50 min) +| EVAL bucket = BUCKET(@timestamp, 5 minutes) // Assign each event to its 5-minute time bucket +| STATS + total_buckets = COUNT_DISTINCT(bucket), // How many distinct buckets exist in the window + exceeding_buckets = COUNT_DISTINCT( + CASE(system.cpu.total.pct > 0.90, bucket, null) // Count only buckets where CPU exceeded threshold; + ) // null values are excluded by COUNT_DISTINCT + BY host.name +| WHERE total_buckets >= 10 // Require a full window of data before firing; + AND exceeding_buckets == total_buckets // every bucket must have breached +| KEEP host.name, total_buckets, exceeding_buckets +``` + +The rule's lookback window must cover all the buckets you want to check. In this example, 10 five-minute buckets requires at least 50 minutes of lookback. + +## Handling gaps in data + +If any bucket is missing because the host stopped reporting briefly mid-window, `total_buckets` drops below 10 and the condition doesn't fire. This is a deliberate safety check: a host that went silent for one bucket is treated as "we don't have enough data to confirm persistence" rather than "breach." + +If you want to allow some gaps, replace `exceeding_buckets == total_buckets` with a ratio or a minimum count: + +```esql +| WHERE total_buckets >= 8 // Tolerate up to 2 missing buckets + AND exceeding_buckets >= total_buckets * 0.9 // 90% of present buckets must have breached +``` + +Design the query so that gaps in reporting produce the behavior you want before deploying it. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md index 2cddc60b1d..604ff57bd9 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md @@ -5,151 +5,17 @@ applies_to: serverless: experimental products: - id: kibana -description: "Advanced ES|QL query patterns for rules in the experimental alerting system: SLO burn rate, no-data detection, persistent breach, and unsupported operations." +description: "ES|QL query patterns for rules in Kibana's experimental alerting system, from basic event filters to SLO burn rates, silent source detection, and persistent breach checks." --- # {{esql}} query patterns for rules in the {{alerting-v2-system}} [esql-query-patterns] +The following pages cover {{esql}} query patterns for rules in the {{alerting-v2-system}}, ordered from the simplest starting point to advanced use cases. Start with [Your first rule query](esql-first-rule-query.md) if you're new, or jump to the pattern you need. -ES|QL query patterns for rules are part of the {{alerting-v2-system}} in {{kib}}. Some detection problems can't be expressed as a single metric compared to a fixed threshold. You might need to know whether an SLO is burning through its error budget across multiple time windows at once. Or whether a specific host has gone silent, rather than whether the query returned nothing. Or whether a condition has persisted continuously across consecutive time buckets rather than appearing once. These are structurally different problems that require different query shapes. - -Use this page when a basic `STATS ... WHERE` pattern isn't enough, or when the detection logic itself requires multi-window calculation, last-seen reasoning, or bucket-level persistence checks. If you're still learning how rules in the {{alerting-v2-system}} work, start with [Author rules](author-rules.md) first. - -## Basic threshold query [threshold-query] - -A threshold query evaluates one metric over one lookback window and fires if a value crosses a limit. It is the simplest rule shape: a `STATS` aggregation followed by a `WHERE` condition. - -```esql -FROM logs-* -| STATS - // Count only error responses; count all requests for the denominator - error_count = COUNT_IF(http.response.status_code >= 500), - total_count = COUNT(*) - BY service.name -| EVAL error_rate = error_count / total_count // Compute the error rate as a fraction (0–1) -| WHERE error_rate > 0.10 // Alert condition: services above 10% error rate are breaches -| KEEP service.name, error_rate, error_count, total_count -``` - -One window, one aggregate, one threshold check. The result is either a breach or no breach for each series. - -## SLO burn rate query [slo-burn-rate-query] - -An SLO burn rate query asks a different question than a basic threshold: are you consuming your error budget faster than you can afford to? Rather than checking a single metric at a fixed limit, it calculates error rates across multiple time windows simultaneously and returns a severity level. - -### Why multiple windows - -Checking both a short window (for example, 5 minutes) and a long window (for example, 1 hour) together filters out brief spikes that don't represent a real budget threat. A `critical`-severity alert episode fires only when *both* the short and long burn rates exceed the threshold. The two-window requirement is what separates a genuine budget emergency from a momentary blip. - -### Query structure - -A single {{esql}} query handles all window pairs at once using conditional aggregation: - -```esql -FROM metrics-* -| WHERE @timestamp >= NOW() - 3 days // Lookback must cover the longest window pair used below. - // Keep this value in sync with the rule's lookback setting. -| STATS - // CRITICAL window pair: 5 min catches the fast signal, 1 hour confirms it's sustained - errors_5m = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 5 minutes), - total_5m = COUNT_IF(@timestamp >= NOW() - 5 minutes), - errors_1h = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 1 hour), - total_1h = COUNT_IF(@timestamp >= NOW() - 1 hour), - // HIGH window pair: 30 min fast signal, 6 hours sustained confirmation - errors_30m = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 30 minutes), - total_30m = COUNT_IF(@timestamp >= NOW() - 30 minutes), - errors_6h = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 6 hours), - total_6h = COUNT_IF(@timestamp >= NOW() - 6 hours) - BY slo.id // Each SLO is evaluated independently -| EVAL - // Compute error rates (errors as a fraction of total requests) for each window - burn_5m = errors_5m / total_5m, - burn_1h = errors_1h / total_1h, - burn_30m = errors_30m / total_30m, - burn_6h = errors_6h / total_6h -| EVAL severity = CASE( - // critical: both the fast and sustained windows exceed 14.4x the baseline error rate. - // Requiring both prevents a single brief spike from triggering a critical alert. - burn_5m > 14.4 AND burn_1h > 14.4, "critical", - // high: same two-window logic at a lower threshold - burn_30m > 6.0 AND burn_6h > 6.0, "high", - "none" - ) -| WHERE severity != "none" // Only breaching SLOs become alert rows -| KEEP slo.id, severity, burn_5m, burn_1h, burn_30m, burn_6h // Store fields needed for routing and triage -``` - -The burn rate multipliers (14.4×, 6×) reflect standard SLO error budget consumption rates. Adjust them to match your SLO targets. - -Because the query computes several window pairs in one pass, the lookback window on the rule must cover the longest window in the query (3 days in the example above). - -The `severity` column in `KEEP` maps directly to `episode.severity` on each resulting alert episode. For the accepted values and matching rules, see [Severity levels](author-rules.md#severity-levels). - -## No-data detection [no-data-esql-query] - -No-data detection inverts the normal pattern. Instead of filtering for data that meets a condition, you query for when data was *last seen* and flag sources that have gone silent. - -The technique uses a broad lookback to find all known hosts, then surfaces only those that have not reported recently: - -```esql -FROM metrics-* -| WHERE @timestamp >= NOW() - 12 hours // Broad lookback: must be wide enough that all known hosts - // have at least one event in the window under normal conditions -| STATS last_seen = MAX(@timestamp) BY host.name // Find the most recent event timestamp per host -| WHERE last_seen < NOW() - 15 minutes // Keep only hosts that have NOT reported in the last 15 minutes -| KEEP host.name, last_seen // Each returned row is a silent host — the query result itself is the alert -``` - -Every row returned is a host that has gone silent, so the base query itself drives the alert. No separate alert condition is needed. - -### Variants - -| Variant | What it detects | -|---|---| -| Host-specific | Each host that stops reporting generates its own alert series (use `BY host.name` for grouping). | -| Global | No data from any source. Omit the `BY` clause and check whether the query returns any rows at all. | -| Combined | Flags both a high-metric condition *and* silent hosts in one query using a `CASE` expression to assign a `status` field (`"alert"`, `"no data"`, or `"ok"`), then filters to only the problematic rows. | - -### Lookback window sizing - -The lookback must be wide enough that known hosts appear in the result set. If the lookback is too short, a silent host falls outside the window and is never checked. However, large lookback windows on high-frequency data streams increase query cost significantly. Start with a lookback that comfortably covers the longest expected reporting gap for your hosts, not the full history of the index. - -For no-data behavior when the entire base query returns zero rows (as opposed to detecting specific silent sources), refer to [No-data handling](configure-a-rule.md#no-data-handling). - - - -## Limitations and workarounds [esql-limitations] - -Some patterns from the classic alerting aggregation API are not directly available in {{esql}}, and some require workarounds. - -### Persistent breach detection [persistent-breach] - -A persistent breach condition detects a metric that stays above a threshold across several consecutive time buckets (for example, "CPU above 90% in all 10 of the last 10 five-minute windows"). {{esql}} can express this with bucket counting: - -```esql -FROM metrics-* -| WHERE @timestamp >= NOW() - 50 minutes // Lookback must cover all 10 buckets (10 × 5 min = 50 min) -| EVAL bucket = BUCKET(@timestamp, 5 minutes) // Assign each event to its 5-minute time bucket -| STATS - total_buckets = COUNT_DISTINCT(bucket), // How many distinct buckets exist in the window - exceeding_buckets = COUNT_DISTINCT( - CASE(system.cpu.total.pct > 0.90, bucket, null) // Count only buckets where CPU exceeded the threshold; - ) // null values are excluded by COUNT_DISTINCT - BY host.name -| WHERE total_buckets >= 10 // Require a full window of data before firing — - AND exceeding_buckets == total_buckets // guards against gaps making a partial breach look persistent; - // every bucket in the window must have breached -| KEEP host.name, total_buckets, exceeding_buckets -``` - -The rule's lookback window must cover all the buckets you want to check (50 minutes for 10 five-minute buckets in this example). If any bucket is missing from the data because the host stopped reporting briefly mid-window, `total_buckets` drops below 10 and the condition doesn't fire. Design the query so that gaps in reporting produce the behavior you want: either treating partial coverage as a non-breach or adjusting the `WHERE` filter to allow it. - - - -### Derivative aggregation [derivative-aggregation] - -{{esql}} does not have a `DERIVATIVE` function. In the {{es}} aggregations API, a derivative pipeline aggregation calculates the rate of change between consecutive time buckets (for example, "how fast is this counter increasing per minute?"). There is no equivalent in {{esql}}. - -Use cases that require true per-bucket deltas (such as detecting a sudden acceleration in error rate) cannot be expressed as an {{esql}} rule at this time. Consider pre-computing deltas in an ingest pipeline or using a transform to write derived metrics to a separate index that your rule can then query with a standard threshold pattern. +| Pattern | What it solves | Complexity | +| --- | --- | --- | +| [Your first rule query](esql-first-rule-query.md) | Alert on any individual event that matches a condition. No aggregation needed. | Beginner | +| [Threshold queries](esql-threshold-queries.md) | Alert when a metric crosses a limit. Covers single-series and grouped (per-host, per-service) rules. | Beginner | +| [No-data detection](esql-no-data-detection.md) | Alert when a specific host or data source stops reporting. | Intermediate | +| [SLO burn rate](esql-slo-burn-rate.md) | Alert when error budget consumption exceeds safe rates across multiple time windows. | Advanced | +| [Persistent breach detection](esql-persistent-breach.md) | Alert when a condition has been continuously true across consecutive time buckets. | Advanced | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md new file mode 100644 index 0000000000..98a53f0e47 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md @@ -0,0 +1,75 @@ +--- +navigation_title: SLO burn rate +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Detect SLO error budget burn across multiple time windows in Kibana's experimental alerting system using ES|QL conditional aggregation." +--- + +# SLO burn rate detection in the {{alerting-v2-system}} [slo-burn-rate-query] + +An SLO burn rate query asks a different question than a basic threshold: are you consuming your error budget faster than you can afford to? Rather than checking a single metric at a fixed limit, it calculates error rates across multiple time windows simultaneously and assigns a severity level based on how fast the budget is being consumed. + +## Single-tier query + +This version checks one window pair and fires only at `critical` severity. It shows the core two-window pattern with the minimum number of moving parts. + +```esql +FROM metrics-* +| WHERE @timestamp >= NOW() - 1 hour // Cover the longest window in the pair +| STATS + errors_5m = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 5 minutes), + total_5m = COUNT_IF(@timestamp >= NOW() - 5 minutes), + errors_1h = COUNT_IF(outcome == "failure"), + total_1h = COUNT(*) + BY slo.id // Each SLO is evaluated independently +| EVAL + burn_5m = errors_5m / total_5m, + burn_1h = errors_1h / total_1h +| WHERE burn_5m > 14.4 AND burn_1h > 14.4 // Both windows must exceed the threshold to fire; + // the short window detects the spike, the long window confirms it's sustained +| EVAL severity = "critical" +| KEEP slo.id, severity, burn_5m, burn_1h +``` + +The 14.4× multiplier reflects the rate at which a service would exhaust a 99.9% monthly error budget in one hour. Adjust it to match your SLO target. + +## Multi-tier query + +This version extends the single-tier pattern to detect both `critical` and `high` severity in one pass. Each severity level uses its own window pair with different time scales and thresholds. + +```esql +FROM metrics-* +| WHERE @timestamp >= NOW() - 3 days // Cover the longest window pair used below. + // Keep this in sync with the rule's lookback setting. +| STATS + // CRITICAL window pair: 5 min fast signal, 1 hour sustained confirmation + errors_5m = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 5 minutes), + total_5m = COUNT_IF(@timestamp >= NOW() - 5 minutes), + errors_1h = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 1 hour), + total_1h = COUNT_IF(@timestamp >= NOW() - 1 hour), + // HIGH window pair: 30 min fast signal, 6 hours sustained confirmation + errors_30m = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 30 minutes), + total_30m = COUNT_IF(@timestamp >= NOW() - 30 minutes), + errors_6h = COUNT_IF(outcome == "failure" AND @timestamp >= NOW() - 6 hours), + total_6h = COUNT_IF(@timestamp >= NOW() - 6 hours) + BY slo.id +| EVAL + burn_5m = errors_5m / total_5m, + burn_1h = errors_1h / total_1h, + burn_30m = errors_30m / total_30m, + burn_6h = errors_6h / total_6h +| EVAL severity = CASE( + burn_5m > 14.4 AND burn_1h > 14.4, "critical", + burn_30m > 6.0 AND burn_6h > 6.0, "high", + "none" + ) +| WHERE severity != "none" +| KEEP slo.id, severity, burn_5m, burn_1h, burn_30m, burn_6h +``` + +The rule's lookback window must cover the longest window in the query. In this example that's 3 days, driven by the 6-hour window pair. + +The `severity` column in `KEEP` maps directly to the `severity` field on each resulting alert episode. For accepted values and matching rules, refer to [Severity](configure-rule-severity.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md new file mode 100644 index 0000000000..9ef349ed7c --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md @@ -0,0 +1,59 @@ +--- +navigation_title: Threshold queries +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Write ES|QL threshold queries for rules in Kibana's experimental alerting system. Covers single-series and grouped rules using STATS aggregation." +--- + +# Threshold queries in the {{alerting-v2-system}} [esql-threshold-queries] + +A threshold query aggregates your data first, then applies an alert condition to the result. Use this pattern when a single matching event isn't enough to warrant an alert. You want to know whether a metric (count, rate, average) has crossed a limit over a time window. + +This page covers two variants: a single-series threshold that produces one result for all your data, and a grouped threshold that tracks each subject (host, service, user) independently. + +## Single-series threshold + +This query counts HTTP 5xx responses and error rates over the lookback window and alerts when the error rate for any service exceeds 10%. + +```esql +FROM logs-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend // Scope to the rule's configured lookback window +| STATS + error_count = COUNT_IF(http.response.status_code >= 500), // Count only error responses + total_count = COUNT(*) // Count all requests for the denominator + BY service.name +| EVAL error_rate = error_count / total_count // Compute error rate as a fraction (0–1) +| WHERE error_rate > 0.10 // Alert condition: services above 10% error rate are breaches +| KEEP service.name, error_rate, error_count, total_count +``` + +One window, one aggregate per service, one threshold check. The result is either a breach or no breach for each service. + +## Grouped threshold + +Adding `BY` to the `STATS` command splits the result into one row per unique field value. Each row is evaluated independently against the alert condition, and each breach creates its own alert series. + +This query tracks average CPU usage per host and alerts when any host exceeds 90%: + +```esql +FROM metrics-* +| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend +| STATS avg_cpu = AVG(system.cpu.total.pct) BY host.name // One result row per host +| WHERE avg_cpu > 0.90 // Each host above the threshold is a breach +| KEEP host.name, avg_cpu +``` + +Without the `BY host.name` clause, the query would produce a single average across all hosts combined. A cluster-wide spike might push the average above the threshold even if no single host is the problem. Grouping by host gives each host its own alert episode with its own lifecycle. If host A recovers but host B stays critical, those are tracked separately. + +The `BY` fields you use here must match the grouping configuration in the rule. Refer to [Rule grouping](configure-rule-grouping.md) for how to align them. + +## Next steps + +If both of these patterns are too simple for your use case, the next pages cover more specific detection problems: + +- [No-data detection](esql-no-data-detection.md): when a host or source stops reporting entirely +- [SLO burn rate](esql-slo-burn-rate.md): when you need to check error budget consumption across multiple time windows +- [Persistent breach detection](esql-persistent-breach.md): when you only want to alert if a condition has been continuously true diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md index dc275b3e35..e955317ed5 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md @@ -5,12 +5,12 @@ applies_to: serverless: experimental products: - id: kibana -description: "Field reference for rule configuration and .rule-events documents in Kibana's experimental alerting system. Covers schedule, activation thresholds, and rule event output fields." +description: "Field reference for .rule-events documents in Kibana's experimental alerting system. Covers signal and alert base fields, episode fields, and the append-only data stream behavior." --- # Rule event and field reference in the {{alerting-v2-system}} [rule-reference] -Rule event fields are part of the {{alerting-v2-system}} in {{kib}}. This page lists technical fields for rule configuration and rule event documents written to `.rule-events`. +This page is a field reference for `.rule-events` documents written by the {{alerting-v2-system}}. For rule configuration settings, refer to [Configure a rule](configure-a-rule.md). @@ -19,56 +19,6 @@ For alert actions in `.alert-actions`, refer to [Alert states and fields referen The `.rule-events` and `.alert-actions` data streams are [system indices](/reference/glossary/index.md#glossary-system-index). {{kib}} manages their versioning, retention, and lifecycle through ILM. Older backing indices are deleted automatically when the retention window expires. Do not change mappings or index settings for these streams yourself. ::: -## Schedule and lookback - -These fields control when a rule runs and how far back its {{esql}} query looks on each evaluation. - -| Field | Description | -|---|---| -| `schedule.every` | Execution interval; minimum 5 seconds, maximum 365 days. | -| `schedule.lookback` | Time range the {{esql}} query covers; must not exceed 365 days; should be at least `schedule.every` to avoid gaps. | - -## Activation thresholds - -These fields are only available in Alert mode. They control how many consecutive breaches, or how long a condition must persist, before an episode transitions from `pending` to `active`. - -| Field | Description | -|---|---| -| `pending_count` | Consecutive breaches required. | -| `pending_timeframe` | Minimum duration the condition must persist. | -| `pending_operator` | How to combine count and timeframe (`AND` or `OR`). | - -## Recovery thresholds - -These fields are only available in Alert mode. They control how many consecutive recoveries, or how long the condition must be clear, before an episode transitions from `recovering` to `inactive`. - -| Field | Description | -|---|---| -| `recovering_count` | Consecutive recoveries required. | -| `recovering_timeframe` | Minimum duration for recovery. | -| `recovering_operator` | How to combine count and timeframe (`AND` or `OR`). | - -## No-data handling - -These settings determine what the rule records when the {{esql}} query returns no rows on an evaluation. - -| Behavior | Effect | -|---|---| -| `no_data` (default) | Record a no-data event. | -| `last_status` | Carry forward the previous status. | -| `recover` | Treat absence as recovery. | - -## Rule grouping - -Grouping is configured in YAML. The fields listed here control how the rule partitions results into independent series, each with its own lifecycle. - -| Key | Description | -|---|---| -| `grouping.fields` | Array of field names; must align with `STATS ... BY` in the {{esql}} query. | - - - ## Rule event documents Each time a rule evaluates, {{kib}} writes one document per matched series to `.rule-events`. The `type` field determines the document kind: @@ -79,7 +29,7 @@ Each time a rule evaluates, {{kib}} writes one document per matched series to `. Both kinds share the base fields below. Only `alert` documents add the [Episode fields](#episode-fields) listed further down. :::{note} -`.rule-events` is a data stream, so it is append-only. A new document is written on every rule evaluation — existing documents are never updated. Each document is a snapshot of that moment: the `episode.status` field records the lifecycle stage the episode was in at that evaluation. To view the full history of an episode, query all documents that share the same `episode.id`. +`.rule-events` is a data stream, so it is append-only. A new document is written on every rule evaluation; existing documents are never updated. Each document is a snapshot of that moment: the `episode.status` field records the lifecycle stage the episode was in at that evaluation. To view the full history of an episode, query all documents that share the same `episode.id`. @@ -101,9 +51,6 @@ These fields appear on all `.rule-events` documents, regardless of whether the r | `source` | keyword | Yes | Origin of this event. Product-specific identifier. | | `type` | keyword | Yes | `signal` or `alert`. Application field on each rule event document written by {{kib}}. | - - :::{admonition} Fields not stored as a dedicated column There's no top-level or nested `duration` field on `.rule-events` documents. For triage or reporting, derive duration from the alert UI or your own queries over timestamps and episode identifiers. ::: -### Episode fields +### Episode fields [episode-fields] -These fields only appear on documents with `type: alert`, written by rules running in Alert mode. They carry the lifecycle state for the episode associated with the matched series. +These fields are stored in `.rule-events`, on the same document as the base fields, when the rule runs in Alert mode. They only appear on documents with `type: alert` and carry the lifecycle state for the episode associated with the matched series. | Field | Type | Description | |---|---|---| | `episode.id` | keyword | Episode identifier for this series. | | `episode.status` | keyword | One of: `inactive`, `pending`, `active`, `recovering`. | | `episode.status_count` | long | Count of consecutive evaluations in the current `episode.status`. Only set when `episode.status` is `pending` or `recovering`. | -| `episode.severity` | keyword | Severity level from the most recent breached event. One of: `info`, `low`, `medium`, `high`, `critical`. Not set when the query output does not include a `severity` column, or when the value does not match a recognized level. Never set on `recovered` or `no_data` events. | -| `episode.severity_max` | keyword | Highest severity level observed across the episode's lifetime (high-water mark). Enables routing or display based on peak severity, for example, "this episode peaked at `critical`". | +| `severity` | keyword | Severity level from the most recent breached event. One of: `info`, `low`, `medium`, `high`, `critical`. Not set when the query output does not include a `severity` column, or when the value does not match a recognized level. Never set on `recovered` or `no_data` events. | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md new file mode 100644 index 0000000000..216c6c4898 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md @@ -0,0 +1,17 @@ +--- +navigation_title: Use the rule builder +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Create Threshold Alert rules in Kibana's experimental alerting system using a guided form that generates ES|QL automatically." +--- + +# Use the rule builder in the {{alerting-v2-system}} [use-rule-builder] + +The rule builder provides a guided form for creating rules without writing {{esql}} by hand. The builder generates the {{esql}} query automatically from structured inputs for the data source, aggregation, filters, and alert conditions. + +## Threshold Alert [use-threshold-alert-builder] + +Threshold Alert is the only rule type available in the rule builder. Use it to monitor one or more metrics and alert when they cross a threshold, with multi-condition support and custom aggregations. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md index 1803f0bd96..fda179e400 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md @@ -10,38 +10,37 @@ description: "Search, filter, sort, and bulk-manage rules from the rules list in # View and manage rules in the {{alerting-v2-system}} [manage-rules] -Rule management is part of the {{alerting-v2-system}} in {{kib}}. After a rule is created, edit its settings, pause it, remove it, and more from the page listing rules. The rules list gives you search, filter, sort, and bulk actions across all rules in the space. Selecting a rule name opens its details page, where you can review the full configuration and edit or act on it directly. +Rule management is part of the {{alerting-v2-system}} in {{kib}}. This page covers how to find and filter rules in the rules list, quick-edit settings without leaving the list, use the rule summary flyout, and navigate the rule details page including the alert activity timeline. ## Find and filter rules [find-filter-rules] -Use the search bar at the top of the rules list to find rules by name or description. The search field accepts plain text. Each space-separated term is matched independently (terms are AND'd) using prefix matching. Type any part of a rule name or description to narrow the list. +Use the search bar to find rules by name or description. Each space-separated term is matched independently using prefix matching. Tags and grouping fields appear in results but aren't searchable. -Search matches rule name and description only. Tags and grouping fields are displayed in search results but aren't included in free-text search. Special characters in rule names and descriptions, including consecutive hyphens, are handled correctly. +Combine text search with filter controls to narrow by rule type, status, or tags. Select any column header to sort, or use bulk actions to enable, disable, or delete multiple rules at once. -Combine text search with filter controls to narrow results further by rule type, status, or tags. Select any column header to sort the list. Use bulk actions when you need to enable, disable, or delete multiple rules at once. - -## Quick-edit a rule [quick-edit-rule] +## Edit a rule inline [quick-edit-rule] To update common rule settings without opening the full rule details page, use the inline edit option on any row in the rules list. The inline editor also opens from the rule summary flyout header. -Editable fields in this view include name, description, tags, grouping key, time field, interval, lookback window, alert delay, recovery type, and recovery delay. The {{esql}} query and alert tracking behavior are read-only in this view. For changes to the query or rule mode, open the full rule details page. - Use inline edit when you need to adjust metadata or scheduling settings quickly without navigating away from the list. -## Rule summary flyout [rule-summary-flyout] +## Inspect a rule with the summary flyout [rule-summary-flyout] To inspect a rule without navigating away from the rules list, select the expand icon on any row. The rule summary flyout opens alongside the list and shows a snapshot of the rule: its status, last run time, recent alert episode activity, and quick actions such as enable, disable, and snooze. Use the flyout when you want to confirm a rule is healthy or take a quick action without committing to a full page load. To open the complete rule configuration with all settings and edit controls, select the rule name in the table row or in the flyout header. -## Rule details page +## Review rule configuration and activity [rule-details-page] + +The rule details page is organized into tabs that let you review a rule's configuration and activity history. +- **Overview** (Alert mode only): Shows an alert activity timeline for each series the rule tracks. The timeline displays a color-coded history of alert episode state transitions per series, along with summary statistics: alert episodes started, recovered, still open, and median duration. A link to view all matching alert episodes is available, filtered to the current rule and time range. Lane labels appear only for grouped rules. The overview tab is not shown for Signal-mode rules, which don't open alert episodes. - **Conditions**: The full {{esql}} base query, alert condition, schedule, lookback, grouping, and recovery settings. -- **Runbook**: If the rule has an investigation guide, it appears here alongside Conditions. +- **Runbook**: If the rule has an investigation guide, it appears here. Use **Edit** to modify the rule, or the actions menu to enable, disable, clone, or delete it. -## Disable versus snooze +## Disable or snooze a rule [disable-snooze-rule] Use **Disable** when you want the rule to stop running entirely until you re-enable it. This is different from snoozing, which suppresses notifications or quiets a series or policy without stopping rule evaluation. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md index 8937f0c0cd..b8af5ea4e5 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md @@ -11,40 +11,69 @@ description: "YAML rule definitions in Kibana's experimental alerting system sup # YAML rule schema reference for the {{alerting-v2-system}} [yaml-rule-schema-reference] -YAML rule schema is part of the {{alerting-v2-system}} in {{kib}}. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create rules using the YAML editor](create-rule-with-yaml.md). +YAML rule schema is part of the {{alerting-v2-system}} in {{kib}}. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create an ES|QL rule](create-esql-rule.md#yaml-editor). -## Required fields +## Base rule fields + +These four fields are required on every rule, regardless of format or mode. The value of `query.format` determines which additional query fields are required. | Field | Type | Accepted values | Description | |---|---|---|---| | `kind` | string | `alert` or `signal` | Whether the rule tracks ongoing episodes (`alert`) or records point-in-time observations (`signal`). | -| `metadata.name` | string | Max 256 characters | The name of the rule. | -| `schedule.every` | duration | For example, `5s`, `1m`, `5m` | How often the rule runs. Minimum interval applies. | -| `evaluation.query.base` | string | Valid {{esql}} query, max 10,000 characters | The query that checks your data on each run. | +| `metadata.name` | string | Any string | The name of the rule. Max 256 characters. | +| `schedule.every` | duration | Any duration string | How often the rule runs. For example: `5s`, `1m`, `5m`. Minimum interval applies. | +| `query.format` | string | `composed` or `standalone` | The query structure the rule uses. `standalone` means each condition (breach, recovery, no-data) is a separate, self-contained ES\|QL query. `composed` means you write one base query and each condition is a pipe segment appended to it. The UI always creates `standalone` rules. | + +### Fields for `query.format: composed` + +Use `composed` when breach, recovery, and no-data conditions all start from the same data shape. Define that shape once in the base query and each condition adds only what differs. + +| Field | Type | Description | +|---|---|---| +| `query.base` | ES\|QL string | Base query that runs on every evaluation. Time filters are applied automatically using the lookback window. Required. | +| `query.breach.segment` | ES\|QL segment string | Appendable ES\|QL segment for breach detection. Written as a pipe command, for example `\| WHERE count > 5`. Required. | +| `query.recovery.segment` | ES\|QL segment string | Appendable ES\|QL segment for recovery detection. Required when `recovery_strategy` is `query`. | + +### Fields for `query.format: standalone` + +Use `standalone` when conditions need full independence. Each query can target different indices, apply different filters, or return a completely different shape. + +| Field | Type | Description | +|---|---|---| +| `query.breach.query` | Full ES\|QL string | Full ES\|QL query for breach detection. Required. | +| `query.recovery.query` | Full ES\|QL string | Full ES\|QL query for recovery detection. Required when `recovery_strategy` is `query`. | +| `query.no_data.query` | Full ES\|QL string | Full ES\|QL query that detects presence of data. Required when `no_data_strategy` is not `none`. Only supported on `standalone` format. | ## Metadata fields +These optional fields add descriptive information to a rule for identification, ownership, and filtering. None affect rule evaluation behavior. + | Field | Type | Accepted values | Description | |---|---|---|---| -| `metadata.description` | string | Max 1,024 characters | Optional description of what the rule monitors. | -| `metadata.owner` | string | Max 256 characters | Team or person responsible for the rule. | -| `metadata.tags` | array of strings | Max 100 tags | Labels for filtering and organization. | +| `metadata.description` | string | Any string | Optional description of what the rule monitors. Max 1,024 characters. | +| `metadata.owner` | string | Any string | Team or person responsible for the rule. Max 256 characters. | +| `metadata.tags` | array of strings | Array of strings | Labels for filtering and organization. Max 20 tags, each max 128 characters. | ## Schedule fields +These fields control how far back each evaluation looks and which timestamp field is used for the time range filter. Both are optional, but omitting `schedule.lookback` means the query runs without a time bound. + | Field | Type | Accepted values | Description | |---|---|---|---| -| `schedule.lookback` | duration | For example, `5m`, `24h` | How far back in time the query searches on each run. | -| `time_field` | string | Any valid field name, max 128 characters | The timestamp field used for the lookback window filter. Defaults to `@timestamp`. | +| `schedule.lookback` | duration | Any duration string | How far back in time the query searches on each run. For example: `5m`, `24h`. | +| `time_field` | string | Any field name | The timestamp field used for the lookback window filter. Max 128 characters. Defaults to `@timestamp`. | -## Recovery policy fields +## Recovery strategy [recovery-strategy] -The `recovery_policy` field is optional. When absent, the rule emits no recovery events and active alert episodes don't close automatically. Omitting `recovery_policy` is only possible when creating a rule via the API or Agent Builder. Rules created through the Kibana UI always include `recovery_policy.type: no_breach` by default. +The `recovery_strategy` field is optional. When omitted, the rule emits no recovery events and active alert episodes don't close automatically. | Field | Type | Accepted values | Description | |---|---|---|---| -| `recovery_policy.type` | string | `no_breach` or `query` | How recovery is detected. `no_breach` recovers when the query returns no breach results for the active group. `query` uses a separate recovery query. | -| `recovery_policy.query.base` | string | Valid {{esql}} query | Required when `recovery_policy.type` is `query`. The query that checks whether the condition has cleared. | +| `recovery_strategy` | string | `no_breach`, `query`, or `none` | How recovery is detected.

-`no_breach`: Recovers an episode when its active group no longer appears in the breach results.
- `query`: Evaluates a separate recovery query defined in `query.recovery.segment` (composed) or `query.recovery.query` (standalone)
- `none`: Turns off recovery. | + +:::{note} +Signal-mode rules (`kind: signal`) must omit `recovery_strategy` or set it to `none`. Any other value fails validation. +::: ## State transition fields @@ -53,49 +82,43 @@ Only valid when `kind: alert`. Controls how many consecutive detections are requ | Field | Type | Accepted values | Description | |---|---|---|---| | `state_transition.pending_operator` | string | `AND` or `OR` | Whether both the count and timeframe must be met (`AND`) or either one (`OR`) before becoming active. | -| `state_transition.pending_count` | integer | 0 or more | Number of consecutive breaches required before the episode becomes active. | -| `state_transition.pending_timeframe` | duration | For example, `5m` | Time window within which the breach count must be met. | +| `state_transition.pending_count` | integer | Integer ≥ 0 | Number of consecutive breaches required before the episode becomes active. | +| `state_transition.pending_timeframe` | duration | Any duration string | Time window within which the breach count must be met. For example: `5m`. | | `state_transition.recovering_operator` | string | `AND` or `OR` | Whether both the count and timeframe must be met (`AND`) or either one (`OR`) before recovering. | -| `state_transition.recovering_count` | integer | 0 or more | Number of consecutive clear evaluations required before the episode recovers. | -| `state_transition.recovering_timeframe` | duration | For example, `5m` | Time window within which the recovery count must be met. | +| `state_transition.recovering_count` | integer | Integer ≥ 0 | Number of consecutive clear evaluations required before the episode recovers. | +| `state_transition.recovering_timeframe` | duration | Any duration string | Time window within which the recovery count must be met. For example: `5m`. | ## Grouping fields +Use grouping to split a rule's detections into independent series, one per unique combination of field values. This lets a single rule track multiple subjects without creating a separate rule for each, for example, tracking CPU usage per host. Each series maintains its own alert episode lifecycle. + | Field | Type | Accepted values | Description | |---|---|---|---| -| `grouping.fields` | array of strings | Max 16 fields, each max 256 characters | Fields to group results by. Each unique combination becomes its own series. | - - - -## No-data fields +Use `no_data_strategy` to control what the rule does when an evaluation returns no results. This matters when data sources can go silent: without a no-data strategy, a quiet data source and a healthy one look identical to the rule. | Field | Type | Accepted values | Description | |---|---|---|---| -| `no_data.behavior` | string | `no_data`, `last_status`, or `recover` | What happens when the query returns no results. `no_data` records a no-data event. `last_status` keeps the current status. `recover` closes any active episode. | -| `no_data.timeframe` | duration | For example, `5m` | How long the query must return no results before the no-data behavior applies. | +| `no_data_strategy` | string | `emit`, `last_known_status`, `recover`, or `none` | Optional. What happens when the rule evaluates and returns no results. `emit` records a no-data event. `last_known_status` holds the last known status. `recover` forces recovery. `none` disables no-data detection. | -## Artifact fields +:::{note} +No-data detection is only supported with `query.format: standalone`. Setting `no_data_strategy` to any active value on a `composed` rule has no effect because `query.no_data.query` can only be defined on a standalone query. Signal-mode rules (`kind: signal`) must omit `no_data_strategy` or set it to `none`. +::: -| Field | Type | Accepted values | Description | -|---|---|---|---| -| `artifacts[].type` | string | For example, `runbook` | The type of artifact being attached. | -| `artifacts[].value` | string | Markdown content | The content of the artifact. Runbooks are rendered as markdown in the rule detail view. | +## Artifact fields -## Notification policy fields +Artifacts let you attach reference material directly to a rule, such as a runbook. The content is stored with the rule and displayed in the rule detail view so responders have context when an alert fires. All artifact fields are optional. | Field | Type | Accepted values | Description | |---|---|---|---| -| `notification_policies[].ref` | string | Format: `policies/` | Links a notification policy to the rule. | +| `artifacts[].id` | string | Any string | Artifact identifier. Required. Max 256 characters. | +| `artifacts[].type` | string | Any string | The type of artifact being attached. For example: `runbook`. | +| `artifacts[].value` | string | Any string | The content of the artifact. Accepts markdown. Runbooks are rendered as markdown in the rule detail view. | -## Duration format +## Duration format [duration-format] All duration fields accept the following units: diff --git a/explore-analyze/toc.yml b/explore-analyze/toc.yml index 5aeb02a59e..50531ec8bd 100644 --- a/explore-analyze/toc.yml +++ b/explore-analyze/toc.yml @@ -384,15 +384,32 @@ toc: children: - file: alerting/kibana-alerting-experimental/rules.md children: - - file: alerting/kibana-alerting-experimental/rules/author-rules.md - - file: alerting/kibana-alerting-experimental/rules/esql-query-patterns.md - - file: alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md - - file: alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md - - file: alerting/kibana-alerting-experimental/rules/create-rule-with-yaml.md + - file: alerting/kibana-alerting-experimental/rules/create-a-rule.md children: - - file: alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md + - file: alerting/kibana-alerting-experimental/rules/create-esql-rule.md + children: + - file: alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md + - file: alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md + - file: alerting/kibana-alerting-experimental/rules/use-rule-builder.md + - file: alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md - file: alerting/kibana-alerting-experimental/rules/configure-a-rule.md + children: + - file: alerting/kibana-alerting-experimental/rules/configure-rule-mode.md + - file: alerting/kibana-alerting-experimental/rules/configure-rule-query.md + - file: alerting/kibana-alerting-experimental/rules/configure-rule-severity.md + - file: alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md + - file: alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md + - file: alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md + - file: alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md + - file: alerting/kibana-alerting-experimental/rules/configure-rule-tags.md - file: alerting/kibana-alerting-experimental/rules/view-manage-rules.md + - file: alerting/kibana-alerting-experimental/rules/esql-query-patterns.md + children: + - file: alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md + - file: alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md + - file: alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md + - file: alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md + - file: alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md - file: alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md - file: alerting/alerts.md children: From d681407bce70a557c5b1d1189001b0646a468af4 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Tue, 30 Jun 2026 18:08:29 -0400 Subject: [PATCH 06/23] typos and vale issues --- .../kibana-alerting-experimental/rules/configure-a-rule.md | 2 +- .../rules/configure-no-data-handling.md | 2 +- .../rules/configure-rule-grouping.md | 2 +- .../rules/configure-rule-query.md | 4 ++-- .../rules/configure-rule-severity.md | 4 ++-- .../kibana-alerting-experimental/rules/configure-rule-tags.md | 2 +- .../rules/configure-rule-thresholds.md | 4 ++-- .../kibana-alerting-experimental/rules/create-a-rule.md | 2 +- .../rules/create-rule-ai-agent.md | 4 ++-- .../rules/esql-threshold-queries.md | 2 +- .../rules/yaml-rule-schema-reference.md | 4 ++-- 11 files changed, 16 insertions(+), 16 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md index 9ebce4c2b9..aa90553b1b 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -10,7 +10,7 @@ description: "Configure rules in the experimental alerting system: mode, ES|QL q # Configure a rule in the {{alerting-v2-system}} [rule-settings] -Rules in the {{alerting-v2-system}} have three required settings and several optional ones. The table below lists each setting, what it controls, and whether it is required to save a rule. +Rules in the {{alerting-v2-system}} have three required settings and several optional ones. The following table lists each setting, what it controls, and whether it is required to save a rule. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md index 3e47fc0622..202b771527 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md @@ -29,7 +29,7 @@ Set `no_data_strategy` to one of the following values: ### Maintain alert state during a metrics collection outage -This rule monitors infrastructure CPU. If the metrics collection agent stops sending data, you don't want an active CPU breach to auto-recover just because the query returned nothing. Set `no_data_strategy` to `last_known_status`. The rule holds the alert in its current state until data resumes. +This rule monitors infrastructure CPU. If the metrics collection agent stops sending data, you don't want an active CPU breach to auto-recover because the query returned nothing. Set `no_data_strategy` to `last_known_status`. The rule holds the alert in its current state until data resumes. Use this when an empty query result most likely means a pipeline problem rather than a genuine recovery. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md index 50fd62d759..ec07f71d8b 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md @@ -50,7 +50,7 @@ Without a matching `grouping.fields` entry, the rule treats all services as a si ### Track CPU usage per host and region -When the query groups by multiple fields, include all of them in `grouping.fields` to create one alert series per unique combination. +When the query groups by multiple fields, include all fields in `grouping.fields` to create one alert series per unique combination. ```esql FROM metrics-* diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md index 5263a262a5..10b2014090 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md @@ -63,7 +63,7 @@ These parameters work across all rule creation methods. ### Set configurable values in the rule form (`?param`) [form-variables] -When creating a rule through the form, you can use `?param` placeholders, such as `?threshold`, as {{esql}} Control variables. The form resolves these variables and inlines their values into the query before saving. The stored rule and the YAML representation of it contains the resolved values, not the placeholder tokens. +When creating a rule through the form, you can use `?param` placeholders, such as `?threshold`, as {{esql}} Control variables. The form resolves these variables and embeds their values into the query before saving. The stored rule and the YAML representation of it contains the resolved values, not the placeholder tokens. ## Examples @@ -83,7 +83,7 @@ If you omit the time filter, the query scans the full index on every evaluation, ### Using a form variable for a configurable threshold -This query uses `?threshold` as a form variable so the threshold can be set in the rule form UI without editing the query directly. When the rule is saved, the form resolves `?threshold` to its configured value and inlines it. The stored query contains the literal number, not the placeholder. +This query uses `?threshold` as a form variable so the threshold can be set in the rule form UI without editing the query directly. When the rule is saved, the form resolves `?threshold` to its configured value and embeds it. The stored query contains the literal number, not the placeholder. ```esql FROM logs-* diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md index 0c5dfa27c8..f2c8ad667c 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md @@ -15,7 +15,7 @@ Severity is an optional setting for rules in the {{alerting-v2-system}}. To set | Value | Description | Urgency | | --- | --- | --- | | `info` | Informational event worth recording. | No action required. | -| `low` | Minor condition that may need monitoring. | Review when convenient. | +| `low` | Minor condition that might need monitoring. | Review when convenient. | | `medium` | Notable condition that warrants investigation. | Investigate soon. | | `high` | Serious condition requiring prompt attention. | Address promptly. | | `critical` | Severe condition requiring immediate action. | Act immediately. | @@ -40,7 +40,7 @@ Refer to [Rule event and field reference](rule-event-field-reference.md#episode- ## Examples -### Static severity for a simple threshold rule +### Static severity for a fixed threshold rule If every breach of a rule is equally urgent, assign a fixed severity rather than computing it dynamically. The `EVAL` command adds a constant `severity` column to every row the query returns. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md index 75bcd88429..8169513ace 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md @@ -19,7 +19,7 @@ Tags and runbooks are optional metadata fields for Alert-mode rules in the {{ale ### Tag a rule for team ownership and severity -Tags make it easy to filter alerts by team, environment, or severity tier. For a checkout service rule, you might add tags like: +Tags let you filter alerts by team, environment, or severity tier. For a checkout service rule, you might add tags like: - `team:payments` - `env:production` diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md index b0e2865a9a..c3e2da7088 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md @@ -44,7 +44,7 @@ Recovery thresholds control when an active alert episode transitions back to ina | `recovering_timeframe` | Duration string | How long the condition must remain non-breaching before the alert episode closes. | | `recovering_operator` | `AND` or `OR` | When both `recovering_count` and `recovering_timeframe` are set, controls whether both must be satisfied (`AND`) or either one is enough (`OR`). | -Timeframe fields accept the same `5s` to `365d` bounds as activation timeframes. Refer to [Duration format](yaml-rule-schema-reference.md#duration-format) for supported units. +Time frame fields accept the same `5s` to `365d` bounds as activation time frames. Refer to [Duration format](yaml-rule-schema-reference.md#duration-format) for supported units. :::{note} The `recovery_strategy` field controls how recovery is detected, separately from how many recoveries are required. When creating a rule through the UI, `recovery_strategy` defaults to `no_breach`, which recovers the alert episode when its active group no longer appears in the breach batch. @@ -56,7 +56,7 @@ When creating a rule through Agent Builder, you can omit `recovery_strategy` ent ### Ignore brief CPU spikes -This rule monitors CPU usage and runs every minute. A single high reading is often just a process starting up. Set `pending_count` to `3` so the rule requires 3 consecutive breaches before opening an episode, meaning the condition has been true for at least 3 minutes. This filters out noise without losing real signals. +This rule monitors CPU usage and runs every minute. A single high reading is often a process starting up. Set `pending_count` to `3` so the rule requires 3 consecutive breaches before opening an episode, meaning the condition has been true for at least 3 minutes. This filters out noise without losing real signals. ### Require sustained breach before escalating diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md index 4bf9217191..6adb36b950 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md @@ -10,7 +10,7 @@ description: "Create rules in Kibana's experimental alerting system using the ES # Create a rule in the {{alerting-v2-system}} [create-a-rule] -The {{alerting-v2-system}} in {{kib}} provides several ways to create rules. For descriptions of configurable rule setting, refer to [Configure a rule](configure-a-rule.md). +The {{alerting-v2-system}} in {{kib}} provides several ways to create rules. For descriptions of configurable rule settings, refer to [Configure a rule](configure-a-rule.md). | Option | Best for | | --- | --- | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md index cc0b010742..1469083e6c 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md @@ -28,7 +28,7 @@ Signal-mode rules don't support notifications. If you ask the agent to set up no Use these prompts as a starting point, then adjust them to your data and thresholds: -- Create an error threshold rule on my checkout service data. Alert when there are more than 3 HTTP 5xx errors in the past 5 minutes, grouped by URL path. +- Create an error threshold rule on the checkout service data. Alert when there are more than 3 HTTP 5xx errors in the past 5 minutes, grouped by URL path. - Monitor average CPU usage across all hosts. Alert when any host exceeds 90% for more than 10 minutes. -- Alert me when log volume from the payments service drops below 100 events in a 5-minute window. This likely means data has stopped flowing. +- Alert when log volume from the payments service drops below 100 events in a 5-minute window. This likely means data has stopped flowing. - Set up a rule that tracks error rate by service. Alert at medium severity when the rate exceeds 1%, and critical when it exceeds 5%. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md index 9ef349ed7c..ffaf304936 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md @@ -52,7 +52,7 @@ The `BY` fields you use here must match the grouping configuration in the rule. ## Next steps -If both of these patterns are too simple for your use case, the next pages cover more specific detection problems: +If both of these patterns don't fit your use case, the next pages cover more specific detection problems: - [No-data detection](esql-no-data-detection.md): when a host or source stops reporting entirely - [SLO burn rate](esql-slo-burn-rate.md): when you need to check error budget consumption across multiple time windows diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md index b8af5ea4e5..2f2dfc9246 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md @@ -31,8 +31,8 @@ Use `composed` when breach, recovery, and no-data conditions all start from the | Field | Type | Description | |---|---|---| | `query.base` | ES\|QL string | Base query that runs on every evaluation. Time filters are applied automatically using the lookback window. Required. | -| `query.breach.segment` | ES\|QL segment string | Appendable ES\|QL segment for breach detection. Written as a pipe command, for example `\| WHERE count > 5`. Required. | -| `query.recovery.segment` | ES\|QL segment string | Appendable ES\|QL segment for recovery detection. Required when `recovery_strategy` is `query`. | +| `query.breach.segment` | ES\|QL segment string | ES\|QL segment appended to the base query for breach detection. Written as a pipe command, for example `\| WHERE count > 5`. Required. | +| `query.recovery.segment` | ES\|QL segment string | ES\|QL segment appended to the base query for recovery detection. Required when `recovery_strategy` is `query`. | ### Fields for `query.format: standalone` From f3e1bfd740449af39c6f3196afda7112ca6f6b3a Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Wed, 1 Jul 2026 13:04:53 -0400 Subject: [PATCH 07/23] Apply suggestions from code review Co-authored-by: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> --- explore-analyze/alerting/kibana-alerting-experimental/rules.md | 2 +- .../kibana-alerting-experimental/rules/configure-rule-tags.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules.md index 921cbb53c0..c49647e39b 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules.md @@ -16,7 +16,7 @@ This page explains what rules do, what they don't control, and how to choose a c ## What rules do [detection-and-notification] -On each run, a rule executes an {{esql}} query against your data. If the query finds a match and the rule is in Signal mode, it writes a _signal_, a point-in-time record that the condition was met. In Alert mode, it also maintains an _alert episode_ for each matched series, tracking state from first breach through recovery. +On each run, a rule executes an {{esql}} query against your data. If the query finds a match, it writes a rule event (`rule_event`), a point-in-time record that the condition was met. In Alert mode, it also maintains an _alert episode_ for each matched series, tracking state from first breach through recovery. When creating a rule, choose Signal mode to record and query results without alerting anyone, or Alert mode when you want to track issues and route notifications. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md index 8169513ace..a4e63661ae 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md @@ -10,7 +10,7 @@ description: "Add tags and runbooks to Alert-mode rules in Kibana's experimental # Tags and runbooks in the {{alerting-v2-system}} (Alert mode only) [tags-investigation] -Tags and runbooks are optional metadata fields for Alert-mode rules in the {{alerting-v2-system}}. +Tags and runbooks are optional artifacts for Alert-mode rules in the {{alerting-v2-system}}. - **Tags**: Free-form labels for filtering and organization. Maximum 20 tags per rule; each tag can be up to 128 characters. - **Runbooks**: An investigation guide stored with the rule so responders have context when alerts are generated. From dcd6af70f164bf2c81e2af09a0d4abc374a2f1cc Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 1 Jul 2026 18:17:27 -0400 Subject: [PATCH 08/23] Add to agentic workflow docs and adds prescriptive guidance for rules --- .../rules/configure-a-rule.md | 10 +-- .../rules/configure-no-data-handling.md | 19 ++++- .../rules/configure-rule-grouping.md | 21 +++++- .../rules/configure-rule-mode.md | 29 +++++++- .../rules/configure-rule-query.md | 26 +++++-- .../rules/configure-rule-schedule.md | 29 ++++++++ .../rules/configure-rule-severity.md | 21 +++++- .../rules/configure-rule-tags.md | 26 ++++++- .../rules/configure-rule-thresholds.md | 21 ++++-- .../rules/create-a-rule.md | 4 +- .../rules/create-esql-rule.md | 2 +- .../rules/create-rule-ai-agent.md | 50 +++++++++++--- .../rules/create-rule-from-discover.md | 2 +- ...ate-rules-action-policies-agent-builder.md | 69 +++++++++++++++++++ .../rules/rule-event-field-reference.md | 2 +- .../rules/use-rule-builder.md | 6 +- explore-analyze/toc.yml | 2 +- 17 files changed, 295 insertions(+), 44 deletions(-) create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md index aa90553b1b..90d3e84b6b 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -10,18 +10,18 @@ description: "Configure rules in the experimental alerting system: mode, ES|QL q # Configure a rule in the {{alerting-v2-system}} [rule-settings] -Rules in the {{alerting-v2-system}} have three required settings and several optional ones. The following table lists each setting, what it controls, and whether it is required to save a rule. +Rules in the {{alerting-v2-system}} have three required settings and several optional ones. Start with the required settings in order: first, select the rule mode (which determines which optional settings are relevant), then define the {{esql}} query, then specify the rule execution schedule. Add optional settings once the detection logic is validated. | Setting | Description | Required | | --- | --- | --- | -| [Rule mode](configure-rule-mode.md) | Signal or Alert. Controls whether matching rows generate signal documents or tracked alert episodes. | Required | -| [ES\|QL query](configure-rule-query.md) | The detection logic and the parameters available in query expressions. | Required | +| [Rule mode](configure-rule-mode.md) | Can be Signal or Alert. Controls whether matching rows generate signal documents or tracked alert episodes. | Required | +| [{{esql}} query](configure-rule-query.md) | The detection logic and the parameters available in query expressions. | Required | | [Schedule and lookback](configure-rule-schedule.md) | How often the rule evaluates and how far back the query looks. | Required | | [Severity](configure-rule-severity.md) | Assign severity levels to alert episodes using a `severity` column in query output. | Optional | | [Grouping](configure-rule-grouping.md) | Track multiple subjects (hosts, services, users) as independent alert series in one rule. | Optional | -| [Activation and recovery thresholds](configure-rule-thresholds.md) | Reduce noise with delay modes for opening and closing alert episodes. (Alert mode only) | Optional | +| [Activation and recovery thresholds](configure-rule-thresholds.md) | Reduce noise with delay modes for opening and closing alert episodes. Alert mode only. | Optional | | [No-data handling](configure-no-data-handling.md) | What the rule records when the base query returns no results. | Optional | -| [Tags and runbooks](configure-rule-tags.md) | Free-form labels and investigation guides attached to the rule. (Alert mode only) | Optional | +| [Tags and runbooks](configure-rule-tags.md) | Free-form labels and investigation guides attached to the rule. Alert mode only. | Optional | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md index 202b771527..9f930331cd 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md @@ -12,12 +12,12 @@ description: "Configure no-data handling for rules in Kibana's experimental aler No-data handling is an optional setting for rules in the {{alerting-v2-system}}. Use `no_data_strategy` to control what the rule records when the base query returns no results. Setting this correctly prevents false recoveries and misleading `no_data` events when data sources stop reporting. -Set `no_data_strategy` to one of the following values: +The `no_data_strategy` field accepts the following values. | Value | Description | | --- | --- | | `emit` | Record a no-data event. | -| `last_known_status` | Hold the last known lifecycle state. An active breach stays active; a recovered episode stays recovered. | +| `last_known_status` | Hold the last known lifecycle state. An active breach stays active and a recovered episode stays recovered. | | `recover` | Treat absence as recovery. | | `none` | Turn off no-data detection | @@ -25,6 +25,19 @@ Set `no_data_strategy` to one of the following values: `no_data_strategy` does not detect when a specific host or data source stops reporting while others continue. Refer to [No-data detection](esql-no-data-detection.md) for an {{esql}} pattern that surfaces silent sources as alert rows. ::: +## When to configure no-data handling [no-data-when-to-use] + +Configure `no_data_strategy` when: + +* The data source your rule monitors can go silent. Examples include a metrics agent that stops reporting, a pipeline that breaks, or a service that stops generating events. +* A false recovery caused by an empty query result would be more harmful than holding the current alert state. +* Absence of data is itself a signal worth surfacing, such as missing heartbeat events from a critical service. + +Leave `no_data_strategy` unconfigured (or set to `none`) when: + +* Your data source reliably produces output on every evaluation and a gap in data would indicate a genuine recovery. +* You are still tuning the rule and don't yet know how it behaves when data is absent. Set the strategy once the rule's normal behavior is understood. + ## Examples ### Maintain alert state during a metrics collection outage @@ -35,6 +48,6 @@ Use this when an empty query result most likely means a pipeline problem rather ### Surface a broken data pipeline as an alert -This rule monitors for login events from an identity provider. If no events appear in the lookback window, it's unusual enough to warrant attention: either the pipeline is broken or something has suppressed activity. Set `no_data_strategy` to `emit`. The absence is recorded as a `no_data` event in `.rule-events`, making it visible alongside other rule activity. +This rule monitors for login events from an identity provider. If no events appear in the lookback window, it's unusual enough to warrant attention. Either the pipeline is broken or something has suppressed activity. Set `no_data_strategy` to `emit`. The absence is recorded as a `no_data` event in `.rule-events`, making it visible alongside other rule activity. Use this when receiving no data is itself a signal worth investigating. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md index ec07f71d8b..a20279f1c1 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md @@ -21,9 +21,24 @@ Rule grouping is an optional setting in the {{alerting-v2-system}} that lets a s Rule grouping controls how alert series are created. Notification grouping (configured on an action policy) controls how those alert episodes are batched into messages. These are separate settings. ::: -## Aligning `BY` fields with your rule's query +## When to configure grouping [grouping-when-to-use] -The `BY` fields you specify for grouping must match the columns in the `BY` clause of your {{esql}} `STATS` command. If they don't match, the grouping configuration won't work as expected. +Configure grouping when: + +* Your {{esql}} query uses a `BY` clause to aggregate across multiple subjects such as hosts, services, or users, and you want each subject to have an independent alert lifecycle. +* You need to track that one host has recovered while another is still breaching, rather than treating all subjects as a single combined series. +* You want action policy notifications to apply per subject rather than firing once for the entire rule. + +Skip grouping when: + +* Your query does not use a `BY` clause. Grouping requires `BY` columns in the query output to be meaningful. +* You intentionally want a single alert series for the rule regardless of how many subjects match. An example is a rule that fires when any host in a cluster is down and the individual host identity doesn't matter for the notification. + +## Configure grouping fields [grouping-fields-config] + +The {{alerting-v2-system}} does not automatically infer grouping from your {{esql}} query. When your query uses `BY` to produce one row per group, the system still treats all rows as a single series unless you explicitly declare which fields define series identity in the grouping configuration. The fields you declare in `grouping.fields` are what the system uses to separate rows into independent alert series and track each one through its own lifecycle. + +The fields you declare in `grouping.fields` must match the column names produced by the `BY` clause in your {{esql}} `STATS` command. If they don't match, the system can't correlate query rows to alert series and the grouping configuration has no effect. :::{tip} Write the query first, then set the group fields. That way the `BY` columns are already defined and you can select them directly. If you later add or remove a `BY` field in the query, update the group fields to match. @@ -36,7 +51,7 @@ Write the query first, then set the group fields. That way the `BY` columns are ### Track error rates per service -This rule counts HTTP errors per service and opens a separate alert series for each service that exceeds the threshold. Each service gets its own lifecycle: if the checkout service recovers but the payments service stays critical, those are tracked independently. +This rule counts HTTP errors per service and opens a separate alert series for each service that exceeds the threshold. Each service gets its own lifecycle. If the checkout service recovers but the payments service stays critical, those are tracked independently. ```esql FROM logs-* diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md index 495a65c905..aeaf45067e 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md @@ -10,13 +10,40 @@ description: "Choose between Signal and Alert mode for rules in Kibana's experim # Rule mode in the {{alerting-v2-system}} [rule-mode] -Rule mode is a required setting for rules in the {{alerting-v2-system}}. Rule mode set by the rule creation method and some creation paths only support one mode. Refer to [Create a rule](create-a-rule.md) for available options. +Rule mode is a required setting for rules in the {{alerting-v2-system}}. Rule mode is set by the rule creation method and some creation paths only support one mode. Refer to [Create a rule](create-a-rule.md) for available options. + +:::{tip} +Start with Signal mode to validate your detection logic without generating noise. Switch to Alert mode once the rule is tuned and you want to track episodes or route notifications. +::: | Mode | Behavior | Best for | | --- | --- | --- | | Signal | Records each matching row as a signal document. No alert episodes, no notifications. | Testing a new query, building detection history, or observing matches without notifying anyone. | | Alert | Creates an alert episode for each matching row. Episodes are tracked through lifecycle states, appear on the **Alerts** page, and can be routed to notifications by action policies. | Production rules where breaches should be tracked, escalated, or routed to a notification channel. | +## When to use each mode [rule-mode-when-to-use] + +Signal mode is the right fit when: + +* You are writing a new detection query and want to verify it produces the expected matches before notifying anyone. +* You need to build detection history in `.rule-events` without generating alert noise or triggering notifications. +* You want to observe matches in Discover without opening tracked episodes on the **Alerts** page. + +Signal mode is **not** the right fit when: + +* You need to track how long a condition has been active or how it transitions between states. Signal mode does not create episodes or lifecycle state. +* You need notifications when a condition fires. Switch to Alert mode and attach an action policy. + +Alert mode is the right fit when: + +* The rule is production-ready and breaches should open tracked episodes with lifecycle state. +* You need the rule to appear on the **Alerts** page for triage, acknowledgment, or escalation. +* You want to attach action policies to route notifications when episodes open, escalate, or recover. + +Alert mode is **not** the right fit when: + +* The rule's query is still being tuned and generating alerts would create noise for on-call teams. Use Signal mode to validate first, then switch. + ## Examples ### Build detection history before enabling alerts diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md index 10b2014090..3ccff1a84f 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md @@ -10,13 +10,29 @@ description: "Configure the ES|QL query and query parameters for rules in Kibana # {{esql}} query in the {{alerting-v2-system}} [esql-query-rule] -Every rule in the {{alerting-v2-system}} uses an {{esql}} query to define what to evaluate. The query has two parts: a base query that shapes and filters the data, and an optional alert condition that determines which rows become alert events. For more advanced use cases, the query also supports [dynamic values](#dynamic-query-values) for filtering by the evaluation window or setting configurable thresholds through the rule form. +Every rule in the {{alerting-v2-system}} uses an {{esql}} query to define what to evaluate. The query consists of a base query that shapes and filters the data and an optional alert condition that determines which rows become alert events. For more advanced use cases, the query also supports [dynamic values](#dynamic-query-values) for filtering by the evaluation window or setting configurable thresholds through the rule form. + +:::{tip} +Use the query preview option to test your query against live data before saving the rule. This lets you verify the detection logic produces the results you expect without committing to a schedule or opening alert episodes. +::: + +## When to add an alert condition [query-when-to-use] + +Add an alert condition when: + +* Your base query returns aggregate results (for example, counts or averages per group) and you only want to alert when a value crosses a specific threshold. Without an alert condition, every row returned by the base query is treated as a breach. +* You want to keep filtering logic out of the base query and express the threshold separately for clarity. + +Skip the alert condition when: + +* Every row returned by the base query should be treated as a breach. This applies when the query filters directly for specific error events where any match warrants attention. +* All filtering can be expressed cleanly in a single `WHERE` clause without a two-stage query. ## Base query [query-base] The base query is the main {{esql}} expression. Use `FROM` to point the rule at the indices or data streams to read. Shape results with `STATS`, `WHERE`, and `EVAL`, and control which fields are stored with `KEEP`. The base query runs on every evaluation, even when no match occurs, which is what enables no-data detection and recovery. The [{{esql}} reference](elasticsearch://reference/query-languages/esql.md) covers all available commands and processing functions. -This query counts HTTP 5xx errors per service over the lookback window and stores only the fields needed for triage: +This query counts HTTP 5xx errors per service over the lookback window and stores only the fields needed for triage. ```esql FROM logs-* @@ -31,7 +47,7 @@ Without an alert condition, every row returned by this query is treated as a bre The alert condition is an optional `WHERE` clause appended after the base query. Only rows that pass the condition are treated as breaches. Use an alert condition when the base query returns aggregate results and you only want to alert when a value crosses a threshold. -This example extends the base query above to only fire when a service exceeds 10 errors: +This example extends the base query above to only fire when a service exceeds 10 errors. ```esql FROM logs-* @@ -46,11 +62,11 @@ The `KEEP` command controls which fields appear on each stored alert event. Only ## Use dynamic values in your rule query [dynamic-query-values] -{{esql}} rule queries support two kinds of parameters that make queries more dynamic: time bounds that the executor injects automatically, and form variables you define when creating a rule. You don't need either to write a working rule, but they're useful for scoping queries precisely to the evaluation window or making thresholds configurable without editing the query. +{{esql}} rule queries support two kinds of parameters that make queries more dynamic. The executor injects time bounds automatically, and you define form variables when creating a rule. You don't need either to write a working rule, but they're useful for scoping queries precisely to the evaluation window or making thresholds configurable without editing the query. ### Filter your query to the evaluation window (`?_tstart` and `?_tend`) [time-bound-parameters] -`?_tstart` and `?_tend` are reserved parameter names that the rule executor binds automatically on every evaluation. They hold the start and end timestamps of the lookback window, so you can scope a query to exactly the period the rule is evaluating: +`?_tstart` and `?_tend` are reserved parameter names that the rule executor binds automatically on every evaluation. They hold the start and end timestamps of the lookback window, so you can scope a query to exactly the period the rule is evaluating. ```esql FROM logs-* diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md index 9bbc393fc6..7051716080 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md @@ -24,6 +24,35 @@ The lookback window (`schedule.lookback`) determines the time range that the {{e If the lookback is shorter than the execution interval, evaluations can miss data between runs. Use a lookback at least as long as the execution interval unless you have a deliberate reason not to. +:::{tip} +When setting up a new rule, start with a longer lookback to verify the query covers the data you expect, then tighten it once the rule is stable. +::: + +## When to use a short or long interval and lookback [schedule-when-to-use] + +Use a short execution interval (seconds to a few minutes) when: + +* The condition being monitored can develop quickly and fast detection is critical. Examples include a burst of failed authentication attempts or a spike in HTTP error rate. +* Notification latency matters and you need the rule to fire close to when the breach occurs. + +Use a longer execution interval (tens of minutes or more) when: + +* The condition develops slowly and near-real-time detection isn't required. Examples include disk utilization for capacity planning or a weekly job failure check. +* You want to reduce evaluation cost. Longer intervals lower the frequency of query execution against your data. + +Use a short lookback window when: + +* Your data arrives reliably and with low latency, and you want to avoid re-scanning data that older evaluations already covered. +* You are running high-frequency rules where a narrow window keeps each evaluation focused on recent data. + +Use a longer lookback window when: + +* The condition you're detecting can develop across multiple events spread over time, and a narrow window might miss the full picture. +* You are setting up a new rule and want to verify the query covers the expected data before tightening the window. +* Ingestion lag means events arrive later than their timestamps, and a wider window ensures late-arriving data is still evaluated. + +Avoid setting the lookback shorter than the execution interval. If the lookback doesn't cover the full gap between evaluations, events that arrive between runs can be missed. + ## Examples ### High-frequency security rule diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md index f2c8ad667c..2d535251ce 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md @@ -10,7 +10,11 @@ description: "Assign severity levels to alert episodes in Kibana's experimental # Severity in the {{alerting-v2-system}} [rule-severity] -Severity is an optional setting for rules in the {{alerting-v2-system}}. To set it, include a column named `severity` in your {{esql}} query output and add it to your `KEEP` list. The framework reads that column after each evaluation and maps it to one of five fixed levels: +Severity is an optional setting for rules in the {{alerting-v2-system}}. To set it, include a column named `severity` in your {{esql}} query output and add it to your `KEEP` list. The framework reads that column after each evaluation and maps it to one of five fixed levels. + +:::{tip} +Add severity to your rule when you need to route or filter alert episodes by urgency, for example, to send critical episodes to an on-call channel and low episodes to a review queue. +::: | Value | Description | Urgency | | --- | --- | --- | @@ -20,6 +24,19 @@ Severity is an optional setting for rules in the {{alerting-v2-system}}. To set | `high` | Serious condition requiring prompt attention. | Address promptly. | | `critical` | Severe condition requiring immediate action. | Act immediately. | +## When to configure severity [severity-when-to-use] + +Configure severity when: + +* You want to route different urgency levels to different notification channels, for example, send `critical` episodes to an on-call channel and `low` episodes to a review queue. +* You want to filter the **Alerts** page by urgency to help triage during incidents. +* The rule's detection logic can meaningfully distinguish between urgency levels through a computed metric, such as burn rate, error count, or latency percentile. + +Skip severity when: + +* All breaches from the rule are equally urgent. A fixed label in the rule's tags is simpler and doesn't require query changes. +* The underlying data doesn't produce a reliable metric to grade urgency. Severity that's frequently wrong generates more noise than routing by severity resolves. + ## How the {{alerting-v2-system}} maps severity values The {{alerting-v2-system}} maps the `severity` column to an internal level after each evaluation using the following rules: @@ -57,7 +74,7 @@ Every breach from this rule produces a `critical` episode. Use this when the thr ### Dynamic severity based on burn rate -Use `CASE` to map a computed metric to different severity levels. This query grades each service's error rate: services consuming error budget at 14.4× baseline or above are `critical`; those between 6× and 14.4× are `high`; and so on. Only services above 1× are returned, so below-threshold services don't generate alert rows. +Use `CASE` to map a computed metric to different severity levels. This query grades each service's error rate. Services consuming error budget at 14.4× baseline or above are `critical`, those between 6× and 14.4× are `high`, and so on. Only services above 1× are returned, so below-threshold services don't generate alert rows. ```esql FROM metrics-* diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md index a4e63661ae..f9acd71234 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md @@ -12,9 +12,31 @@ description: "Add tags and runbooks to Alert-mode rules in Kibana's experimental Tags and runbooks are optional artifacts for Alert-mode rules in the {{alerting-v2-system}}. -- **Tags**: Free-form labels for filtering and organization. Maximum 20 tags per rule; each tag can be up to 128 characters. +- **Tags**: Free-form labels for filtering and organization. Maximum 20 tags per rule. Each tag can be up to 128 characters. - **Runbooks**: An investigation guide stored with the rule so responders have context when alerts are generated. +:::{tip} +Tags are inherited by alert episodes, so they're available for filtering in the alerts view and as KQL matchers in action policies. Use them to organize rules by team, environment, or severity tier. +::: + +## When to configure tags and runbooks [tags-when-to-use] + +Configure tags when: + +* You want to filter the **Alerts** page by team, environment, or severity tier without writing ad hoc KQL queries each time. +* You are using action policies and want to match episodes by ownership or category rather than by rule name. +* You manage many rules and need a consistent labeling scheme to track which team owns which alerts. + +Configure a runbook when: + +* Responders who aren't familiar with the service may need to triage the alert. A runbook surfaces triage steps directly alongside the alert without requiring a separate search. +* The alert requires a consistent response process that you want encoded and version-controlled alongside the rule. + +Skip tags and runbooks when: + +* The rule is in Signal mode. Tags and runbooks are Alert-mode-only artifacts and have no effect on signal document output. +* The rule is experimental or not yet part of a monitored production system. + ## Examples ### Tag a rule for team ownership and severity @@ -29,7 +51,7 @@ On-call engineers can then narrow the alerts view to rules their team owns witho ### Add a runbook with triage steps -A runbook gives responders immediate context when an alert fires. Write it as plain text in the rule's description field. Include enough detail that an engineer unfamiliar with the service can triage without asking for help: +A runbook gives responders immediate context when an alert fires. Write it as plain text in the rule's description field. Include enough detail that an engineer unfamiliar with the service can triage without asking for help. ``` Fires when checkout error rate exceeds 10% for 3 consecutive evaluations. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md index c3e2da7088..5f022d0f78 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md @@ -5,12 +5,25 @@ applies_to: serverless: experimental products: - id: kibana -description: "Configure activation and recovery thresholds for Alert-mode rules in Kibana's experimental alerting system to reduce noise from spikes and flapping." +description: "Configure activation and recovery thresholds for Alert-mode rules in Kibana's experimental alerting system to reduce noise from brief spikes and rapid state changes." --- # Activation and recovery thresholds in the {{alerting-v2-system}} (Alert mode only) [activation-recovery-thresholds] -Activation and recovery thresholds are optional settings for Alert-mode rules in the {{alerting-v2-system}}. They control when alerts transition between lifecycle states, reducing noise from short spikes and rapid flapping between active and recovered. +Activation and recovery thresholds are optional settings for Alert-mode rules in the {{alerting-v2-system}}. They control when alerts transition between lifecycle states, reducing noise from brief spikes and rules that alternate rapidly between breaching and recovering. + +## When to configure thresholds [thresholds-when-to-use] + +Configure activation and recovery thresholds when: + +* The metric being monitored fluctuates and a single breach or recovery doesn't reflect a real state change. Examples include CPU usage that briefly spikes during process startup or a connection pool that crosses the threshold on alternating evaluations. +* You want to reduce notification noise from rules that alternate rapidly between breaching and recovering on consecutive evaluations. +* The cost or urgency of a notification is high enough that you need confidence the condition is sustained before alerting on it. + +Skip activation and recovery thresholds when: + +* Any single breach warrants immediate attention and you cannot tolerate the added latency of waiting for consecutive evaluations. Leave the activation mode set to Immediate. +* The rule is in Signal mode. Thresholds only apply to Alert-mode rules and have no effect on signal document output. ## Activation thresholds @@ -36,7 +49,7 @@ You can combine Breaches and Duration. For example, require the threshold to be ## Recovery thresholds -Recovery thresholds control when an active alert episode transitions back to inactive. The same delay modes available for activation apply here: consecutive recoveries required, minimum recovery duration, or both. +Recovery thresholds control when an active alert episode transitions back to inactive. The same delay modes available for activation apply. You can require a set number of consecutive recoveries, a minimum recovery duration, or both. | Field | Type | Description | | --- | --- | --- | @@ -62,6 +75,6 @@ This rule monitors CPU usage and runs every minute. A single high reading is oft This rule monitors a payment error rate. Brief spikes happen during deployments and are expected. Set `pending_count` to `5`, `pending_timeframe` to `2m`, and `pending_operator` to `AND`. The rule only fires when the error rate has breached on 5 consecutive evaluations and has been continuously elevated for at least 2 minutes. Either condition alone isn't enough. -### Prevent flapping on recovery +### Require consecutive recoveries before closing an episode This rule monitors database connection pool saturation. After the condition clears, set `recovering_count` to `3` to require 3 consecutive non-breaching evaluations before closing the episode. Without this, a rule that alternates between breaching and recovering on consecutive evaluations generates a constant stream of open and closed notifications. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md index 6adb36b950..aa225c9276 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md @@ -10,12 +10,12 @@ description: "Create rules in Kibana's experimental alerting system using the ES # Create a rule in the {{alerting-v2-system}} [create-a-rule] -The {{alerting-v2-system}} in {{kib}} provides several ways to create rules. For descriptions of configurable rule settings, refer to [Configure a rule](configure-a-rule.md). +The {{alerting-v2-system}} in {{kib}} provides several ways to create rules. For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). | Option | Best for | | --- | --- | | [Create an ES\|QL rule](create-esql-rule.md) | Full control over the query. Supports both a step-by-step form and a YAML editor. | -| [Create with AI Agent](create-rule-ai-agent.md) | When you know what you want to detect but aren't sure how to write the ES\|QL. | +| [Create with AI Agent](create-rules-action-policies-agent-builder.md) | When you know what you want to detect but aren't sure how to write the ES\|QL. | | [Use the rule builder](use-rule-builder.md) | Rules that follow a guided, form-based setup. | | [Create from Discover](create-rule-from-discover.md) | When you already have an ES\|QL query working in Discover and want to convert it into a rule. | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md index 49f78bcce2..489561ee00 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md @@ -15,7 +15,7 @@ The {{esql}} rule path lets you write the detection query directly. There are tw - **Rule form** - Fill in the step-by-step form with a live preview of results. - **YAML mode** - Switch to YAML and edit the raw rule definition. You can switch between form and YAML at any point; edits are preserved. -For descriptions of each rule setting, refer to [Configure a rule](configure-a-rule.md). For a list of supported YAML fields, refer to [YAML rule schema reference](yaml-rule-schema-reference.md). +For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). For a list of supported YAML fields, refer to [YAML rule schema reference](yaml-rule-schema-reference.md). ## Preview query results in the sandbox [rule-builder-query-sandbox] diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md index 1469083e6c..6951dd17ac 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md @@ -1,27 +1,35 @@ --- -navigation_title: Create with AI Agent +navigation_title: Create rules and action policies with Agent Builder applies_to: stack: experimental 9.5+ serverless: experimental products: - id: kibana -description: "Use the Elastic AI Agent to generate ES|QL rules from plain-language descriptions in Kibana's experimental alerting system." +description: "How {{agent-builder}} creates rules and action policies in the experimental alerting system using the rule management skill, what the agent produces, and the save-order dependency." --- -# Create a rule with AI Agent in the {{alerting-v2-system}} [create-rule-ai-agent] +# Create rules and action policies with {{agent-builder}} [create-rules-action-policies-ai-agent] -The AI Agent option opens the Elastic AI agent pre-loaded with rule management knowledge. Describe what you want to monitor in plain language and the agent resolves the relevant data source and builds a rule proposal. +Rule and action policy authoring in {{agent-builder}} is part of the {{alerting-v2-system}} in {{kib}}. The {{alerting-v2-system}} registers rules and action policies as attachment types in {{agent-builder}}, so an agent equipped with the rule management skill can propose, create, and configure them through natural language conversation. -The proposal appears as an inline attachment card in the conversation showing the rule name, type, schedule, and tags. Select the card to open a flyout with three tabs: +Instead of filling out the rule form manually, you describe what you want to monitor and the agent uses its rule management skill and tools to resolve the data source and build a fully configured rule proposal for you. -- **Conditions** - The full rule configuration, including query, thresholds, grouping, and schedule. -- **Query preview** - Runs the {{esql}} query and shows results inline so you can verify the detection logic without leaving the conversation. -- **Runbook** - A free-text runbook associated with the rule. +## How rule proposals work [ai-agent-rule-proposal] -The agent doesn't save the rule automatically. When the proposal looks correct, select **Save as rule** from the flyout header to persist it. After saving, you can ask the agent to configure notifications, which creates an action policy scoped to that rule. +The rule management skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of ES\|QL query patterns, threshold configuration, grouping, and the alerting v2 data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. -:::{note} -Signal-mode rules don't support notifications. If you ask the agent to set up notifications on a signal rule, the agent will explain the limitation and offer to convert the rule to Alert mode or create a new Alert-mode rule. +The proposal appears as an inline attachment in the conversation, summarizing the rule name, type, schedule, and tags. Opening the attachment shows the full configuration across three views: + +- **Conditions** - The ES\|QL query, thresholds, grouping criteria, and schedule the agent constructed. +- **Query preview** - The results of running the proposed ES\|QL query against live data, so you can evaluate whether the rule would produce meaningful signal before committing to it. +- **Runbook** - A free-text runbook field associated with the rule, which the agent can populate from context in the conversation. + +The agent can also search for and attach an existing rule to the conversation using the same inline attachment, opening the same view for inspection or revision. + +The agent does not persist the rule automatically. Saving is an explicit action that signals the configuration is ready. Until the rule is saved, the proposal exists only in the conversation and is not evaluated against data. + +:::{note} +Signal rules do not support notifications. Alert episodes, and therefore action policies, only apply to rules running in Alert mode. If you ask the agent to set up notifications for a signal rule, the rule management skill explains the limitation and offers to either convert the rule to Alert mode or create a separate alert rule. ::: ## Example prompts [ai-agent-sample-prompts] @@ -32,3 +40,23 @@ Use these prompts as a starting point, then adjust them to your data and thresho - Monitor average CPU usage across all hosts. Alert when any host exceeds 90% for more than 10 minutes. - Alert when log volume from the payments service drops below 100 events in a 5-minute window. This likely means data has stopped flowing. - Set up a rule that tracks error rate by service. Alert at medium severity when the rate exceeds 1%, and critical when it exceeds 5%. + + +## How notification setup works [ai-agent-notification-setup] + +After a rule is saved, you can ask the agent to configure notifications. The rule management skill handles this by creating two objects: + +- A **workflow** - The delivery mechanism. It defines what happens when the {{alerting-v2-system}} determines that a notification should be sent: posting to Slack, emailing a team, triggering PagerDuty, and so on. +- An **action policy** - The gating mechanism. It evaluates alert episodes from the rule on a continuous schedule and invokes the workflow when the episode clears the policy's match conditions and frequency settings. When the agent creates an action policy alongside a specific rule, the policy is automatically scoped to that rule as a per-rule policy. + +Both objects are proposed as inline attachments and must be explicitly saved before they take effect. + +### Save order [save-order-ai-agent] + +The three objects have a dependency chain that determines the order in which they must be saved: + +1. **Rule** - The action policy references the rule by ID. The ID is not available until the rule is persisted. +2. **Workflow** - The action policy references the workflow as a destination. The reference must resolve to a persisted workflow. +3. **Action policy** - Can only be saved after both its rule and workflow dependencies exist. + +This order is enforced in the UI. The action policy save control remains inactive until both dependencies are met. \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md index 131b0e9e53..1eaf4b2f40 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md @@ -25,7 +25,7 @@ When you trigger rule creation from Discover, your {{esql}} query pre-fills the The rule creation flyout supports both a step-by-step form and a YAML editing mode. You can switch between them at any point; edits in YAML mode are preserved when you return to the form view. The YAML editor includes {{esql}} autocomplete in the query field. -For descriptions of what each rule setting does, refer to [Configure a rule](configure-a-rule.md). +For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md new file mode 100644 index 0000000000..9885d507ef --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md @@ -0,0 +1,69 @@ +--- +navigation_title: Create rules and action policies with Agent Builder +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "How {{agent-builder}} creates rules and action policies in the experimental alerting system using the rule management skill, what the agent produces, and the save-order dependency." +--- + +# Create rules and action policies with {{agent-builder}} [create-rules-action-policies-ai-agent] + +Rule and action policy authoring in {{agent-builder}} is part of the {{alerting-v2-system}} in {{kib}}. The {{alerting-v2-system}} registers rules and action policies as attachment types in {{agent-builder}}, so an agent equipped with the rule management skill can propose, create, and configure them through natural language conversation. + +Instead of filling out the rule form manually, you describe what you want to monitor and the agent uses its rule management skill and tools to resolve the data source and build a fully configured rule proposal for you. + +## Propose and save a rule [ai-agent-rule-proposal] + +To use this capability, open an agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the rule management skill configured. The rule management skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of ES\|QL query patterns, threshold configuration, grouping, and the alerting v2 data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. + +The proposal appears as an inline attachment in the conversation, summarizing the rule name, type, schedule, and tags. Opening the attachment shows the full configuration across three views: + +- **Conditions** - The ES\|QL query, thresholds, grouping criteria, and schedule the agent constructed. +- **Query preview** - The results of running the proposed ES\|QL query against live data, so you can evaluate whether the rule would produce meaningful signal before committing to it. +- **Runbook** - A free-text runbook field associated with the rule, which the agent can populate from context in the conversation. + +The agent can also search for and attach an existing rule to the conversation using the same inline attachment, opening the same view for inspection or revision. + +The agent does not persist the rule automatically. Saving is an explicit action that signals the configuration is ready. Until the rule is saved, the proposal exists only in the conversation and is not evaluated against data. + +:::{note} +Signal rules do not support notifications. Alert episodes, and therefore action policies, only apply to rules running in Alert mode. If you ask the agent to set up notifications for a signal rule, the rule management skill explains the limitation and offers to either convert the rule to Alert mode or create a separate alert rule. +::: + +## Example prompts [ai-agent-sample-prompts] + +Use these prompts as a starting point, then adjust them to your data and thresholds: + +- Create an error threshold rule on the checkout service data. Alert when there are more than 3 HTTP 5xx errors in the past 5 minutes, grouped by URL path. +- Monitor average CPU usage across all hosts. Alert when any host exceeds 90% for more than 10 minutes. +- Alert when log volume from the payments service drops below 100 events in a 5-minute window. This likely means data has stopped flowing. +- Set up a rule that tracks error rate by service. Alert at medium severity when the rate exceeds 1%, and critical when it exceeds 5%. + + +## Set up notifications [ai-agent-notification-setup] + +After a rule is saved, you can ask the agent to configure notifications. The rule management skill handles this by creating two objects: + +- A **workflow** - The delivery mechanism. It defines what happens when the {{alerting-v2-system}} determines that a notification should be sent: posting to Slack, emailing a team, triggering PagerDuty, and so on. +- An **action policy** - The gating mechanism. It evaluates alert episodes from the rule on a continuous schedule and invokes the workflow when the episode clears the policy's match conditions and frequency settings. When the agent creates an action policy alongside a specific rule, the policy is automatically scoped to that rule as a per-rule policy. + +Both objects are proposed as inline attachments and must be explicitly saved before they take effect. + +### Save order [save-order-ai-agent] + +The three objects have a dependency chain that determines the order in which they must be saved: + +1. **Rule** - The action policy references the rule by ID. The ID is not available until the rule is persisted. +2. **Workflow** - The action policy references the workflow as a destination. The reference must resolve to a persisted workflow. +3. **Action policy** - Can only be saved after both its rule and workflow dependencies exist. + +This order is enforced in the UI. The action policy save control remains inactive until both dependencies are met. + +## Related pages + +- [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) - How the {{agent-builder}} platform works, including agents, skills, and tools. + + + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md index e955317ed5..76f35a034e 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md @@ -10,7 +10,7 @@ description: "Field reference for .rule-events documents in Kibana's experimenta # Rule event and field reference in the {{alerting-v2-system}} [rule-reference] -This page is a field reference for `.rule-events` documents written by the {{alerting-v2-system}}. For rule configuration settings, refer to [Configure a rule](configure-a-rule.md). +This page is a field reference for `.rule-events` documents written by the {{alerting-v2-system}}. For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md index 216c6c4898..4adc9afdfe 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md @@ -1,5 +1,5 @@ --- -navigation_title: Use the rule builder +navigation_title: Create rules using the rule builder applies_to: stack: experimental 9.5+ serverless: experimental @@ -8,10 +8,12 @@ products: description: "Create Threshold Alert rules in Kibana's experimental alerting system using a guided form that generates ES|QL automatically." --- -# Use the rule builder in the {{alerting-v2-system}} [use-rule-builder] +# Create a rule using the rule builder in the {{alerting-v2-system}} [use-rule-builder] The rule builder provides a guided form for creating rules without writing {{esql}} by hand. The builder generates the {{esql}} query automatically from structured inputs for the data source, aggregation, filters, and alert conditions. +For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). + ## Threshold Alert [use-threshold-alert-builder] Threshold Alert is the only rule type available in the rule builder. Use it to monitor one or more metrics and alert when they cross a threshold, with multi-condition support and custom aggregations. diff --git a/explore-analyze/toc.yml b/explore-analyze/toc.yml index 50531ec8bd..19bd6e6a02 100644 --- a/explore-analyze/toc.yml +++ b/explore-analyze/toc.yml @@ -389,7 +389,7 @@ toc: - file: alerting/kibana-alerting-experimental/rules/create-esql-rule.md children: - file: alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md - - file: alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md + - file: alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md - file: alerting/kibana-alerting-experimental/rules/use-rule-builder.md - file: alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md - file: alerting/kibana-alerting-experimental/rules/configure-a-rule.md From 343c2a3e328804351ac8b1eb683160f3fd852a1e Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 1 Jul 2026 18:23:40 -0400 Subject: [PATCH 09/23] remove old file --- .../rules/create-rule-ai-agent.md | 62 ------------------- 1 file changed, 62 deletions(-) delete mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md deleted file mode 100644 index 6951dd17ac..0000000000 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-ai-agent.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -navigation_title: Create rules and action policies with Agent Builder -applies_to: - stack: experimental 9.5+ - serverless: experimental -products: - - id: kibana -description: "How {{agent-builder}} creates rules and action policies in the experimental alerting system using the rule management skill, what the agent produces, and the save-order dependency." ---- - -# Create rules and action policies with {{agent-builder}} [create-rules-action-policies-ai-agent] - -Rule and action policy authoring in {{agent-builder}} is part of the {{alerting-v2-system}} in {{kib}}. The {{alerting-v2-system}} registers rules and action policies as attachment types in {{agent-builder}}, so an agent equipped with the rule management skill can propose, create, and configure them through natural language conversation. - -Instead of filling out the rule form manually, you describe what you want to monitor and the agent uses its rule management skill and tools to resolve the data source and build a fully configured rule proposal for you. - -## How rule proposals work [ai-agent-rule-proposal] - -The rule management skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of ES\|QL query patterns, threshold configuration, grouping, and the alerting v2 data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. - -The proposal appears as an inline attachment in the conversation, summarizing the rule name, type, schedule, and tags. Opening the attachment shows the full configuration across three views: - -- **Conditions** - The ES\|QL query, thresholds, grouping criteria, and schedule the agent constructed. -- **Query preview** - The results of running the proposed ES\|QL query against live data, so you can evaluate whether the rule would produce meaningful signal before committing to it. -- **Runbook** - A free-text runbook field associated with the rule, which the agent can populate from context in the conversation. - -The agent can also search for and attach an existing rule to the conversation using the same inline attachment, opening the same view for inspection or revision. - -The agent does not persist the rule automatically. Saving is an explicit action that signals the configuration is ready. Until the rule is saved, the proposal exists only in the conversation and is not evaluated against data. - -:::{note} -Signal rules do not support notifications. Alert episodes, and therefore action policies, only apply to rules running in Alert mode. If you ask the agent to set up notifications for a signal rule, the rule management skill explains the limitation and offers to either convert the rule to Alert mode or create a separate alert rule. -::: - -## Example prompts [ai-agent-sample-prompts] - -Use these prompts as a starting point, then adjust them to your data and thresholds: - -- Create an error threshold rule on the checkout service data. Alert when there are more than 3 HTTP 5xx errors in the past 5 minutes, grouped by URL path. -- Monitor average CPU usage across all hosts. Alert when any host exceeds 90% for more than 10 minutes. -- Alert when log volume from the payments service drops below 100 events in a 5-minute window. This likely means data has stopped flowing. -- Set up a rule that tracks error rate by service. Alert at medium severity when the rate exceeds 1%, and critical when it exceeds 5%. - - -## How notification setup works [ai-agent-notification-setup] - -After a rule is saved, you can ask the agent to configure notifications. The rule management skill handles this by creating two objects: - -- A **workflow** - The delivery mechanism. It defines what happens when the {{alerting-v2-system}} determines that a notification should be sent: posting to Slack, emailing a team, triggering PagerDuty, and so on. -- An **action policy** - The gating mechanism. It evaluates alert episodes from the rule on a continuous schedule and invokes the workflow when the episode clears the policy's match conditions and frequency settings. When the agent creates an action policy alongside a specific rule, the policy is automatically scoped to that rule as a per-rule policy. - -Both objects are proposed as inline attachments and must be explicitly saved before they take effect. - -### Save order [save-order-ai-agent] - -The three objects have a dependency chain that determines the order in which they must be saved: - -1. **Rule** - The action policy references the rule by ID. The ID is not available until the rule is persisted. -2. **Workflow** - The action policy references the workflow as a destination. The reference must resolve to a persisted workflow. -3. **Action policy** - Can only be saved after both its rule and workflow dependencies exist. - -This order is enforced in the UI. The action policy save control remains inactive until both dependencies are met. \ No newline at end of file From e22dc77ab2d92b3325bb2003ea0aafdbdc16c5cb Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 1 Jul 2026 22:31:56 -0400 Subject: [PATCH 10/23] fix front matter descriptions --- .../kibana-alerting-experimental/rules.md | 6 ++-- .../rules/configure-a-rule.md | 7 ++--- .../rules/configure-no-data-handling.md | 6 ++-- .../rules/configure-rule-grouping.md | 6 ++-- .../rules/configure-rule-mode.md | 27 +++++++---------- .../rules/configure-rule-query.md | 30 ++++++++----------- .../rules/configure-rule-schedule.md | 30 ++++++++----------- .../rules/configure-rule-severity.md | 27 +++++------------ .../rules/configure-rule-tags.md | 8 ++--- .../rules/configure-rule-thresholds.md | 6 ++-- ...ate-rules-action-policies-agent-builder.md | 2 +- 11 files changed, 61 insertions(+), 94 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules.md index c49647e39b..6884b64de6 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules.md @@ -5,7 +5,7 @@ applies_to: serverless: experimental products: - id: kibana -description: "Rules in Kibana's experimental alerting system define what to detect using ES|QL. Evaluation runs on a schedule; alerts, action policies, and notifications flow from rule detections." +description: "Rules in Kibana's experimental alerting system define what to detect using ES|QL. Evaluation runs on a schedule and alerts, action policies, and notifications flow from rule detections." --- # Rules in the {{alerting-v2-system}} @@ -16,9 +16,9 @@ This page explains what rules do, what they don't control, and how to choose a c ## What rules do [detection-and-notification] -On each run, a rule executes an {{esql}} query against your data. If the query finds a match, it writes a rule event (`rule_event`), a point-in-time record that the condition was met. In Alert mode, it also maintains an _alert episode_ for each matched series, tracking state from first breach through recovery. +On each run, a rule executes an {{esql}} query against your data. Matches are recorded as rule events (`rule_event`), and handled according to the rule's mode, which can be Signal mode or Alert mode. -When creating a rule, choose Signal mode to record and query results without alerting anyone, or Alert mode when you want to track issues and route notifications. +In Signal mode, each matching row is stored as a signal document with no alert lifecycle or notifications. In Alert mode, the rule creates and tracks an alert episode for each match. Episodes move through lifecycle states, appear on the Alerts UI, and can trigger notifications through action policies. ## What rules don't do diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md index 90d3e84b6b..3dc876a016 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -5,15 +5,12 @@ applies_to: serverless: experimental products: - id: kibana -description: "Configure rules in the experimental alerting system: mode, ES|QL query, grouping, schedule, activation and recovery thresholds, no-data handling, tags, and evaluation." +description: "Overview of all configurable rule settings in the experimental alerting system. Required settings are mode, ES|QL query, and schedule. Optional settings include severity, grouping, activation and recovery thresholds, no-data handling, and tags." --- # Configure a rule in the {{alerting-v2-system}} [rule-settings] -Rules in the {{alerting-v2-system}} have three required settings and several optional ones. Start with the required settings in order: first, select the rule mode (which determines which optional settings are relevant), then define the {{esql}} query, then specify the rule execution schedule. Add optional settings once the detection logic is validated. - +Rules in the {{alerting-v2-system}} have three required settings and several optional ones. Start with the required settings in order. Only add optional settings once the detection logic is validated. The table below links to a dedicated page for each setting with field descriptions, accepted values, and guidance on when to configure it. | Setting | Description | Required | | --- | --- | --- | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md index 9f930331cd..e2d3231928 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md @@ -5,13 +5,15 @@ applies_to: serverless: experimental products: - id: kibana -description: "Configure no-data handling for rules in Kibana's experimental alerting system to control what happens when a query returns no results." +description: "How to configure the no-data strategy for rules in the experimental alerting system. Controls whether an empty query result emits a no-data event, holds the last known alert state, triggers recovery, or is ignored." --- # No-data handling in the {{alerting-v2-system}} [no-data-handling] No-data handling is an optional setting for rules in the {{alerting-v2-system}}. Use `no_data_strategy` to control what the rule records when the base query returns no results. Setting this correctly prevents false recoveries and misleading `no_data` events when data sources stop reporting. +## No-data strategy options [no-data-strategy-options] + The `no_data_strategy` field accepts the following values. | Value | Description | @@ -22,7 +24,7 @@ The `no_data_strategy` field accepts the following values. | `none` | Turn off no-data detection | :::{note} -`no_data_strategy` does not detect when a specific host or data source stops reporting while others continue. Refer to [No-data detection](esql-no-data-detection.md) for an {{esql}} pattern that surfaces silent sources as alert rows. +`no_data_strategy` only applies when the base query returns **no rows at all**. If one host or data source goes silent while others continue reporting, the query still returns results for the active sources and `no_data_strategy` does not trigger. Refer to [No-data detection](esql-no-data-detection.md) for an {{esql}} pattern that surfaces individual silent sources as alert rows. ::: ## When to configure no-data handling [no-data-when-to-use] diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md index a20279f1c1..4d90afb4a8 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md @@ -17,10 +17,6 @@ Rule grouping is an optional setting in the {{alerting-v2-system}} that lets a s 2. Does "lifecycle" mean the standard inactive → pending → active → recovering episode states? If so, rewrite as: "In Alert mode, each group becomes its own alert episode with an independent lifecycle. One group can be active while another has recovered, and notifications apply per episode, not across all groups combined." --> -:::{note} -Rule grouping controls how alert series are created. Notification grouping (configured on an action policy) controls how those alert episodes are batched into messages. These are separate settings. -::: - ## When to configure grouping [grouping-when-to-use] Configure grouping when: @@ -34,6 +30,8 @@ Skip grouping when: * Your query does not use a `BY` clause. Grouping requires `BY` columns in the query output to be meaningful. * You intentionally want a single alert series for the rule regardless of how many subjects match. An example is a rule that fires when any host in a cluster is down and the individual host identity doesn't matter for the notification. +Rule grouping controls how alert series are created. Notification grouping, configured on an action policy, controls how those alert episodes are batched into messages. These are separate settings. + ## Configure grouping fields [grouping-fields-config] The {{alerting-v2-system}} does not automatically infer grouping from your {{esql}} query. When your query uses `BY` to produce one row per group, the system still treats all rows as a single series unless you explicitly declare which fields define series identity in the grouping configuration. The fields you declare in `grouping.fields` are what the system uses to separate rows into independent alert series and track each one through its own lifecycle. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md index aeaf45067e..7d5aebfdd0 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md @@ -5,29 +5,24 @@ applies_to: serverless: experimental products: - id: kibana -description: "Choose between Signal and Alert mode for rules in Kibana's experimental alerting system." +description: "How rule mode determines whether detections produce signal documents or tracked alert episodes in the experimental alerting system, and when to use each." --- # Rule mode in the {{alerting-v2-system}} [rule-mode] -Rule mode is a required setting for rules in the {{alerting-v2-system}}. Rule mode is set by the rule creation method and some creation paths only support one mode. Refer to [Create a rule](create-a-rule.md) for available options. +Rule mode is a required setting for rules in the {{alerting-v2-system}}. It determines what the rule produces when the detection query finds a match. Rule mode is set by the rule creation method and some [creation paths](create-a-rule.md) only support one mode. -:::{tip} -Start with Signal mode to validate your detection logic without generating noise. Switch to Alert mode once the rule is tuned and you want to track episodes or route notifications. -::: +| Mode | Behavior | +| --- | --- | +| Signal | Records each matching row as a signal document. No alert episodes, no notifications. | +| Alert | Creates an alert episode for each matching row. Episodes are tracked through lifecycle states, appear on the Alerts UI, and can be routed to notifications by action policies. | -| Mode | Behavior | Best for | -| --- | --- | --- | -| Signal | Records each matching row as a signal document. No alert episodes, no notifications. | Testing a new query, building detection history, or observing matches without notifying anyone. | -| Alert | Creates an alert episode for each matching row. Episodes are tracked through lifecycle states, appear on the **Alerts** page, and can be routed to notifications by action policies. | Production rules where breaches should be tracked, escalated, or routed to a notification channel. | - -## When to use each mode [rule-mode-when-to-use] +## When to use each rule mode [rule-mode-when-to-use] Signal mode is the right fit when: * You are writing a new detection query and want to verify it produces the expected matches before notifying anyone. * You need to build detection history in `.rule-events` without generating alert noise or triggering notifications. -* You want to observe matches in Discover without opening tracked episodes on the **Alerts** page. Signal mode is **not** the right fit when: @@ -36,9 +31,9 @@ Signal mode is **not** the right fit when: Alert mode is the right fit when: -* The rule is production-ready and breaches should open tracked episodes with lifecycle state. -* You need the rule to appear on the **Alerts** page for triage, acknowledgment, or escalation. -* You want to attach action policies to route notifications when episodes open, escalate, or recover. +* The rule is production-ready and each breach should be tracked as a distinct alert episode that opens, can escalate, and closes when the condition clears. +* Alert episodes from the rule should be available for be triage, acknowledgement, or escalatation. +* You want to attach action policies to route notifications when alert episodes open, escalate, or recover. Alert mode is **not** the right fit when: @@ -52,4 +47,4 @@ You're writing a new detection query and want to verify it produces the results ### Route critical episodes to an on-call workflow -You have a checkout service error rate rule and want on-call engineers notified when it fires. Create the rule in Alert mode so each breach opens a tracked episode that action policies can route to a notification channel. The rule's episodes appear on the **Alerts** page and are visible to any action policy whose KQL matcher matches the episode fields. +You have a checkout service error rate rule and want on-call engineers notified when it fires. Create the rule in Alert mode so each breach opens a tracked episode that action policies can route to a notification channel. The rule's episodes appear on the Alerts UI and are visible to any action policy whose KQL matcher matches the episode fields. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md index 3ccff1a84f..c466920586 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md @@ -5,29 +5,13 @@ applies_to: serverless: experimental products: - id: kibana -description: "Configure the ES|QL query and query parameters for rules in Kibana's experimental alerting system." +description: "How to structure the ES|QL detection query for a rule in the experimental alerting system. Covers the base query, the optional alert condition that gates which rows become breaches, and dynamic parameters for time bounds and configurable thresholds." --- # {{esql}} query in the {{alerting-v2-system}} [esql-query-rule] Every rule in the {{alerting-v2-system}} uses an {{esql}} query to define what to evaluate. The query consists of a base query that shapes and filters the data and an optional alert condition that determines which rows become alert events. For more advanced use cases, the query also supports [dynamic values](#dynamic-query-values) for filtering by the evaluation window or setting configurable thresholds through the rule form. -:::{tip} -Use the query preview option to test your query against live data before saving the rule. This lets you verify the detection logic produces the results you expect without committing to a schedule or opening alert episodes. -::: - -## When to add an alert condition [query-when-to-use] - -Add an alert condition when: - -* Your base query returns aggregate results (for example, counts or averages per group) and you only want to alert when a value crosses a specific threshold. Without an alert condition, every row returned by the base query is treated as a breach. -* You want to keep filtering logic out of the base query and express the threshold separately for clarity. - -Skip the alert condition when: - -* Every row returned by the base query should be treated as a breach. This applies when the query filters directly for specific error events where any match warrants attention. -* All filtering can be expressed cleanly in a single `WHERE` clause without a two-stage query. - ## Base query [query-base] The base query is the main {{esql}} expression. Use `FROM` to point the rule at the indices or data streams to read. Shape results with `STATS`, `WHERE`, and `EVAL`, and control which fields are stored with `KEEP`. The base query runs on every evaluation, even when no match occurs, which is what enables no-data detection and recovery. The [{{esql}} reference](elasticsearch://reference/query-languages/esql.md) covers all available commands and processing functions. @@ -60,6 +44,18 @@ FROM logs-* The `KEEP` command controls which fields appear on each stored alert event. Only the fields in `KEEP` are available for action policy matchers, grouping keys, and triage. +## When to add an alert condition [query-when-to-use] + +Add an alert condition when: + +* Your base query returns aggregate results (for example, counts or averages per group) and you only want to alert when a value crosses a specific threshold. Without an alert condition, every row returned by the base query is treated as a breach. +* You want to keep filtering logic out of the base query and express the threshold separately for clarity. + +Skip the alert condition when: + +* Every row returned by the base query should be treated as a breach. This applies when the query filters directly for specific error events where any match warrants attention. +* All filtering can be expressed cleanly in a single `WHERE` clause without a two-stage query. + ## Use dynamic values in your rule query [dynamic-query-values] {{esql}} rule queries support two kinds of parameters that make queries more dynamic. The executor injects time bounds automatically, and you define form variables when creating a rule. You don't need either to write a working rule, but they're useful for scoping queries precisely to the evaluation window or making thresholds configurable without editing the query. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md index 7051716080..d45abee80c 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md @@ -5,29 +5,15 @@ applies_to: serverless: experimental products: - id: kibana -description: "Configure the execution schedule and lookback window for rules in Kibana's experimental alerting system." +description: "How the execution interval and lookback window control when a rule evaluates and how much data it covers each time in the experimental alerting system." --- # Schedule and lookback in the {{alerting-v2-system}} [schedule-lookback] -Schedule and lookback are required settings for rules in the {{alerting-v2-system}}. They control how often a rule runs and how far back it looks when evaluating data. +Schedule and lookback are required settings for rules in the {{alerting-v2-system}}. They control how often a rule runs and how far back it looks when evaluating data. This page describes both fields, lists the accepted values and bounds, and includes guidance on choosing appropriate values for different monitoring scenarios. Both fields accept duration strings such as `30s`, `5m`, `2h`, or `7d`. Refer to [Duration format](yaml-rule-schema-reference.md#duration-format) for supported units. -## Execution interval - -The execution interval (`schedule.every`) determines how frequently the rule evaluates. The minimum is `5s` and the maximum is `365d`. Values outside that range are rejected. - -## Lookback window - -The lookback window (`schedule.lookback`) determines the time range that the {{esql}} query covers. The minimum is `5s` and the maximum is `365d`. - -If the lookback is shorter than the execution interval, evaluations can miss data between runs. Use a lookback at least as long as the execution interval unless you have a deliberate reason not to. - -:::{tip} -When setting up a new rule, start with a longer lookback to verify the query covers the data you expect, then tighten it once the rule is stable. -::: - ## When to use a short or long interval and lookback [schedule-when-to-use] Use a short execution interval (seconds to a few minutes) when: @@ -53,7 +39,17 @@ Use a longer lookback window when: Avoid setting the lookback shorter than the execution interval. If the lookback doesn't cover the full gap between evaluations, events that arrive between runs can be missed. -## Examples +## Execution interval [schedule-execution-interval] + +The execution interval (`schedule.every`) determines how frequently the rule evaluates. The minimum is `5s` and the maximum is `365d`. Values outside that range are rejected. + +## Lookback window [schedule-lookback-window] + +The lookback window (`schedule.lookback`) determines the time range that the {{esql}} query covers. The minimum is `5s` and the maximum is `365d`. + +If the lookback is shorter than the execution interval, evaluations can miss data between runs. Use a lookback at least as long as the execution interval unless you have a deliberate reason not to. + +## Examples [schedule-examples] ### High-frequency security rule diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md index 2d535251ce..59b6b47524 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md @@ -12,10 +12,6 @@ description: "Assign severity levels to alert episodes in Kibana's experimental Severity is an optional setting for rules in the {{alerting-v2-system}}. To set it, include a column named `severity` in your {{esql}} query output and add it to your `KEEP` list. The framework reads that column after each evaluation and maps it to one of five fixed levels. -:::{tip} -Add severity to your rule when you need to route or filter alert episodes by urgency, for example, to send critical episodes to an on-call channel and low episodes to a review queue. -::: - | Value | Description | Urgency | | --- | --- | --- | | `info` | Informational event worth recording. | No action required. | @@ -29,7 +25,7 @@ Add severity to your rule when you need to route or filter alert episodes by urg Configure severity when: * You want to route different urgency levels to different notification channels, for example, send `critical` episodes to an on-call channel and `low` episodes to a review queue. -* You want to filter the **Alerts** page by urgency to help triage during incidents. +* You want to filter the Alerts UI by urgency to help triage during incidents. * The rule's detection logic can meaningfully distinguish between urgency levels through a computed metric, such as burn rate, error count, or latency percentile. Skip severity when: @@ -37,23 +33,14 @@ Skip severity when: * All breaches from the rule are equally urgent. A fixed label in the rule's tags is simpler and doesn't require query changes. * The underlying data doesn't produce a reliable metric to grade urgency. Severity that's frequently wrong generates more noise than routing by severity resolves. -## How the {{alerting-v2-system}} maps severity values - -The {{alerting-v2-system}} maps the `severity` column to an internal level after each evaluation using the following rules: - -- Matching is case-insensitive. -- Values that don't match one of the five levels are silently ignored. The alert episode is still created, but `severity` isn't set. -- Severity is only set on `breached` events. `recovered` and `no_data` events don't carry a severity value. - -## Stored fields - -When severity is set, the {{alerting-v2-system}} stores the following field on the alert episode, available to action policy matchers: +## Severity behavior and usage [severity-behavior] -| Field | Description | -| --- | --- | -| `severity` | The severity value from the most recent breached event. | +Keep the following in mind when configuring severity. -Refer to [Rule event and field reference](rule-event-field-reference.md#episode-fields) for more information about this field. +- **Matching is case-insensitive** - `critical`, `Critical`, and `CRITICAL` are all treated the same. You can use any casing in your `EVAL` expression. +- **Unrecognized values are silently ignored** - If the `severity` column contains a value that doesn't match one of the five levels, the alert episode is still created but `severity` is not set. If severity isn't appearing as expected, check the exact string your query is producing. +- **Severity only applies to breached events** - `recovered` and `no_data` events don't carry a severity value. Action policy matchers that filter by severity only match open episodes. +- **The `severity` field is available in action policy matchers** - Once set, the value is stored on the alert episode and can be used to route episodes by urgency — for example, sending `critical` episodes to an on-call channel while `low` episodes go to a review queue. Refer to [Rule event and field reference](rule-event-field-reference.md#episode-fields) for the full field reference. ## Examples diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md index f9acd71234..ddd4987215 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md @@ -15,16 +15,12 @@ Tags and runbooks are optional artifacts for Alert-mode rules in the {{alerting- - **Tags**: Free-form labels for filtering and organization. Maximum 20 tags per rule. Each tag can be up to 128 characters. - **Runbooks**: An investigation guide stored with the rule so responders have context when alerts are generated. -:::{tip} -Tags are inherited by alert episodes, so they're available for filtering in the alerts view and as KQL matchers in action policies. Use them to organize rules by team, environment, or severity tier. -::: - ## When to configure tags and runbooks [tags-when-to-use] Configure tags when: -* You want to filter the **Alerts** page by team, environment, or severity tier without writing ad hoc KQL queries each time. -* You are using action policies and want to match episodes by ownership or category rather than by rule name. +* You want to filter the Alerts UI by team, environment, or severity tier without writing ad hoc KQL queries each time. +* You are using action policies and want to match episodes by ownership or category rather than by rule name. Tags are inherited by alert episodes, so any tag you add to a rule is available as a KQL matcher in action policies. * You manage many rules and need a consistent labeling scheme to track which team owns which alerts. Configure a runbook when: diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md index 5f022d0f78..6ffde95e34 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md @@ -51,6 +51,8 @@ You can combine Breaches and Duration. For example, require the threshold to be Recovery thresholds control when an active alert episode transitions back to inactive. The same delay modes available for activation apply. You can require a set number of consecutive recoveries, a minimum recovery duration, or both. +### Recovery fields + | Field | Type | Description | | --- | --- | --- | | `recovering_count` | Positive integer | Number of consecutive non-breaching evaluations required before the alert episode closes. | @@ -60,9 +62,7 @@ Recovery thresholds control when an active alert episode transitions back to ina Time frame fields accept the same `5s` to `365d` bounds as activation time frames. Refer to [Duration format](yaml-rule-schema-reference.md#duration-format) for supported units. :::{note} -The `recovery_strategy` field controls how recovery is detected, separately from how many recoveries are required. When creating a rule through the UI, `recovery_strategy` defaults to `no_breach`, which recovers the alert episode when its active group no longer appears in the breach batch. - -When creating a rule through Agent Builder, you can omit `recovery_strategy` entirely to suppress recovery events and keep alert episodes active until closed manually. For the full field reference, go to [YAML rule schema reference](yaml-rule-schema-reference.md#recovery-strategy). +`recovery_strategy` is a separate field that controls how recovery is detected, independent of how many recoveries these thresholds require. Refer to [YAML rule schema reference](yaml-rule-schema-reference.md#recovery-strategy) for field details and default values. ::: ## Examples diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md index 9885d507ef..2fb347ea69 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md @@ -5,7 +5,7 @@ applies_to: serverless: experimental products: - id: kibana -description: "How {{agent-builder}} creates rules and action policies in the experimental alerting system using the rule management skill, what the agent produces, and the save-order dependency." +description: "How Agent Builder creates rules and action policies in the experimental alerting system using the rule management skill, what the agent produces, and the save-order dependency." --- # Create rules and action policies with {{agent-builder}} [create-rules-action-policies-ai-agent] From 66c8bc1ca0d58f00b5a930473098738ba23c16f0 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Mon, 6 Jul 2026 11:53:25 -0400 Subject: [PATCH 11/23] bailey's feedback --- .../kibana-alerting-experimental/rules/create-esql-rule.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md index 489561ee00..a87adb1d2b 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md @@ -13,7 +13,7 @@ description: "Write ES|QL detection queries for rules in Kibana's experimental a The {{esql}} rule path lets you write the detection query directly. There are two ways to define the rule: - **Rule form** - Fill in the step-by-step form with a live preview of results. -- **YAML mode** - Switch to YAML and edit the raw rule definition. You can switch between form and YAML at any point; edits are preserved. +- **YAML mode** - Edit the raw rule definition. You can switch between form and YAML at any time, unless the YAML can't be translated to a valid form state, in which case you must stay in YAML. For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). For a list of supported YAML fields, refer to [YAML rule schema reference](yaml-rule-schema-reference.md). @@ -21,6 +21,10 @@ For details on configurable rule settings and guidance on how to configure them, The query sandbox lets you run your {{esql}} query against current data and preview the results before applying them to the rule form. Use the time field selector and date picker to control the time range, then select **Search** (or press ⌘↵) to execute. When the results look correct, select **Apply changes** to populate the form. +:::{note} +In the query sandbox, the time field selector and date picker control the query results only. They do not set the rule's schedule or lookback period. +::: + Use the sandbox to: - **Confirm grouping** - Check that your `BY` clause produces the series you intend, for example, one distinct series per host or per service, not a single undifferentiated result. From c88f8b37e5cbc8194364000e4afa8286eb7ec28b Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Mon, 6 Jul 2026 14:40:26 -0400 Subject: [PATCH 12/23] Apply suggestions from code review Co-authored-by: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> --- .../kibana-alerting-experimental/rules/configure-a-rule.md | 2 +- .../kibana-alerting-experimental/rules/configure-rule-mode.md | 2 +- .../kibana-alerting-experimental/rules/configure-rule-tags.md | 2 +- .../rules/configure-rule-thresholds.md | 2 +- .../rules/create-rule-from-discover.md | 2 +- .../kibana-alerting-experimental/rules/esql-first-rule-query.md | 2 +- .../rules/esql-no-data-detection.md | 2 +- .../rules/rule-event-field-reference.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md index 3dc876a016..087f7472c2 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -10,7 +10,7 @@ description: "Overview of all configurable rule settings in the experimental ale # Configure a rule in the {{alerting-v2-system}} [rule-settings] -Rules in the {{alerting-v2-system}} have three required settings and several optional ones. Start with the required settings in order. Only add optional settings once the detection logic is validated. The table below links to a dedicated page for each setting with field descriptions, accepted values, and guidance on when to configure it. +Rules in the {{alerting-v2-system}} have three required settings and several optional ones. Start with the required settings in order. Only add optional settings once the detection logic is validated. The following table links to a dedicated page for each setting with field descriptions, accepted values, and guidance on when to configure it. | Setting | Description | Required | | --- | --- | --- | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md index 7d5aebfdd0..fdde673b34 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md @@ -32,7 +32,7 @@ Signal mode is **not** the right fit when: Alert mode is the right fit when: * The rule is production-ready and each breach should be tracked as a distinct alert episode that opens, can escalate, and closes when the condition clears. -* Alert episodes from the rule should be available for be triage, acknowledgement, or escalatation. +* Alert episodes from the rule should be available for be triage, acknowledgment, or escalation. * You want to attach action policies to route notifications when alert episodes open, escalate, or recover. Alert mode is **not** the right fit when: diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md index ddd4987215..2b1e531666 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md @@ -25,7 +25,7 @@ Configure tags when: Configure a runbook when: -* Responders who aren't familiar with the service may need to triage the alert. A runbook surfaces triage steps directly alongside the alert without requiring a separate search. +* Responders who aren't familiar with the service might need to triage the alert. A runbook surfaces triage steps directly alongside the alert without requiring a separate search. * The alert requires a consistent response process that you want encoded and version-controlled alongside the rule. Skip tags and runbooks when: diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md index 6ffde95e34..11834e554a 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md @@ -45,7 +45,7 @@ Use the following fields to configure the Breaches and Duration modes. Timeframe | `pending_timeframe` | Duration string | How long the condition must remain breached before the alert episode opens. | | `pending_operator` | `AND` or `OR` | When both `pending_count` and `pending_timeframe` are set, controls whether both must be satisfied (`AND`) or either one is enough (`OR`). | -You can combine Breaches and Duration. For example, require the threshold to be breached five times in a row _and_ persist for at least two minutes before an alert episode opens. Set `pending_operator` to `AND` to require both, or `OR` if either is enough. +You can combine Breaches and Duration. For example, require the threshold to be breached five times in a row _and_ persist for at least two minutes before an alert episode opens. To require both, set `pending_operator` to `AND` or `OR` if either is enough. ## Recovery thresholds diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md index 1eaf4b2f40..842d739c84 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md @@ -23,7 +23,7 @@ Two paths lead to Discover-based rule creation: When you trigger rule creation from Discover, your {{esql}} query pre-fills the **Create ES|QL rule** form. The rule creation form also shows a preview panel that reflects how your query partitions results into alert series. If your query uses a `BY` clause, the preview shows the series that would be evaluated on each run, letting you verify grouping logic against live data before committing to a schedule. -The rule creation flyout supports both a step-by-step form and a YAML editing mode. You can switch between them at any point; edits in YAML mode are preserved when you return to the form view. The YAML editor includes {{esql}} autocomplete in the query field. +The rule creation flyout supports both a step-by-step form and a YAML editing mode. You can switch between them at any point. Edits in YAML mode are preserved when you return to the form view. The YAML editor includes {{esql}} autocomplete in the query field. For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md index 0d7f3fa700..d7129b53ad 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md @@ -14,7 +14,7 @@ If you're new to {{esql}} or to writing rules, this page shows the simplest quer ## The simplest rule query -This query returns one row for every log entry at `ERROR` level in the lookback window. No aggregation happens; each matching event becomes its own alert event. Use this pattern when any single occurrence of a condition is worth alerting on: any critical error log, any failed authentication attempt, any payment rejection. +This query returns one row for every log entry at `ERROR` level in the lookback window. No aggregation happens. Each matching event becomes its own alert event. Use this pattern when any single occurrence of a condition is worth alerting on: any critical error log, any failed authentication attempt, any payment rejection. ```esql FROM logs-* diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md index 7ff031fae9..e74676cb8f 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md @@ -25,7 +25,7 @@ FROM metrics-* | KEEP host.name, last_seen // Each returned row is a silent host ``` -Every row returned is a host that has gone silent. The query result itself drives the alert; no separate alert condition is needed. +Every row returned is a host that has gone silent. The query result itself drives the alert. A separate alert condition isn't needed. :::{note} This pattern detects specific silent sources. For controlling what the rule records when the entire base query returns zero rows, for example when an index is completely empty, refer to [No-data handling](configure-no-data-handling.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md index 76f35a034e..a4801c6fbf 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md @@ -29,7 +29,7 @@ Each time a rule evaluates, {{kib}} writes one document per matched series to `. Both kinds share the base fields below. Only `alert` documents add the [Episode fields](#episode-fields) listed further down. :::{note} -`.rule-events` is a data stream, so it is append-only. A new document is written on every rule evaluation; existing documents are never updated. Each document is a snapshot of that moment: the `episode.status` field records the lifecycle stage the episode was in at that evaluation. To view the full history of an episode, query all documents that share the same `episode.id`. +`.rule-events` is a data stream, so it is append-only. A new document is written on every rule evaluation. Existing documents are never updated. Each document is a snapshot of that moment: the `episode.status` field records the lifecycle stage the episode was in at that evaluation. To view the full history of an episode, query all documents that share the same `episode.id`. From 9aea193631ef16733f83eef527a81ddda9aeae47 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Tue, 7 Jul 2026 00:14:09 -0400 Subject: [PATCH 13/23] [Alerting V2][Serverless & 9.5][M2] Add requirements section and execution history docs to rules pages (#7247) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Adds two missing documentation gaps to the experimental alerting rules section, addressing issues [#7227](https://github.com/elastic/docs-content/issues/7227) and [#7240](https://github.com/elastic/docs-content/issues/7240). Both pages are in the in-progress PR [#6523](https://github.com/elastic/docs-content/pull/6523). --- ## Content changes ### `rules/create-rules-action-policies-agent-builder.md` Addresses [#7227](https://github.com/elastic/docs-content/issues/7227): Added a **Requirements** section before "Propose and save a rule" covering the three conditions that must be met for the "Create with AI Agent" entry points to appear in the {{alerting-v2-system}} UI: - **The required subscription**: Agent Builder requires the appropriate Stack subscription or Serverless project feature tier. Without it, the entry points are hidden. - **The `agentBuilder:experimentalFeatures` advanced setting turned on**: The alerting v2-specific UI gate, enabled in Advanced Settings. Added following the Kibana PR [#274165](https://github.com/elastic/kibana/pull/274165) which introduced this as a hard gate on all four "Create with AI Agent" entry points (rules list split-button, empty state, and both create-rule flyouts). - **The required privileges**: A table covering the four privilege requirements — `Agent Builder: Read` to access the agent, `Rules: All` to save a rule, `Action Policies: All` to save an action policy, and `Workflows: Read` or `Workflows: All` to select or create a workflow destination. A cross-reference link to `configure-access.md` is included but commented out pending PR [#6522](https://github.com/elastic/docs-content/pull/6522). Requirements section is modeled on the `create-your-first-rule.md` pattern from PR [#6522](https://github.com/elastic/docs-content/pull/6522). --- ### `rules/view-manage-rules.md` Addresses [#7240](https://github.com/elastic/docs-content/issues/7240): Added a **Monitor rule execution health** section documenting the Execution History page and its Rules tab, introduced in Kibana PR [#275066](https://github.com/elastic/kibana/pull/275066). - Describes the Execution History page as a cross-rule view for monitoring rule health at scale. - Documents the two-tab layout: **Rules** (default) and **Policies**. - Documents the **Rules** tab columns: Timestamp, Rule (links to rule summary flyout), Duration, Response, and Message. - Documents the server-side **Outcome** filter (All / Success / Failure) and the 10,000-record result cap. Updated the page description and opening paragraph to reflect the new coverage. ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes — Cursor + Claude - [ ] No --- ...ate-rules-action-policies-agent-builder.md | 19 ++++++++++++++++ .../rules/view-manage-rules.md | 22 +++++++++++++++++-- 2 files changed, 39 insertions(+), 2 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md index 2fb347ea69..8049f5e037 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md @@ -14,6 +14,25 @@ Rule and action policy authoring in {{agent-builder}} is part of the {{alerting- Instead of filling out the rule form manually, you describe what you want to monitor and the agent uses its rule management skill and tools to resolve the data source and build a fully configured rule proposal for you. +## Requirements [create-ai-agent-requirements] + +Before you start, make sure you have the following: + +- **The required subscription**: {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). Without it, the "Create with AI Agent" option is hidden in the {{alerting-v2-system}} UI. +- **The `agentBuilder:experimentalFeatures` advanced setting turned on**: Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`. +- **The required privileges**: Your [role](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) must include the following: + + | To... | Required privilege | + |---|---| + | Access and use {{agent-builder}} | **Agent Builder: Read** (under **Analytics**) | + | Save the rule | **Rules: All** (under **Alerting**) | + | Save the action policy | **Action Policies: All** (under **Alerting**) | + | Select or create the workflow destination | **Workflows: Read** to select an existing workflow; **Workflows: All** to create one (under **Analytics > Workflows**) | + + + ## Propose and save a rule [ai-agent-rule-proposal] To use this capability, open an agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the rule management skill configured. The rule management skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of ES\|QL query patterns, threshold configuration, grouping, and the alerting v2 data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md index fda179e400..a445cf8f00 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md @@ -5,12 +5,12 @@ applies_to: serverless: experimental products: - id: kibana -description: "Search, filter, sort, and bulk-manage rules from the rules list in Kibana's experimental alerting system. Inline editing and a summary flyout let you update settings without a full page reload." +description: "Search, filter, and bulk-manage rules in Kibana's experimental alerting system. Use inline editing, the rule summary flyout, and the Execution History page to manage rules and monitor rule health." --- # View and manage rules in the {{alerting-v2-system}} [manage-rules] -Rule management is part of the {{alerting-v2-system}} in {{kib}}. This page covers how to find and filter rules in the rules list, quick-edit settings without leaving the list, use the rule summary flyout, and navigate the rule details page including the alert activity timeline. +Rule management is part of the {{alerting-v2-system}} in {{kib}}. This page covers how to find and filter rules in the rules list, quick-edit settings without leaving the list, use the rule summary flyout, navigate the rule details page including the alert activity timeline, and monitor rule health at scale from the Execution History page. ## Find and filter rules [find-filter-rules] @@ -40,6 +40,24 @@ The rule details page is organized into tabs that let you review a rule's config Use **Edit** to modify the rule, or the actions menu to enable, disable, clone, or delete it. +## Monitor rule execution health [execution-history] + +The Execution History page shows a cross-rule view of rule execution history, giving you a paginated, filterable log of every rule run across all rules in the space. Use this page to spot patterns that aren't visible when looking at individual rules, for example, a cluster of failures at the same timestamp pointing to a shared dependency issue. + +The page has two tabs: **Rules** (default), which shows per-rule execution records, and **Policies**, which shows action policy dispatch records and outcomes. + +The **Rules** tab displays a table of rule execution records with the following columns: + +| Column | Description | +|---|---| +| **Timestamp** | When the rule execution ran. | +| **Rule** | The rule that ran. Selecting the rule name opens the rule summary flyout so you can inspect the rule without leaving the page. | +| **Duration** | How long the execution took. | +| **Response** | The outcome of the run: `success` or `failure`. | +| **Message** | An optional message included with the execution result, typically an error description for failed runs. | + +Use the **Outcome** filter to narrow results by execution outcome: **All**, **Success**, or **Failure**. Filtering is applied server-side. Results are capped at 10,000 records. + ## Disable or snooze a rule [disable-snooze-rule] Use **Disable** when you want the rule to stop running entirely until you re-enable it. This is different from snoozing, which suppresses notifications or quiets a series or policy without stopping rule evaluation. From 24fb4b709d0ff293e653f403b48b7b739846ccb2 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Tue, 7 Jul 2026 14:55:18 -0400 Subject: [PATCH 14/23] Add rule execution tab docs --- .../kibana-alerting-experimental/rules.md | 1 + .../rules/review-execution-history.md | 33 +++++++++++++++++++ .../rules/view-manage-rules.md | 23 ++++--------- explore-analyze/toc.yml | 1 + 4 files changed, 42 insertions(+), 16 deletions(-) create mode 100644 explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules.md index 6884b64de6..906ea11b35 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules.md @@ -31,4 +31,5 @@ This separation means you can build and test a rule without anyone getting paged - **[Create a rule](rules/create-a-rule.md):** Compare creation paths and choose the one that fits your workflow. - **[Configure a rule](rules/configure-a-rule.md):** Set the schedule, grouping, activation thresholds, recovery conditions, and no-data behavior. - **[View and manage rules](rules/view-manage-rules.md):** Enable, disable, clone, delete, and bulk-manage rules from the rules list. +- **[Review execution history](rules/review-execution-history.md):** Monitor rule and action policy execution outcomes across all rules in a space. - **[ES|QL query patterns](rules/esql-query-patterns.md):** Browse query patterns ordered by complexity, from a basic event filter to SLO burn rate and persistent breach detection. \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md new file mode 100644 index 0000000000..fd07eb0537 --- /dev/null +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md @@ -0,0 +1,33 @@ +--- +navigation_title: Review execution history +applies_to: + stack: experimental 9.5+ + serverless: experimental +products: + - id: kibana +description: "Use the Execution History page in Kibana's experimental alerting system to monitor rule and action policy execution outcomes across all rules in a space." +--- + +# Review execution history in the {{alerting-v2-system}} [review-execution-history] + +Execution history gives you a cross-rule, filterable log of every rule run across all rules in the space. Use it to spot patterns that aren't visible when looking at individual rules, for example, a cluster of failures at the same timestamp that points to a shared dependency issue. + + + +## Rule execution records [rule-execution-records] + +Rule execution records are displayed in a table with the following columns: + +| Column | Description | +|---|---| +| **Timestamp** | When the rule execution ran. | +| **Rule** | The rule that ran. Selecting the rule name opens a summary so you can inspect the rule without leaving the page. | +| **Duration** | How long the execution took. | +| **Response** | The outcome of the run: `success` or `failure`. | +| **Message** | An optional message included with the execution result, typically an error description for failed runs. | + +Use the outcome filter to view only successful or failed executions. Filtering is applied server-side. Results are limited to 10,000 records. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md index a445cf8f00..abb25b1b62 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md @@ -5,12 +5,12 @@ applies_to: serverless: experimental products: - id: kibana -description: "Search, filter, and bulk-manage rules in Kibana's experimental alerting system. Use inline editing, the rule summary flyout, and the Execution History page to manage rules and monitor rule health." +description: "Search, filter, and bulk-manage rules in Kibana's experimental alerting system. Use inline editing, the rule summary flyout, and the rule details page to manage rules." --- # View and manage rules in the {{alerting-v2-system}} [manage-rules] -Rule management is part of the {{alerting-v2-system}} in {{kib}}. This page covers how to find and filter rules in the rules list, quick-edit settings without leaving the list, use the rule summary flyout, navigate the rule details page including the alert activity timeline, and monitor rule health at scale from the Execution History page. +Rule management is part of the {{alerting-v2-system}} in {{kib}}. This page covers how to find and filter rules in the rules list, quick-edit settings without leaving the list, use the rule summary flyout, and navigate the rule details page including the alert activity timeline. ## Find and filter rules [find-filter-rules] @@ -40,23 +40,14 @@ The rule details page is organized into tabs that let you review a rule's config Use **Edit** to modify the rule, or the actions menu to enable, disable, clone, or delete it. -## Monitor rule execution health [execution-history] +## Review execution history [rule-execution-history] -The Execution History page shows a cross-rule view of rule execution history, giving you a paginated, filterable log of every rule run across all rules in the space. Use this page to spot patterns that aren't visible when looking at individual rules, for example, a cluster of failures at the same timestamp pointing to a shared dependency issue. +The **Execution history** page logs each rule run and each action policy dispatch across the space. It is organized into two tabs: -The page has two tabs: **Rules** (default), which shows per-rule execution records, and **Policies**, which shows action policy dispatch records and outcomes. +- **Rules** — One row per rule evaluation. Shows the timestamp, rule name, run duration, response status (success or failure), and a message. Use the **Response** filter to narrow results to successful or failed runs. Select a rule name to open its details page. +- **Policies** — One row per action policy dispatch event. Use this tab to audit whether policies are dispatching as expected. -The **Rules** tab displays a table of rule execution records with the following columns: - -| Column | Description | -|---|---| -| **Timestamp** | When the rule execution ran. | -| **Rule** | The rule that ran. Selecting the rule name opens the rule summary flyout so you can inspect the rule without leaving the page. | -| **Duration** | How long the execution took. | -| **Response** | The outcome of the run: `success` or `failure`. | -| **Message** | An optional message included with the execution result, typically an error description for failed runs. | - -Use the **Outcome** filter to narrow results by execution outcome: **All**, **Success**, or **Failure**. Filtering is applied server-side. Results are capped at 10,000 records. +Both tabs support pagination and a configurable rows-per-page setting. ## Disable or snooze a rule [disable-snooze-rule] diff --git a/explore-analyze/toc.yml b/explore-analyze/toc.yml index 910af53545..5aad3d7bd1 100644 --- a/explore-analyze/toc.yml +++ b/explore-analyze/toc.yml @@ -405,6 +405,7 @@ toc: - file: alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md - file: alerting/kibana-alerting-experimental/rules/configure-rule-tags.md - file: alerting/kibana-alerting-experimental/rules/view-manage-rules.md + - file: alerting/kibana-alerting-experimental/rules/review-execution-history.md - file: alerting/kibana-alerting-experimental/rules/esql-query-patterns.md children: - file: alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md From 105f064b18eb95d4df4cd6eba3b809c85d9baf44 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Tue, 7 Jul 2026 17:20:51 -0400 Subject: [PATCH 15/23] Add recent changes --- .../kibana-alerting-experimental/rules/create-esql-rule.md | 4 ++++ .../rules/create-rules-action-policies-agent-builder.md | 6 +++++- .../kibana-alerting-experimental/rules/use-rule-builder.md | 2 +- 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md index a87adb1d2b..cf06752ce0 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md @@ -31,6 +31,10 @@ Use the sandbox to: - **Catch unexpected output** - Verify that the query returns data in the right shape for the alert condition you plan to set. A query that returns zero rows or an unexpected field name won't behave as expected once the rule runs on a schedule. - **Refine before committing** - Edit the query and re-run it as many times as needed without leaving the rule creation form. +### Control how your query splits [sandbox-split-editor] + +By default, applying changes automatically splits your query into a [base query and alert condition](configure-rule-query.md). If you want full manual control over the split, use the toggle in the sandbox to switch to separate Base and Alert editors. If auto-split fails, a callout on the alert condition step lets you open the sandbox directly in manual split mode. + ## Using the YAML editor [yaml-editor] Use the YAML editor when you want to copy or adapt a rule quickly without re-entering settings by hand, or provision many rules at once. The YAML editor isn't available within the Threshold Alert builder. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md index 8049f5e037..ceb46cfa20 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md @@ -1,5 +1,5 @@ --- -navigation_title: Create rules and action policies with Agent Builder +navigation_title: Create rules using Agent Builder applies_to: stack: experimental 9.5+ serverless: experimental @@ -47,6 +47,8 @@ The agent can also search for and attach an existing rule to the conversation us The agent does not persist the rule automatically. Saving is an explicit action that signals the configuration is ready. Until the rule is saved, the proposal exists only in the conversation and is not evaluated against data. +When Agent Builder saves or edits a rule, {{kib}} automatically adds an `agent-builder-assisted` tag to it. The tag appears in the rules list and works as a normal filter tag. You can remove it or edit it manually. If the agent edits the same rule later, the tag is re-applied automatically. + :::{note} Signal rules do not support notifications. Alert episodes, and therefore action policies, only apply to rules running in Alert mode. If you ask the agent to set up notifications for a signal rule, the rule management skill explains the limitation and offers to either convert the rule to Alert mode or create a separate alert rule. ::: @@ -80,6 +82,8 @@ The three objects have a dependency chain that determines the order in which the This order is enforced in the UI. The action policy save control remains inactive until both dependencies are met. +Action policies saved or edited through Agent Builder also receive the `agent-builder-assisted` tag automatically, with the same behavior: user-editable and re-applied on subsequent agent edits. + ## Related pages - [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) - How the {{agent-builder}} platform works, including agents, skills, and tools. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md index 4adc9afdfe..3560d58517 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md @@ -16,4 +16,4 @@ For details on configurable rule settings and guidance on how to configure them, ## Threshold Alert [use-threshold-alert-builder] -Threshold Alert is the only rule type available in the rule builder. Use it to monitor one or more metrics and alert when they cross a threshold, with multi-condition support and custom aggregations. +Threshold Alert is the rule type currently available in the rule builder. Use it to monitor one or more metrics and alert when they cross a threshold, with multi-condition support and custom aggregations. From 237df996e28935391c8ccb212bdf055334bd150c Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Tue, 7 Jul 2026 17:31:12 -0400 Subject: [PATCH 16/23] Address 7241 --- .../kibana-alerting-experimental/rules/create-esql-rule.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md index cf06752ce0..1d7a455ea1 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md @@ -31,6 +31,8 @@ Use the sandbox to: - **Catch unexpected output** - Verify that the query returns data in the right shape for the alert condition you plan to set. A query that returns zero rows or an unexpected field name won't behave as expected once the rule runs on a schedule. - **Refine before committing** - Edit the query and re-run it as many times as needed without leaving the rule creation form. +While the sandbox is open, switching between rule form and YAML or between rule modes (Alert and Signal) is not available. Close the sandbox first if you need to change authoring mode. + ### Control how your query splits [sandbox-split-editor] By default, applying changes automatically splits your query into a [base query and alert condition](configure-rule-query.md). If you want full manual control over the split, use the toggle in the sandbox to switch to separate Base and Alert editors. If auto-split fails, a callout on the alert condition step lets you open the sandbox directly in manual split mode. From 2db4f483472d1bd6c5a4444e9723ba558030fb95 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 8 Jul 2026 16:45:10 -0400 Subject: [PATCH 17/23] Dominique's feedback --- .../create-rules-action-policies-agent-builder.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md index ceb46cfa20..3ed3b5f16f 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md @@ -18,9 +18,9 @@ Instead of filling out the rule form manually, you describe what you want to mon Before you start, make sure you have the following: -- **The required subscription**: {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). Without it, the "Create with AI Agent" option is hidden in the {{alerting-v2-system}} UI. -- **The `agentBuilder:experimentalFeatures` advanced setting turned on**: Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`. -- **The required privileges**: Your [role](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) must include the following: +- **The required subscription** - {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). Without it, the "Create with AI Agent" option is disabled in the {{alerting-v2-system}} UI. +- **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`. +- **The required privileges** - Your [role](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) must include the following: | To... | Required privilege | |---|---| @@ -35,12 +35,12 @@ Before you start, make sure you have the following: ## Propose and save a rule [ai-agent-rule-proposal] -To use this capability, open an agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the rule management skill configured. The rule management skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of ES\|QL query patterns, threshold configuration, grouping, and the alerting v2 data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. +You can start from the rule management page by selecting the option to create a rule with an agent, or open any agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the rule management skill configured. The rule management skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of {{esql}} query patterns, threshold configuration, grouping, and the alerting v2 data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. The proposal appears as an inline attachment in the conversation, summarizing the rule name, type, schedule, and tags. Opening the attachment shows the full configuration across three views: -- **Conditions** - The ES\|QL query, thresholds, grouping criteria, and schedule the agent constructed. -- **Query preview** - The results of running the proposed ES\|QL query against live data, so you can evaluate whether the rule would produce meaningful signal before committing to it. +- **Conditions** - The {{esql}} query, thresholds, grouping criteria, and schedule the agent constructed. +- **Query preview** - The results of running the proposed {{esql}} query against live data, so you can evaluate whether the rule would produce meaningful signal before committing to it. - **Runbook** - A free-text runbook field associated with the rule, which the agent can populate from context in the conversation. The agent can also search for and attach an existing rule to the conversation using the same inline attachment, opening the same view for inspection or revision. From 403123a1552a2396a186131b8e6cd9421989025c Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 8 Jul 2026 17:19:18 -0400 Subject: [PATCH 18/23] Fix inconsistencies and add items to clarify --- .../rules/configure-rule-thresholds.md | 7 ++++++- .../kibana-alerting-experimental/rules/create-a-rule.md | 2 +- .../rules/create-rule-from-discover.md | 5 +---- .../rules/create-rules-action-policies-agent-builder.md | 2 +- .../rules/review-execution-history.md | 2 ++ .../rules/rule-event-field-reference.md | 7 ++++--- .../rules/view-manage-rules.md | 1 + .../rules/yaml-rule-schema-reference.md | 1 + 8 files changed, 17 insertions(+), 10 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md index 11834e554a..f9f7f057b6 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md @@ -39,13 +39,18 @@ Activation thresholds control when a breached rule transitions from pending to a Use the following fields to configure the Breaches and Duration modes. Timeframe fields accept duration strings between `5s` and `365d`. Refer to [Duration format](yaml-rule-schema-reference.md#duration-format) for supported units. +:::{note} +In the YAML rule schema, these fields are prefixed with `state_transition.` — for example, `pending_count` here is `state_transition.pending_count` in the [YAML rule schema reference](yaml-rule-schema-reference.md#state-transition-fields). They are the same fields. +::: + + | Field | Type | Description | | --- | --- | --- | | `pending_count` | Positive integer | Number of consecutive breach evaluations required before the alert episode opens. | | `pending_timeframe` | Duration string | How long the condition must remain breached before the alert episode opens. | | `pending_operator` | `AND` or `OR` | When both `pending_count` and `pending_timeframe` are set, controls whether both must be satisfied (`AND`) or either one is enough (`OR`). | -You can combine Breaches and Duration. For example, require the threshold to be breached five times in a row _and_ persist for at least two minutes before an alert episode opens. To require both, set `pending_operator` to `AND` or `OR` if either is enough. +You can combine Breaches and Duration by setting both `pending_count` and `pending_timeframe`. Use `pending_operator: AND` to require both conditions before the episode opens, or `pending_operator: OR` if either condition alone is enough. ## Recovery thresholds diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md index aa225c9276..26d0f21c42 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md @@ -15,7 +15,7 @@ The {{alerting-v2-system}} in {{kib}} provides several ways to create rules. For | Option | Best for | | --- | --- | | [Create an ES\|QL rule](create-esql-rule.md) | Full control over the query. Supports both a step-by-step form and a YAML editor. | -| [Create with AI Agent](create-rules-action-policies-agent-builder.md) | When you know what you want to detect but aren't sure how to write the ES\|QL. | +| [Create using {{agent-builder}}](create-rules-action-policies-agent-builder.md) | When you know what you want to detect but aren't sure how to write the ES\|QL. | | [Use the rule builder](use-rule-builder.md) | Rules that follow a guided, form-based setup. | | [Create from Discover](create-rule-from-discover.md) | When you already have an ES\|QL query working in Discover and want to convert it into a rule. | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md index 842d739c84..4bdb57a615 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md @@ -25,7 +25,4 @@ When you trigger rule creation from Discover, your {{esql}} query pre-fills the The rule creation flyout supports both a step-by-step form and a YAML editing mode. You can switch between them at any point. Edits in YAML mode are preserved when you return to the form view. The YAML editor includes {{esql}} autocomplete in the query field. -For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). - - +For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md index 3ed3b5f16f..7087f1c231 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md @@ -18,7 +18,7 @@ Instead of filling out the rule form manually, you describe what you want to mon Before you start, make sure you have the following: -- **The required subscription** - {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). Without it, the "Create with AI Agent" option is disabled in the {{alerting-v2-system}} UI. +- **The required subscription** - {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). - **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`. - **The required privileges** - Your [role](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) must include the following: diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md index fd07eb0537..9e08ce74a6 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md @@ -31,3 +31,5 @@ Rule execution records are displayed in a table with the following columns: | **Message** | An optional message included with the execution result, typically an error description for failed runs. | Use the outcome filter to view only successful or failed executions. Filtering is applied server-side. Results are limited to 10,000 records. + + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md index a4801c6fbf..c15f057cb0 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md @@ -1,5 +1,5 @@ --- -navigation_title: Rule and event fields +navigation_title: Rule event and field reference applies_to: stack: experimental 9.5+ serverless: experimental @@ -10,6 +10,7 @@ description: "Field reference for .rule-events documents in Kibana's experimenta # Rule event and field reference in the {{alerting-v2-system}} [rule-reference] + This page is a field reference for `.rule-events` documents written by the {{alerting-v2-system}}. For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). The **Execution history** page logs each rule run and each action policy dispatch across the space. It is organized into two tabs: - **Rules** — One row per rule evaluation. Shows the timestamp, rule name, run duration, response status (success or failure), and a message. Use the **Response** filter to narrow results to successful or failed runs. Select a rule name to open its details page. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md index 2f2dfc9246..4c5aa933db 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md @@ -79,6 +79,7 @@ Signal-mode rules (`kind: signal`) must omit `recovery_strategy` or set it to `n Only valid when `kind: alert`. Controls how many consecutive detections are required before an episode becomes active or recovers. + | Field | Type | Accepted values | Description | |---|---|---|---| | `state_transition.pending_operator` | string | `AND` or `OR` | Whether both the count and timeframe must be met (`AND`) or either one (`OR`) before becoming active. | From 0ae994f4de45cc0b2674641da27f93bf5bf4dd82 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 8 Jul 2026 18:45:00 -0400 Subject: [PATCH 19/23] Address inconsistencies --- .../rules/configure-rule-grouping.md | 5 +- .../rules/configure-rule-thresholds.md | 5 +- ...ate-rules-action-policies-agent-builder.md | 4 -- .../rules/review-execution-history.md | 18 +++---- .../rules/rule-event-field-reference.md | 54 ++++--------------- .../rules/view-manage-rules.md | 25 ++------- .../rules/yaml-rule-schema-reference.md | 5 +- 7 files changed, 27 insertions(+), 89 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md index 4d90afb4a8..125fdd0ce8 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md @@ -12,10 +12,7 @@ description: "Configure rule grouping in Kibana's experimental alerting system t Rule grouping is an optional setting in the {{alerting-v2-system}} that lets a single rule track multiple things independently. For example, a rule monitoring CPU usage across hosts can produce a separate alert series for each host, rather than one alert for everything combined. - +In Alert mode, each group becomes its own alert episode with an independent lifecycle. One group can be active while another has recovered, and notifications apply per episode, not across all groups combined. Snooze state is also per series. Snoozing one group does not affect other groups tracked by the same rule. ## When to configure grouping [grouping-when-to-use] diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md index f9f7f057b6..de826d29b1 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md @@ -43,10 +43,9 @@ Use the following fields to configure the Breaches and Duration modes. Timeframe In the YAML rule schema, these fields are prefixed with `state_transition.` — for example, `pending_count` here is `state_transition.pending_count` in the [YAML rule schema reference](yaml-rule-schema-reference.md#state-transition-fields). They are the same fields. ::: - | Field | Type | Description | | --- | --- | --- | -| `pending_count` | Positive integer | Number of consecutive breach evaluations required before the alert episode opens. | +| `pending_count` | Integer, 0–1000 | Number of consecutive breach evaluations required before the alert episode opens. Set to `0` to skip the pending phase and transition directly to active on the first breach. | | `pending_timeframe` | Duration string | How long the condition must remain breached before the alert episode opens. | | `pending_operator` | `AND` or `OR` | When both `pending_count` and `pending_timeframe` are set, controls whether both must be satisfied (`AND`) or either one is enough (`OR`). | @@ -60,7 +59,7 @@ Recovery thresholds control when an active alert episode transitions back to ina | Field | Type | Description | | --- | --- | --- | -| `recovering_count` | Positive integer | Number of consecutive non-breaching evaluations required before the alert episode closes. | +| `recovering_count` | Integer, 0–1000 | Number of consecutive non-breaching evaluations required before the alert episode closes. Set to `0` to skip the recovering phase and transition directly to inactive on recovery. | | `recovering_timeframe` | Duration string | How long the condition must remain non-breaching before the alert episode closes. | | `recovering_operator` | `AND` or `OR` | When both `recovering_count` and `recovering_timeframe` are set, controls whether both must be satisfied (`AND`) or either one is enough (`OR`). | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md index 7087f1c231..d5b721a3a2 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md @@ -29,10 +29,6 @@ Before you start, make sure you have the following: | Save the action policy | **Action Policies: All** (under **Alerting**) | | Select or create the workflow destination | **Workflows: Read** to select an existing workflow; **Workflows: All** to create one (under **Analytics > Workflows**) | - - ## Propose and save a rule [ai-agent-rule-proposal] You can start from the rule management page by selecting the option to create a rule with an agent, or open any agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the rule management skill configured. The rule management skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of {{esql}} query patterns, threshold configuration, grouping, and the alerting v2 data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md index 9e08ce74a6..3732eb989e 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md @@ -10,17 +10,11 @@ description: "Use the Execution History page in Kibana's experimental alerting s # Review execution history in the {{alerting-v2-system}} [review-execution-history] -Execution history gives you a cross-rule, filterable log of every rule run across all rules in the space. Use it to spot patterns that aren't visible when looking at individual rules, for example, a cluster of failures at the same timestamp that points to a shared dependency issue. +Execution history gives you a cross-rule, filterable log of every rule run and action policy dispatch across the space. Rule executions and policy dispatcher decisions are shown separately, with different scopes. - +## Rule executions [rule-execution-records] -## Rule execution records [rule-execution-records] - -Rule execution records are displayed in a table with the following columns: +Rule execution history shows one row per rule evaluation across all rules in the space. Use it to spot patterns that aren't visible when looking at individual rules, for example, a cluster of failures at the same timestamp that points to a shared dependency issue. | Column | Description | |---|---| @@ -30,6 +24,8 @@ Rule execution records are displayed in a table with the following columns: | **Response** | The outcome of the run: `success` or `failure`. | | **Message** | An optional message included with the execution result, typically an error description for failed runs. | -Use the outcome filter to view only successful or failed executions. Filtering is applied server-side. Results are limited to 10,000 records. +Use the outcome filter to view only successful or failed executions. Filtering is applied server-side. Results are paginated up to 100 per page. You can page through up to 10,000 records — this is a pagination ceiling, not a retention limit. Deeper history exists in the event log but is not reachable by paging further. + +## Policy dispatcher decisions [policy-execution-records] - +Policy execution history shows one row per action policy dispatcher decision and covers the **last 24 hours** only. Use it to audit whether policies are dispatching as expected. Results are paginated up to 100 per page. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md index c15f057cb0..93558fab4f 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md @@ -9,15 +9,10 @@ description: "Field reference for .rule-events documents in Kibana's experimenta --- # Rule event and field reference in the {{alerting-v2-system}} [rule-reference] - - This page is a field reference for `.rule-events` documents written by the {{alerting-v2-system}}. For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). - :::{important} -The `.rule-events` and `.alert-actions` data streams are [system indices](/reference/glossary/index.md#glossary-system-index). {{kib}} manages their versioning, retention, and lifecycle through ILM. Older backing indices are deleted automatically when the retention window expires. Do not change mappings or index settings for these streams yourself. +The `.rule-events` and `.alert-actions` data streams are [system indices](/reference/glossary/index.md#glossary-system-index). {{kib}} manages their versioning, retention, and lifecycle through [Index Lifecycle Management (ILM)](/manage-data/lifecycle/index-lifecycle-management.md). Older backing indices are deleted automatically when the retention window expires. Do not change mappings or index settings for these streams yourself. ::: ## Rule event documents @@ -27,45 +22,18 @@ Each time a rule evaluates, {{kib}} writes one document per matched series to `. - **`signal`** - A point-in-time record that the query matched. Useful for querying history or chaining into follow-on rules. Signal documents don't include `episode.*` fields. - **`alert`** - A lifecycle-tracked episode visible in the alert inbox, episode details, and triage views. Alert documents include `episode.*` fields and represent a breach that stays open until the condition clears. -Both kinds share the base fields below. Only `alert` documents add the [Episode fields](#episode-fields) listed further down. +Both kinds share base fields. Only `alert` documents add episode fields that carry the lifecycle state for the matched series. :::{note} -`.rule-events` is a data stream, so it is append-only. A new document is written on every rule evaluation. Existing documents are never updated. Each document is a snapshot of that moment: the `episode.status` field records the lifecycle stage the episode was in at that evaluation. To view the full history of an episode, query all documents that share the same `episode.id`. - -::: - -### Signal and alert fields +The `.rule-events` data stream is append-only. A new document is written on every rule evaluation. Existing documents are never updated. Each document is a snapshot of that moment. The `episode.status` field records the lifecycle stage the episode was in at that evaluation. To view the full history of an episode, query `.rule-events` filtered by `episode.id`, for example: -These fields appear on all `.rule-events` documents, regardless of whether the rule is in Signal or Alert mode. +```esql +FROM .rule-events +| WHERE episode.id == "" +| SORT @timestamp ASC +``` -| Field | Type | Required | Description | -|---|---|---|---| -| `@timestamp` | date | Yes | When this document was written to `.rule-events`. | -| `scheduled_timestamp` | date | No | Scheduled execution time for this rule run. | -| `rule.id` | keyword | Yes | Rule identifier. | -| `rule.version` | long | Yes | Rule version at the time this event was emitted. | -| `group_hash` | keyword | Yes | Series identity key for grouped evaluations. | -| `data` | flattened | Yes | Payload from the {{esql}} query output. Shape depends on your rule. | -| `status` | keyword | Yes | One of: `breached`, `recovered`, `no_data`. | -| `source` | keyword | Yes | Origin of this event. Product-specific identifier. | -| `type` | keyword | Yes | `signal` or `alert`. Application field on each rule event document written by {{kib}}. | - -:::{admonition} Fields not stored as a dedicated column -There's no top-level or nested `duration` field on `.rule-events` documents. For triage or reporting, derive duration from the alert UI or your own queries over timestamps and episode identifiers. - -::: - -### Episode fields [episode-fields] - -These fields are stored in `.rule-events`, on the same document as the base fields, when the rule runs in Alert mode. They only appear on documents with `type: alert` and carry the lifecycle state for the episode associated with the matched series. - -| Field | Type | Description | -|---|---|---| -| `episode.id` | keyword | Episode identifier for this series. | -| `episode.status` | keyword | One of: `inactive`, `pending`, `active`, `recovering`. | -| `episode.status_count` | long | Count of consecutive evaluations in the current `episode.status`. Only set when `episode.status` is `pending` or `recovering`. | -| `severity` | keyword | Severity level from the most recent breached event. One of: `info`, `low`, `medium`, `high`, `critical`. Not set when the query output does not include a `severity` column, or when the value does not match a recognized level. Never set on `recovered` or `no_data` events. | +::: \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md index 2b2737a244..5c11f0130d 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md @@ -34,29 +34,12 @@ Use the flyout when you want to confirm a rule is healthy or take a quick action The rule details page is organized into tabs that let you review a rule's configuration and activity history. -- **Overview** (Alert mode only): Shows an alert activity timeline for each series the rule tracks. The timeline displays a color-coded history of alert episode state transitions per series, along with summary statistics: alert episodes started, recovered, still open, and median duration. A link to view all matching alert episodes is available, filtered to the current rule and time range. Lane labels appear only for grouped rules. The overview tab is not shown for Signal-mode rules, which don't open alert episodes. -- **Conditions**: The full {{esql}} base query, alert condition, schedule, lookback, grouping, and recovery settings. -- **Runbook**: If the rule has an investigation guide, it appears here. +- **Overview** (Alert mode only): Shows a color-coded alert activity timeline per series, with summary statistics (episodes started, recovered, still open, and median duration) and a link to view matching episodes. +- **Conditions**: The rule's base query, alert condition, schedule, lookback, grouping, and recovery settings. +- **Runbook**: The rule's investigation guide, if one has been added. Use it to document steps for diagnosing or responding to alerts produced by this rule. Use **Edit** to modify the rule, or the actions menu to enable, disable, clone, or delete it. -## Review execution history [rule-execution-history] - - -The **Execution history** page logs each rule run and each action policy dispatch across the space. It is organized into two tabs: - -- **Rules** — One row per rule evaluation. Shows the timestamp, rule name, run duration, response status (success or failure), and a message. Use the **Response** filter to narrow results to successful or failed runs. Select a rule name to open its details page. -- **Policies** — One row per action policy dispatch event. Use this tab to audit whether policies are dispatching as expected. - -Both tabs support pagination and a configurable rows-per-page setting. - ## Disable or snooze a rule [disable-snooze-rule] -Use **Disable** when you want the rule to stop running entirely until you re-enable it. This is different from snoozing, which suppresses notifications or quiets a series or policy without stopping rule evaluation. - - - +Use **Disable** when you want the rule to stop running entirely until you re-enable it. This is different from snoozing, which suppresses notifications or quiets a series or policy without stopping rule evaluation. \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md index 4c5aa933db..1fe8306f54 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md @@ -79,14 +79,13 @@ Signal-mode rules (`kind: signal`) must omit `recovery_strategy` or set it to `n Only valid when `kind: alert`. Controls how many consecutive detections are required before an episode becomes active or recovers. - | Field | Type | Accepted values | Description | |---|---|---|---| | `state_transition.pending_operator` | string | `AND` or `OR` | Whether both the count and timeframe must be met (`AND`) or either one (`OR`) before becoming active. | -| `state_transition.pending_count` | integer | Integer ≥ 0 | Number of consecutive breaches required before the episode becomes active. | +| `state_transition.pending_count` | integer | Integer, 0–1000 | Number of consecutive breaches required before the episode becomes active. Set to `0` to skip the pending phase and transition directly to active on the first breach. | | `state_transition.pending_timeframe` | duration | Any duration string | Time window within which the breach count must be met. For example: `5m`. | | `state_transition.recovering_operator` | string | `AND` or `OR` | Whether both the count and timeframe must be met (`AND`) or either one (`OR`) before recovering. | -| `state_transition.recovering_count` | integer | Integer ≥ 0 | Number of consecutive clear evaluations required before the episode recovers. | +| `state_transition.recovering_count` | integer | Integer, 0–1000 | Number of consecutive clear evaluations required before the episode recovers. Set to `0` to skip the recovering phase and transition directly to inactive on recovery. | | `state_transition.recovering_timeframe` | duration | Any duration string | Time window within which the recovery count must be met. For example: `5m`. | ## Grouping fields From 91c6865917c69c4b418f4fb45f97d390681a24a2 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 8 Jul 2026 19:49:21 -0400 Subject: [PATCH 20/23] Consistency fixes --- explore-analyze/alerting/alerts.md | 2 +- .../kibana-alerting-experimental/rules.md | 14 +++++++------- .../rules/configure-a-rule.md | 2 +- .../rules/configure-no-data-handling.md | 2 +- .../rules/configure-rule-grouping.md | 2 +- .../rules/configure-rule-mode.md | 4 ++-- .../rules/configure-rule-query.md | 2 +- .../rules/configure-rule-schedule.md | 2 +- .../rules/configure-rule-severity.md | 6 +++++- .../rules/configure-rule-tags.md | 2 +- .../rules/configure-rule-thresholds.md | 2 +- .../rules/create-a-rule.md | 2 +- .../rules/create-esql-rule.md | 2 +- .../rules/create-rule-from-discover.md | 2 +- ...ate-rules-action-policies-agent-builder.md | 19 ++++++++----------- .../rules/esql-first-rule-query.md | 2 +- .../rules/esql-no-data-detection.md | 2 +- .../rules/esql-persistent-breach.md | 2 +- .../rules/esql-query-patterns.md | 2 +- .../rules/esql-slo-burn-rate.md | 2 +- .../rules/esql-threshold-queries.md | 2 +- ...ry.md => review-rule-execution-history.md} | 8 ++++---- .../rules/rule-event-field-reference.md | 7 ++++--- .../rules/use-rule-builder.md | 2 +- .../rules/view-manage-rules.md | 4 ++-- .../rules/yaml-rule-schema-reference.md | 4 ++-- explore-analyze/toc.yml | 2 +- 27 files changed, 53 insertions(+), 51 deletions(-) rename explore-analyze/alerting/kibana-alerting-experimental/rules/{review-execution-history.md => review-rule-execution-history.md} (75%) diff --git a/explore-analyze/alerting/alerts.md b/explore-analyze/alerting/alerts.md index 972d944c84..fad4c20556 100644 --- a/explore-analyze/alerting/alerts.md +++ b/explore-analyze/alerting/alerts.md @@ -17,7 +17,7 @@ description: "Overview of Kibana alerting: rules, alerts, actions, connectors, a {{kib}} alerting is the built-in alerting system in {{kib}}. It lets you define rules that check your data on a schedule, create alerts when conditions are met, and trigger actions through connectors (email, Slack, webhooks, and more). It is available on all deployments. ## {{rules-ui}} [rules] diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules.md index 906ea11b35..b659adfd60 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules.md @@ -8,7 +8,7 @@ products: description: "Rules in Kibana's experimental alerting system define what to detect using ES|QL. Evaluation runs on a schedule and alerts, action policies, and notifications flow from rule detections." --- -# Rules in the {{alerting-v2-system}} +# Rules in the {{alerting-v2-system}} [experimental-alerting-system-rules] A rule is where the {{alerting-v2-system}} starts. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. @@ -22,14 +22,14 @@ In Signal mode, each matching row is stored as a signal document with no alert l ## What rules don't do -Rules only define *what* to detect. They don't control notifications, who gets notified, or when. That's the job of action policies, which are global objects scoped to your space that match alert episodes from any rule. A rule has no say in which policies pick it up. +Rules only define *what* to detect. They don't control notifications, who gets notified, or when. That's the job of action policies, which are global objects scoped to your space that match alert episodes from any rule. A rule has no say in which action policies pick it up. This separation means you can build and test a rule without anyone getting paged, update notification routing without touching the rule, and have multiple action policies respond to the same rule independently. ## Next steps -- **[Create a rule](rules/create-a-rule.md):** Compare creation paths and choose the one that fits your workflow. -- **[Configure a rule](rules/configure-a-rule.md):** Set the schedule, grouping, activation thresholds, recovery conditions, and no-data behavior. -- **[View and manage rules](rules/view-manage-rules.md):** Enable, disable, clone, delete, and bulk-manage rules from the rules list. -- **[Review execution history](rules/review-execution-history.md):** Monitor rule and action policy execution outcomes across all rules in a space. -- **[ES|QL query patterns](rules/esql-query-patterns.md):** Browse query patterns ordered by complexity, from a basic event filter to SLO burn rate and persistent breach detection. \ No newline at end of file +- [Create a rule](rules/create-a-rule.md): Compare creation paths and choose the one that fits your workflow. +- [Configure a rule](rules/configure-a-rule.md): Set the schedule, grouping, activation thresholds, recovery conditions, and no-data behavior. +- [View and manage rules](rules/view-manage-rules.md): Enable, disable, clone, delete, and bulk-manage rules from the rules list. +- [Review execution history](rules/review-rule-execution-history.md): Monitor rule and action policy execution outcomes across all rules in a space. +- [{{esql}} query patterns](rules/esql-query-patterns.md): Browse query patterns ordered by complexity, from a basic event filter to SLO burn rate and persistent breach detection. \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md index 087f7472c2..3d7c383b31 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md @@ -8,7 +8,7 @@ products: description: "Overview of all configurable rule settings in the experimental alerting system. Required settings are mode, ES|QL query, and schedule. Optional settings include severity, grouping, activation and recovery thresholds, no-data handling, and tags." --- -# Configure a rule in the {{alerting-v2-system}} [rule-settings] +# Configure a rule in the {{alerting-v2-system}} [experimental-alerting-system-rule-settings] Rules in the {{alerting-v2-system}} have three required settings and several optional ones. Start with the required settings in order. Only add optional settings once the detection logic is validated. The following table links to a dedicated page for each setting with field descriptions, accepted values, and guidance on when to configure it. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md index e2d3231928..0eb520fd3e 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md @@ -8,7 +8,7 @@ products: description: "How to configure the no-data strategy for rules in the experimental alerting system. Controls whether an empty query result emits a no-data event, holds the last known alert state, triggers recovery, or is ignored." --- -# No-data handling in the {{alerting-v2-system}} [no-data-handling] +# No-data handling in the {{alerting-v2-system}} [experimental-alerting-system-no-data-handling] No-data handling is an optional setting for rules in the {{alerting-v2-system}}. Use `no_data_strategy` to control what the rule records when the base query returns no results. Setting this correctly prevents false recoveries and misleading `no_data` events when data sources stop reporting. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md index 125fdd0ce8..a2dc033cbd 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md @@ -8,7 +8,7 @@ products: description: "Configure rule grouping in Kibana's experimental alerting system to track multiple subjects as independent alert series." --- -# Rule grouping in the {{alerting-v2-system}} [rule-grouping] +# Rule grouping in the {{alerting-v2-system}} [experimental-alerting-system-rule-grouping] Rule grouping is an optional setting in the {{alerting-v2-system}} that lets a single rule track multiple things independently. For example, a rule monitoring CPU usage across hosts can produce a separate alert series for each host, rather than one alert for everything combined. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md index fdde673b34..67e3b54a28 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md @@ -8,9 +8,9 @@ products: description: "How rule mode determines whether detections produce signal documents or tracked alert episodes in the experimental alerting system, and when to use each." --- -# Rule mode in the {{alerting-v2-system}} [rule-mode] +# Rule mode in the {{alerting-v2-system}} [experimental-alerting-system-rule-mode] -Rule mode is a required setting for rules in the {{alerting-v2-system}}. It determines what the rule produces when the detection query finds a match. Rule mode is set by the rule creation method and some [creation paths](create-a-rule.md) only support one mode. +Rule mode is a required setting for rules in the {{alerting-v2-system}}. It determines what the rule produces when the detection query finds a match. Rule mode is set by the rule creation method. Some [creation paths](create-a-rule.md) only support one mode. | Mode | Behavior | | --- | --- | diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md index c466920586..91fdd668e7 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md @@ -8,7 +8,7 @@ products: description: "How to structure the ES|QL detection query for a rule in the experimental alerting system. Covers the base query, the optional alert condition that gates which rows become breaches, and dynamic parameters for time bounds and configurable thresholds." --- -# {{esql}} query in the {{alerting-v2-system}} [esql-query-rule] +# {{esql}} query in the {{alerting-v2-system}} [experimental-alerting-system-esql-query-rule] Every rule in the {{alerting-v2-system}} uses an {{esql}} query to define what to evaluate. The query consists of a base query that shapes and filters the data and an optional alert condition that determines which rows become alert events. For more advanced use cases, the query also supports [dynamic values](#dynamic-query-values) for filtering by the evaluation window or setting configurable thresholds through the rule form. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md index d45abee80c..fb22239df2 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md @@ -8,7 +8,7 @@ products: description: "How the execution interval and lookback window control when a rule evaluates and how much data it covers each time in the experimental alerting system." --- -# Schedule and lookback in the {{alerting-v2-system}} [schedule-lookback] +# Schedule and lookback in the {{alerting-v2-system}} [experimental-alerting-system-schedule-lookback] Schedule and lookback are required settings for rules in the {{alerting-v2-system}}. They control how often a rule runs and how far back it looks when evaluating data. This page describes both fields, lists the accepted values and bounds, and includes guidance on choosing appropriate values for different monitoring scenarios. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md index 59b6b47524..50786e0aa3 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md @@ -8,7 +8,7 @@ products: description: "Assign severity levels to alert episodes in Kibana's experimental alerting system using a severity column in ES|QL query output." --- -# Severity in the {{alerting-v2-system}} [rule-severity] +# Severity in the {{alerting-v2-system}} [experimental-alerting-system-rule-severity] Severity is an optional setting for rules in the {{alerting-v2-system}}. To set it, include a column named `severity` in your {{esql}} query output and add it to your `KEEP` list. The framework reads that column after each evaluation and maps it to one of five fixed levels. @@ -40,7 +40,11 @@ Keep the following in mind when configuring severity. - **Matching is case-insensitive** - `critical`, `Critical`, and `CRITICAL` are all treated the same. You can use any casing in your `EVAL` expression. - **Unrecognized values are silently ignored** - If the `severity` column contains a value that doesn't match one of the five levels, the alert episode is still created but `severity` is not set. If severity isn't appearing as expected, check the exact string your query is producing. - **Severity only applies to breached events** - `recovered` and `no_data` events don't carry a severity value. Action policy matchers that filter by severity only match open episodes. + + ## Examples diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md index 2b1e531666..101c65265c 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md @@ -8,7 +8,7 @@ products: description: "Add tags and runbooks to Alert-mode rules in Kibana's experimental alerting system for filtering and investigation context." --- -# Tags and runbooks in the {{alerting-v2-system}} (Alert mode only) [tags-investigation] +# Tags and runbooks in the {{alerting-v2-system}} (Alert mode only) [experimental-alerting-system-tags-investigation] Tags and runbooks are optional artifacts for Alert-mode rules in the {{alerting-v2-system}}. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md index de826d29b1..0813f71be1 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md @@ -8,7 +8,7 @@ products: description: "Configure activation and recovery thresholds for Alert-mode rules in Kibana's experimental alerting system to reduce noise from brief spikes and rapid state changes." --- -# Activation and recovery thresholds in the {{alerting-v2-system}} (Alert mode only) [activation-recovery-thresholds] +# Activation and recovery thresholds in the {{alerting-v2-system}} (Alert mode only) [experimental-alerting-system-activation-recovery-thresholds] Activation and recovery thresholds are optional settings for Alert-mode rules in the {{alerting-v2-system}}. They control when alerts transition between lifecycle states, reducing noise from brief spikes and rules that alternate rapidly between breaching and recovering. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md index 26d0f21c42..c9fd061409 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md @@ -8,7 +8,7 @@ products: description: "Create rules in Kibana's experimental alerting system using the ES|QL editor, AI Agent, rule builder, or directly from a Discover session." --- -# Create a rule in the {{alerting-v2-system}} [create-a-rule] +# Create a rule in the {{alerting-v2-system}} [experimental-alerting-system-create-a-rule] The {{alerting-v2-system}} in {{kib}} provides several ways to create rules. For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md index 1d7a455ea1..24e6722d5d 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md @@ -8,7 +8,7 @@ products: description: "Write ES|QL detection queries for rules in Kibana's experimental alerting system using the rule form or YAML editor, with a live query sandbox for previewing results." --- -# Create an {{esql}} rule in the {{alerting-v2-system}} [create-esql-rule] +# Create an {{esql}} rule in the {{alerting-v2-system}} [experimental-alerting-system-create-esql-rule] The {{esql}} rule path lets you write the detection query directly. There are two ways to define the rule: diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md index 4bdb57a615..9e86b5a1e7 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md @@ -8,7 +8,7 @@ products: description: "Convert an ES|QL query from a Discover session into a rule in Kibana's experimental alerting system, with the query pre-filled and a preview panel for verifying grouping." --- -# Create a rule from Discover in the {{alerting-v2-system}} [create-from-discover] +# Create a rule from Discover in the {{alerting-v2-system}} [experimental-alerting-system-create-from-discover] When you build an {{esql}} query in Discover that surfaces interesting patterns, you can convert it into a rule without rewriting the query. Starting from Discover means your query is already tested and returns the shape you expect before the rule is ever saved. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md index d5b721a3a2..63d12ff049 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md @@ -8,7 +8,7 @@ products: description: "How Agent Builder creates rules and action policies in the experimental alerting system using the rule management skill, what the agent produces, and the save-order dependency." --- -# Create rules and action policies with {{agent-builder}} [create-rules-action-policies-ai-agent] +# Create rules and action policies with {{agent-builder}} [experimental-alerting-system-create-rules-agent-builder] Rule and action policy authoring in {{agent-builder}} is part of the {{alerting-v2-system}} in {{kib}}. The {{alerting-v2-system}} registers rules and action policies as attachment types in {{agent-builder}}, so an agent equipped with the rule management skill can propose, create, and configure them through natural language conversation. @@ -24,7 +24,7 @@ Before you start, make sure you have the following: | To... | Required privilege | |---|---| - | Access and use {{agent-builder}} | **Agent Builder: Read** (under **Analytics**) | + | Access and use {{agent-builder}} | **{{agent-builder}}: Read** (under **Analytics**) | | Save the rule | **Rules: All** (under **Alerting**) | | Save the action policy | **Action Policies: All** (under **Alerting**) | | Select or create the workflow destination | **Workflows: Read** to select an existing workflow; **Workflows: All** to create one (under **Analytics > Workflows**) | @@ -43,7 +43,7 @@ The agent can also search for and attach an existing rule to the conversation us The agent does not persist the rule automatically. Saving is an explicit action that signals the configuration is ready. Until the rule is saved, the proposal exists only in the conversation and is not evaluated against data. -When Agent Builder saves or edits a rule, {{kib}} automatically adds an `agent-builder-assisted` tag to it. The tag appears in the rules list and works as a normal filter tag. You can remove it or edit it manually. If the agent edits the same rule later, the tag is re-applied automatically. +When {{agent-builder}} saves or edits a rule, {{kib}} automatically adds an `agent-builder-assisted` tag to it. The tag appears in the rules list and works as a normal filter tag. You can remove it or edit it manually. If the agent edits the same rule later, the tag is re-applied automatically. :::{note} Signal rules do not support notifications. Alert episodes, and therefore action policies, only apply to rules running in Alert mode. If you ask the agent to set up notifications for a signal rule, the rule management skill explains the limitation and offers to either convert the rule to Alert mode or create a separate alert rule. @@ -58,13 +58,12 @@ Use these prompts as a starting point, then adjust them to your data and thresho - Alert when log volume from the payments service drops below 100 events in a 5-minute window. This likely means data has stopped flowing. - Set up a rule that tracks error rate by service. Alert at medium severity when the rate exceeds 1%, and critical when it exceeds 5%. - ## Set up notifications [ai-agent-notification-setup] -After a rule is saved, you can ask the agent to configure notifications. The rule management skill handles this by creating two objects: +After a rule is saved, you can ask the agent to configure notifications. The rule management skill handles this by creating workflows and action policies. -- A **workflow** - The delivery mechanism. It defines what happens when the {{alerting-v2-system}} determines that a notification should be sent: posting to Slack, emailing a team, triggering PagerDuty, and so on. -- An **action policy** - The gating mechanism. It evaluates alert episodes from the rule on a continuous schedule and invokes the workflow when the episode clears the policy's match conditions and frequency settings. When the agent creates an action policy alongside a specific rule, the policy is automatically scoped to that rule as a per-rule policy. +- **Workflows** - Workflows are the delivery mechanism. They define what happens when the {{alerting-v2-system}} determines that a notification should be sent, such as posting to Slack, emailing a team, triggering PagerDuty, and so on. +- **Action policies** - Action policies are the gating mechanism. They evaluates alert episodes from the rule on a continuous schedule and invokes the workflow when the episode clears the action policy's match conditions and frequency settings. When the agent creates an action policy alongside a specific rule, the action policy is automatically scoped to that rule. Both objects are proposed as inline attachments and must be explicitly saved before they take effect. @@ -76,13 +75,11 @@ The three objects have a dependency chain that determines the order in which the 2. **Workflow** - The action policy references the workflow as a destination. The reference must resolve to a persisted workflow. 3. **Action policy** - Can only be saved after both its rule and workflow dependencies exist. -This order is enforced in the UI. The action policy save control remains inactive until both dependencies are met. - -Action policies saved or edited through Agent Builder also receive the `agent-builder-assisted` tag automatically, with the same behavior: user-editable and re-applied on subsequent agent edits. +Action policies saved or edited through {{agent-builder}} also receive the `agent-builder-assisted` tag automatically, with the same behavior: user-editable and re-applied on subsequent agent edits. ## Related pages - [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) - How the {{agent-builder}} platform works, including agents, skills, and tools. - + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md index d7129b53ad..e908729823 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md @@ -8,7 +8,7 @@ products: description: "Write your first ES|QL rule query in Kibana's experimental alerting system. Covers the minimum query structure and how to adapt it to your data." --- -# Your first rule query in the {{alerting-v2-system}} [esql-first-rule-query] +# Your first rule query in the {{alerting-v2-system}} [experimental-alerting-system-first-rule-query] If you're new to {{esql}} or to writing rules, this page shows the simplest query structure that a rule needs. It requires only a basic familiarity with your data. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md index e74676cb8f..1b5064a457 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md @@ -8,7 +8,7 @@ products: description: "Detect silent hosts and stopped data sources in Kibana's experimental alerting system using ES|QL last-seen queries." --- -# No-data detection in the {{alerting-v2-system}} [no-data-esql-query] +# No-data detection in the {{alerting-v2-system}} [experimental-alerting-system-no-data-esql-query] No-data detection solves a different problem from threshold alerting. A threshold query evaluates data that's present. No-data detection identifies sources that have gone silent. Threshold queries can't do this. A silent host produces no rows at all, so there's nothing to evaluate a condition against. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md index d6471397ed..e5c5517019 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md @@ -8,7 +8,7 @@ products: description: "Detect conditions that persist across consecutive time buckets in Kibana's experimental alerting system using ES|QL bucket counting." --- -# Persistent breach detection in the {{alerting-v2-system}} [persistent-breach] +# Persistent breach detection in the {{alerting-v2-system}} [experimental-alerting-system-persistent-breach] A persistent breach condition detects a metric that stays above a threshold across several consecutive time buckets, for example CPU above 90% in all 10 of the last 10 five-minute windows. This filters out transient spikes and fires only when a problem has been sustained. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md index 604ff57bd9..fababcb576 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md @@ -8,7 +8,7 @@ products: description: "ES|QL query patterns for rules in Kibana's experimental alerting system, from basic event filters to SLO burn rates, silent source detection, and persistent breach checks." --- -# {{esql}} query patterns for rules in the {{alerting-v2-system}} [esql-query-patterns] +# {{esql}} query patterns for rules in the {{alerting-v2-system}} [experimental-alerting-system-esql-query-patterns] The following pages cover {{esql}} query patterns for rules in the {{alerting-v2-system}}, ordered from the simplest starting point to advanced use cases. Start with [Your first rule query](esql-first-rule-query.md) if you're new, or jump to the pattern you need. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md index 98a53f0e47..9cb1579b15 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md @@ -8,7 +8,7 @@ products: description: "Detect SLO error budget burn across multiple time windows in Kibana's experimental alerting system using ES|QL conditional aggregation." --- -# SLO burn rate detection in the {{alerting-v2-system}} [slo-burn-rate-query] +# SLO burn rate detection in the {{alerting-v2-system}} [experimental-alerting-system-slo-burn-rate-query] An SLO burn rate query asks a different question than a basic threshold: are you consuming your error budget faster than you can afford to? Rather than checking a single metric at a fixed limit, it calculates error rates across multiple time windows simultaneously and assigns a severity level based on how fast the budget is being consumed. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md index ffaf304936..9b73445ee6 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md @@ -8,7 +8,7 @@ products: description: "Write ES|QL threshold queries for rules in Kibana's experimental alerting system. Covers single-series and grouped rules using STATS aggregation." --- -# Threshold queries in the {{alerting-v2-system}} [esql-threshold-queries] +# Threshold queries in the {{alerting-v2-system}} [experimental-alerting-system-esql-threshold-queries] A threshold query aggregates your data first, then applies an alert condition to the result. Use this pattern when a single matching event isn't enough to warrant an alert. You want to know whether a metric (count, rate, average) has crossed a limit over a time window. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/review-rule-execution-history.md similarity index 75% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md rename to explore-analyze/alerting/kibana-alerting-experimental/rules/review-rule-execution-history.md index 3732eb989e..fdf8de8cfd 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/review-execution-history.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/review-rule-execution-history.md @@ -8,9 +8,9 @@ products: description: "Use the Execution History page in Kibana's experimental alerting system to monitor rule and action policy execution outcomes across all rules in a space." --- -# Review execution history in the {{alerting-v2-system}} [review-execution-history] +# Review execution history in the {{alerting-v2-system}} [experimental-alerting-system-review-rule-execution-history] -Execution history gives you a cross-rule, filterable log of every rule run and action policy dispatch across the space. Rule executions and policy dispatcher decisions are shown separately, with different scopes. +Execution history gives you a cross-rule, filterable log of every rule run and action policy dispatch across the space. Rule executions and action policy dispatcher decisions are shown separately, with different scopes. ## Rule executions [rule-execution-records] @@ -26,6 +26,6 @@ Rule execution history shows one row per rule evaluation across all rules in the Use the outcome filter to view only successful or failed executions. Filtering is applied server-side. Results are paginated up to 100 per page. You can page through up to 10,000 records — this is a pagination ceiling, not a retention limit. Deeper history exists in the event log but is not reachable by paging further. -## Policy dispatcher decisions [policy-execution-records] +## Action policy dispatcher decisions [policy-execution-records] -Policy execution history shows one row per action policy dispatcher decision and covers the **last 24 hours** only. Use it to audit whether policies are dispatching as expected. Results are paginated up to 100 per page. +Action policy execution history shows one row per action policy dispatcher decision and covers the **last 24 hours** only. Use it to audit whether action policies are dispatching as expected. Results are paginated up to 100 per page. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md index 93558fab4f..df31b979e6 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md @@ -8,11 +8,12 @@ products: description: "Field reference for .rule-events documents in Kibana's experimental alerting system. Covers signal and alert base fields, episode fields, and the append-only data stream behavior." --- -# Rule event and field reference in the {{alerting-v2-system}} [rule-reference] -This page is a field reference for `.rule-events` documents written by the {{alerting-v2-system}}. For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). +# Rule event and field reference in the {{alerting-v2-system}} [experimental-alerting-system-rule-reference] + +This page is a field reference for `.rule-events` documents written by the {{alerting-v2-system}}. Use it when writing {{esql}} queries against `.rule-events`, for example, to replay an episode's history, investigate a signal, or build dashboards from rule output. :::{important} -The `.rule-events` and `.alert-actions` data streams are [system indices](/reference/glossary/index.md#glossary-system-index). {{kib}} manages their versioning, retention, and lifecycle through [Index Lifecycle Management (ILM)](/manage-data/lifecycle/index-lifecycle-management.md). Older backing indices are deleted automatically when the retention window expires. Do not change mappings or index settings for these streams yourself. +The `.rule-events` and `.alert-actions` data streams are [system indices](/reference/glossary/index.md#glossary-system-index). {{kib}} manages their versioning, retention, and lifecycle through [index lifecycle management (ILM)](/manage-data/lifecycle/index-lifecycle-management.md). Older backing indices are deleted automatically when the retention window expires. Do not change mappings or index settings for these streams yourself. ::: ## Rule event documents diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md index 3560d58517..1ca5f6663c 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md @@ -8,7 +8,7 @@ products: description: "Create Threshold Alert rules in Kibana's experimental alerting system using a guided form that generates ES|QL automatically." --- -# Create a rule using the rule builder in the {{alerting-v2-system}} [use-rule-builder] +# Create a rule using the rule builder in the {{alerting-v2-system}} [experimental-alerting-system-use-rule-builder] The rule builder provides a guided form for creating rules without writing {{esql}} by hand. The builder generates the {{esql}} query automatically from structured inputs for the data source, aggregation, filters, and alert conditions. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md index 5c11f0130d..015a1f0830 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md @@ -8,7 +8,7 @@ products: description: "Search, filter, and bulk-manage rules in Kibana's experimental alerting system. Use inline editing, the rule summary flyout, and the rule details page to manage rules." --- -# View and manage rules in the {{alerting-v2-system}} [manage-rules] +# View and manage rules in the {{alerting-v2-system}} [experimental-alerting-system-manage-rules] Rule management is part of the {{alerting-v2-system}} in {{kib}}. This page covers how to find and filter rules in the rules list, quick-edit settings without leaving the list, use the rule summary flyout, and navigate the rule details page including the alert activity timeline. @@ -42,4 +42,4 @@ Use **Edit** to modify the rule, or the actions menu to enable, disable, clone, ## Disable or snooze a rule [disable-snooze-rule] -Use **Disable** when you want the rule to stop running entirely until you re-enable it. This is different from snoozing, which suppresses notifications or quiets a series or policy without stopping rule evaluation. \ No newline at end of file +Use **Disable** when you want the rule to stop running entirely until you re-enable it. This is different from snoozing, which suppresses notifications or quiets a series or action policy without stopping rule evaluation. \ No newline at end of file diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md index 1fe8306f54..4ce7e1c1c4 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md @@ -8,7 +8,7 @@ products: description: "YAML rule definitions in Kibana's experimental alerting system support fields for detection mode, schedule, query, grouping, and recovery. Reference tables list all valid field values." --- -# YAML rule schema reference for the {{alerting-v2-system}} [yaml-rule-schema-reference] +# YAML rule schema reference for the {{alerting-v2-system}} [experimental-alerting-system-yaml-rule-schema-reference] YAML rule schema is part of the {{alerting-v2-system}} in {{kib}}. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create an ES|QL rule](create-esql-rule.md#yaml-editor). @@ -75,7 +75,7 @@ The `recovery_strategy` field is optional. When omitted, the rule emits no recov Signal-mode rules (`kind: signal`) must omit `recovery_strategy` or set it to `none`. Any other value fails validation. ::: -## State transition fields +## State transition fields [state-transition-fields] Only valid when `kind: alert`. Controls how many consecutive detections are required before an episode becomes active or recovers. diff --git a/explore-analyze/toc.yml b/explore-analyze/toc.yml index 582112debf..6d375b97d9 100644 --- a/explore-analyze/toc.yml +++ b/explore-analyze/toc.yml @@ -406,7 +406,7 @@ toc: - file: alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md - file: alerting/kibana-alerting-experimental/rules/configure-rule-tags.md - file: alerting/kibana-alerting-experimental/rules/view-manage-rules.md - - file: alerting/kibana-alerting-experimental/rules/review-execution-history.md + - file: alerting/kibana-alerting-experimental/rules/review-rule-execution-history.md - file: alerting/kibana-alerting-experimental/rules/esql-query-patterns.md children: - file: alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md From 246a8b38b743d2be17bebb8223de1aa8aee109df Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 8 Jul 2026 19:56:38 -0400 Subject: [PATCH 21/23] remove comment - no longer needed --- .../rules/configure-rule-grouping.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md index a2dc033cbd..616336c393 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md @@ -39,9 +39,6 @@ The fields you declare in `grouping.fields` must match the column names produced Write the query first, then set the group fields. That way the `BY` columns are already defined and you can select them directly. If you later add or remove a `BY` field in the query, update the group fields to match. ::: - - ## Examples ### Track error rates per service From f48bd88bb6564679f39d8558dd3942dbe6a78a92 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Thu, 9 Jul 2026 12:37:02 -0400 Subject: [PATCH 22/23] updating to not use alert --- .../kibana-alerting-experimental/rules/use-rule-builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md index 1ca5f6663c..1e0c360527 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md @@ -16,4 +16,4 @@ For details on configurable rule settings and guidance on how to configure them, ## Threshold Alert [use-threshold-alert-builder] -Threshold Alert is the rule type currently available in the rule builder. Use it to monitor one or more metrics and alert when they cross a threshold, with multi-condition support and custom aggregations. +Threshold Alert is the rule type currently available in the rule builder. Use it to monitor metrics against one or more threshold conditions. Custom aggregations let you control how metric values are computed before they are compared to the threshold. \ No newline at end of file From 9fe683b23a751d855524892d1ddd5a6c300ad606 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Thu, 9 Jul 2026 19:10:52 -0400 Subject: [PATCH 23/23] update folder name and anchors --- .../rules.md | 2 +- .../rules/configure-a-rule.md | 2 +- .../rules/configure-no-data-handling.md | 2 +- .../rules/configure-rule-grouping.md | 2 +- .../rules/configure-rule-mode.md | 2 +- .../rules/configure-rule-query.md | 2 +- .../rules/configure-rule-schedule.md | 2 +- .../rules/configure-rule-severity.md | 4 +- .../rules/configure-rule-tags.md | 2 +- .../rules/configure-rule-thresholds.md | 2 +- .../rules/create-a-rule.md | 2 +- .../rules/create-esql-rule.md | 2 +- .../rules/create-rule-from-discover.md | 2 +- ...ate-rules-action-policies-agent-builder.md | 2 +- .../rules/esql-first-rule-query.md | 2 +- .../rules/esql-no-data-detection.md | 2 +- .../rules/esql-persistent-breach.md | 2 +- .../rules/esql-query-patterns.md | 2 +- .../rules/esql-slo-burn-rate.md | 2 +- .../rules/esql-threshold-queries.md | 2 +- .../rules/review-rule-execution-history.md | 2 +- .../rules/rule-event-field-reference.md | 12 +++-- .../rules/use-rule-builder.md | 2 +- .../rules/view-manage-rules.md | 2 +- .../rules/yaml-rule-schema-reference.md | 2 +- explore-analyze/toc.yml | 54 +++++++++---------- 26 files changed, 60 insertions(+), 56 deletions(-) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules.md (97%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/configure-a-rule.md (95%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/configure-no-data-handling.md (97%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/configure-rule-grouping.md (97%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/configure-rule-mode.md (97%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/configure-rule-query.md (98%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/configure-rule-schedule.md (97%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/configure-rule-severity.md (95%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/configure-rule-tags.md (98%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/configure-rule-thresholds.md (98%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/create-a-rule.md (93%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/create-esql-rule.md (96%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/create-rule-from-discover.md (94%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/create-rules-action-policies-agent-builder.md (98%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/esql-first-rule-query.md (96%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/esql-no-data-detection.md (94%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/esql-persistent-breach.md (95%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/esql-query-patterns.md (96%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/esql-slo-burn-rate.md (97%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/esql-threshold-queries.md (96%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/review-rule-execution-history.md (94%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/rule-event-field-reference.md (70%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/use-rule-builder.md (95%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/view-manage-rules.md (96%) rename explore-analyze/alerting/{kibana-alerting-experimental => experimental-alerting-system}/rules/yaml-rule-schema-reference.md (98%) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules.md b/explore-analyze/alerting/experimental-alerting-system/rules.md similarity index 97% rename from explore-analyze/alerting/kibana-alerting-experimental/rules.md rename to explore-analyze/alerting/experimental-alerting-system/rules.md index b659adfd60..589ed957bf 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules.md @@ -8,7 +8,7 @@ products: description: "Rules in Kibana's experimental alerting system define what to detect using ES|QL. Evaluation runs on a schedule and alerts, action policies, and notifications flow from rule detections." --- -# Rules in the {{alerting-v2-system}} [experimental-alerting-system-rules] +# Rules in the {{alerting-v2-system}} [rules] A rule is where the {{alerting-v2-system}} starts. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md b/explore-analyze/alerting/experimental-alerting-system/rules/configure-a-rule.md similarity index 95% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md rename to explore-analyze/alerting/experimental-alerting-system/rules/configure-a-rule.md index 3d7c383b31..087f7472c2 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/configure-a-rule.md @@ -8,7 +8,7 @@ products: description: "Overview of all configurable rule settings in the experimental alerting system. Required settings are mode, ES|QL query, and schedule. Optional settings include severity, grouping, activation and recovery thresholds, no-data handling, and tags." --- -# Configure a rule in the {{alerting-v2-system}} [experimental-alerting-system-rule-settings] +# Configure a rule in the {{alerting-v2-system}} [rule-settings] Rules in the {{alerting-v2-system}} have three required settings and several optional ones. Start with the required settings in order. Only add optional settings once the detection logic is validated. The following table links to a dedicated page for each setting with field descriptions, accepted values, and guidance on when to configure it. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md b/explore-analyze/alerting/experimental-alerting-system/rules/configure-no-data-handling.md similarity index 97% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md rename to explore-analyze/alerting/experimental-alerting-system/rules/configure-no-data-handling.md index 0eb520fd3e..e2d3231928 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/configure-no-data-handling.md @@ -8,7 +8,7 @@ products: description: "How to configure the no-data strategy for rules in the experimental alerting system. Controls whether an empty query result emits a no-data event, holds the last known alert state, triggers recovery, or is ignored." --- -# No-data handling in the {{alerting-v2-system}} [experimental-alerting-system-no-data-handling] +# No-data handling in the {{alerting-v2-system}} [no-data-handling] No-data handling is an optional setting for rules in the {{alerting-v2-system}}. Use `no_data_strategy` to control what the rule records when the base query returns no results. Setting this correctly prevents false recoveries and misleading `no_data` events when data sources stop reporting. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-grouping.md similarity index 97% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md rename to explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-grouping.md index 616336c393..5132240cd4 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-grouping.md @@ -8,7 +8,7 @@ products: description: "Configure rule grouping in Kibana's experimental alerting system to track multiple subjects as independent alert series." --- -# Rule grouping in the {{alerting-v2-system}} [experimental-alerting-system-rule-grouping] +# Rule grouping in the {{alerting-v2-system}} [rule-grouping] Rule grouping is an optional setting in the {{alerting-v2-system}} that lets a single rule track multiple things independently. For example, a rule monitoring CPU usage across hosts can produce a separate alert series for each host, rather than one alert for everything combined. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-mode.md similarity index 97% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md rename to explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-mode.md index 67e3b54a28..b90c8e50d8 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-mode.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-mode.md @@ -8,7 +8,7 @@ products: description: "How rule mode determines whether detections produce signal documents or tracked alert episodes in the experimental alerting system, and when to use each." --- -# Rule mode in the {{alerting-v2-system}} [experimental-alerting-system-rule-mode] +# Rule mode in the {{alerting-v2-system}} [rule-mode] Rule mode is a required setting for rules in the {{alerting-v2-system}}. It determines what the rule produces when the detection query finds a match. Rule mode is set by the rule creation method. Some [creation paths](create-a-rule.md) only support one mode. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-query.md similarity index 98% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md rename to explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-query.md index 91fdd668e7..c466920586 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-query.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-query.md @@ -8,7 +8,7 @@ products: description: "How to structure the ES|QL detection query for a rule in the experimental alerting system. Covers the base query, the optional alert condition that gates which rows become breaches, and dynamic parameters for time bounds and configurable thresholds." --- -# {{esql}} query in the {{alerting-v2-system}} [experimental-alerting-system-esql-query-rule] +# {{esql}} query in the {{alerting-v2-system}} [esql-query-rule] Every rule in the {{alerting-v2-system}} uses an {{esql}} query to define what to evaluate. The query consists of a base query that shapes and filters the data and an optional alert condition that determines which rows become alert events. For more advanced use cases, the query also supports [dynamic values](#dynamic-query-values) for filtering by the evaluation window or setting configurable thresholds through the rule form. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-schedule.md similarity index 97% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md rename to explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-schedule.md index fb22239df2..d45abee80c 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-schedule.md @@ -8,7 +8,7 @@ products: description: "How the execution interval and lookback window control when a rule evaluates and how much data it covers each time in the experimental alerting system." --- -# Schedule and lookback in the {{alerting-v2-system}} [experimental-alerting-system-schedule-lookback] +# Schedule and lookback in the {{alerting-v2-system}} [schedule-lookback] Schedule and lookback are required settings for rules in the {{alerting-v2-system}}. They control how often a rule runs and how far back it looks when evaluating data. This page describes both fields, lists the accepted values and bounds, and includes guidance on choosing appropriate values for different monitoring scenarios. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-severity.md similarity index 95% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md rename to explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-severity.md index 50786e0aa3..66de8fe832 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-severity.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-severity.md @@ -8,7 +8,7 @@ products: description: "Assign severity levels to alert episodes in Kibana's experimental alerting system using a severity column in ES|QL query output." --- -# Severity in the {{alerting-v2-system}} [experimental-alerting-system-rule-severity] +# Severity in the {{alerting-v2-system}} [rule-severity] Severity is an optional setting for rules in the {{alerting-v2-system}}. To set it, include a column named `severity` in your {{esql}} query output and add it to your `KEEP` list. The framework reads that column after each evaluation and maps it to one of five fixed levels. @@ -43,7 +43,7 @@ Keep the following in mind when configuring severity. ## Examples diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-tags.md similarity index 98% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md rename to explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-tags.md index 101c65265c..2b1e531666 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-tags.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-tags.md @@ -8,7 +8,7 @@ products: description: "Add tags and runbooks to Alert-mode rules in Kibana's experimental alerting system for filtering and investigation context." --- -# Tags and runbooks in the {{alerting-v2-system}} (Alert mode only) [experimental-alerting-system-tags-investigation] +# Tags and runbooks in the {{alerting-v2-system}} (Alert mode only) [tags-investigation] Tags and runbooks are optional artifacts for Alert-mode rules in the {{alerting-v2-system}}. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-thresholds.md similarity index 98% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md rename to explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-thresholds.md index 0813f71be1..de826d29b1 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-thresholds.md @@ -8,7 +8,7 @@ products: description: "Configure activation and recovery thresholds for Alert-mode rules in Kibana's experimental alerting system to reduce noise from brief spikes and rapid state changes." --- -# Activation and recovery thresholds in the {{alerting-v2-system}} (Alert mode only) [experimental-alerting-system-activation-recovery-thresholds] +# Activation and recovery thresholds in the {{alerting-v2-system}} (Alert mode only) [activation-recovery-thresholds] Activation and recovery thresholds are optional settings for Alert-mode rules in the {{alerting-v2-system}}. They control when alerts transition between lifecycle states, reducing noise from brief spikes and rules that alternate rapidly between breaching and recovering. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md b/explore-analyze/alerting/experimental-alerting-system/rules/create-a-rule.md similarity index 93% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md rename to explore-analyze/alerting/experimental-alerting-system/rules/create-a-rule.md index c9fd061409..26d0f21c42 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-a-rule.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/create-a-rule.md @@ -8,7 +8,7 @@ products: description: "Create rules in Kibana's experimental alerting system using the ES|QL editor, AI Agent, rule builder, or directly from a Discover session." --- -# Create a rule in the {{alerting-v2-system}} [experimental-alerting-system-create-a-rule] +# Create a rule in the {{alerting-v2-system}} [create-a-rule] The {{alerting-v2-system}} in {{kib}} provides several ways to create rules. For details on configurable rule settings and guidance on how to configure them, refer to [Configure a rule](configure-a-rule.md). diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md b/explore-analyze/alerting/experimental-alerting-system/rules/create-esql-rule.md similarity index 96% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md rename to explore-analyze/alerting/experimental-alerting-system/rules/create-esql-rule.md index 24e6722d5d..1d7a455ea1 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-esql-rule.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/create-esql-rule.md @@ -8,7 +8,7 @@ products: description: "Write ES|QL detection queries for rules in Kibana's experimental alerting system using the rule form or YAML editor, with a live query sandbox for previewing results." --- -# Create an {{esql}} rule in the {{alerting-v2-system}} [experimental-alerting-system-create-esql-rule] +# Create an {{esql}} rule in the {{alerting-v2-system}} [create-esql-rule] The {{esql}} rule path lets you write the detection query directly. There are two ways to define the rule: diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md b/explore-analyze/alerting/experimental-alerting-system/rules/create-rule-from-discover.md similarity index 94% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md rename to explore-analyze/alerting/experimental-alerting-system/rules/create-rule-from-discover.md index 9e86b5a1e7..4bdb57a615 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/create-rule-from-discover.md @@ -8,7 +8,7 @@ products: description: "Convert an ES|QL query from a Discover session into a rule in Kibana's experimental alerting system, with the query pre-filled and a preview panel for verifying grouping." --- -# Create a rule from Discover in the {{alerting-v2-system}} [experimental-alerting-system-create-from-discover] +# Create a rule from Discover in the {{alerting-v2-system}} [create-from-discover] When you build an {{esql}} query in Discover that surfaces interesting patterns, you can convert it into a rule without rewriting the query. Starting from Discover means your query is already tested and returns the shape you expect before the rule is ever saved. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/experimental-alerting-system/rules/create-rules-action-policies-agent-builder.md similarity index 98% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md rename to explore-analyze/alerting/experimental-alerting-system/rules/create-rules-action-policies-agent-builder.md index 63d12ff049..68074e8ee5 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/create-rules-action-policies-agent-builder.md @@ -8,7 +8,7 @@ products: description: "How Agent Builder creates rules and action policies in the experimental alerting system using the rule management skill, what the agent produces, and the save-order dependency." --- -# Create rules and action policies with {{agent-builder}} [experimental-alerting-system-create-rules-agent-builder] +# Create rules and action policies with {{agent-builder}} [create-rules-agent-builder] Rule and action policy authoring in {{agent-builder}} is part of the {{alerting-v2-system}} in {{kib}}. The {{alerting-v2-system}} registers rules and action policies as attachment types in {{agent-builder}}, so an agent equipped with the rule management skill can propose, create, and configure them through natural language conversation. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md b/explore-analyze/alerting/experimental-alerting-system/rules/esql-first-rule-query.md similarity index 96% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md rename to explore-analyze/alerting/experimental-alerting-system/rules/esql-first-rule-query.md index e908729823..80e4b17674 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/esql-first-rule-query.md @@ -8,7 +8,7 @@ products: description: "Write your first ES|QL rule query in Kibana's experimental alerting system. Covers the minimum query structure and how to adapt it to your data." --- -# Your first rule query in the {{alerting-v2-system}} [experimental-alerting-system-first-rule-query] +# Your first rule query in the {{alerting-v2-system}} [first-rule-query] If you're new to {{esql}} or to writing rules, this page shows the simplest query structure that a rule needs. It requires only a basic familiarity with your data. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md b/explore-analyze/alerting/experimental-alerting-system/rules/esql-no-data-detection.md similarity index 94% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md rename to explore-analyze/alerting/experimental-alerting-system/rules/esql-no-data-detection.md index 1b5064a457..e74676cb8f 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/esql-no-data-detection.md @@ -8,7 +8,7 @@ products: description: "Detect silent hosts and stopped data sources in Kibana's experimental alerting system using ES|QL last-seen queries." --- -# No-data detection in the {{alerting-v2-system}} [experimental-alerting-system-no-data-esql-query] +# No-data detection in the {{alerting-v2-system}} [no-data-esql-query] No-data detection solves a different problem from threshold alerting. A threshold query evaluates data that's present. No-data detection identifies sources that have gone silent. Threshold queries can't do this. A silent host produces no rows at all, so there's nothing to evaluate a condition against. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md b/explore-analyze/alerting/experimental-alerting-system/rules/esql-persistent-breach.md similarity index 95% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md rename to explore-analyze/alerting/experimental-alerting-system/rules/esql-persistent-breach.md index e5c5517019..d6471397ed 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/esql-persistent-breach.md @@ -8,7 +8,7 @@ products: description: "Detect conditions that persist across consecutive time buckets in Kibana's experimental alerting system using ES|QL bucket counting." --- -# Persistent breach detection in the {{alerting-v2-system}} [experimental-alerting-system-persistent-breach] +# Persistent breach detection in the {{alerting-v2-system}} [persistent-breach] A persistent breach condition detects a metric that stays above a threshold across several consecutive time buckets, for example CPU above 90% in all 10 of the last 10 five-minute windows. This filters out transient spikes and fires only when a problem has been sustained. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md b/explore-analyze/alerting/experimental-alerting-system/rules/esql-query-patterns.md similarity index 96% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md rename to explore-analyze/alerting/experimental-alerting-system/rules/esql-query-patterns.md index fababcb576..604ff57bd9 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/esql-query-patterns.md @@ -8,7 +8,7 @@ products: description: "ES|QL query patterns for rules in Kibana's experimental alerting system, from basic event filters to SLO burn rates, silent source detection, and persistent breach checks." --- -# {{esql}} query patterns for rules in the {{alerting-v2-system}} [experimental-alerting-system-esql-query-patterns] +# {{esql}} query patterns for rules in the {{alerting-v2-system}} [esql-query-patterns] The following pages cover {{esql}} query patterns for rules in the {{alerting-v2-system}}, ordered from the simplest starting point to advanced use cases. Start with [Your first rule query](esql-first-rule-query.md) if you're new, or jump to the pattern you need. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md b/explore-analyze/alerting/experimental-alerting-system/rules/esql-slo-burn-rate.md similarity index 97% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md rename to explore-analyze/alerting/experimental-alerting-system/rules/esql-slo-burn-rate.md index 9cb1579b15..98a53f0e47 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/esql-slo-burn-rate.md @@ -8,7 +8,7 @@ products: description: "Detect SLO error budget burn across multiple time windows in Kibana's experimental alerting system using ES|QL conditional aggregation." --- -# SLO burn rate detection in the {{alerting-v2-system}} [experimental-alerting-system-slo-burn-rate-query] +# SLO burn rate detection in the {{alerting-v2-system}} [slo-burn-rate-query] An SLO burn rate query asks a different question than a basic threshold: are you consuming your error budget faster than you can afford to? Rather than checking a single metric at a fixed limit, it calculates error rates across multiple time windows simultaneously and assigns a severity level based on how fast the budget is being consumed. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md b/explore-analyze/alerting/experimental-alerting-system/rules/esql-threshold-queries.md similarity index 96% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md rename to explore-analyze/alerting/experimental-alerting-system/rules/esql-threshold-queries.md index 9b73445ee6..ffaf304936 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/esql-threshold-queries.md @@ -8,7 +8,7 @@ products: description: "Write ES|QL threshold queries for rules in Kibana's experimental alerting system. Covers single-series and grouped rules using STATS aggregation." --- -# Threshold queries in the {{alerting-v2-system}} [experimental-alerting-system-esql-threshold-queries] +# Threshold queries in the {{alerting-v2-system}} [esql-threshold-queries] A threshold query aggregates your data first, then applies an alert condition to the result. Use this pattern when a single matching event isn't enough to warrant an alert. You want to know whether a metric (count, rate, average) has crossed a limit over a time window. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/review-rule-execution-history.md b/explore-analyze/alerting/experimental-alerting-system/rules/review-rule-execution-history.md similarity index 94% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/review-rule-execution-history.md rename to explore-analyze/alerting/experimental-alerting-system/rules/review-rule-execution-history.md index fdf8de8cfd..396593b52b 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/review-rule-execution-history.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/review-rule-execution-history.md @@ -8,7 +8,7 @@ products: description: "Use the Execution History page in Kibana's experimental alerting system to monitor rule and action policy execution outcomes across all rules in a space." --- -# Review execution history in the {{alerting-v2-system}} [experimental-alerting-system-review-rule-execution-history] +# Review execution history in the {{alerting-v2-system}} [review-rule-execution-history] Execution history gives you a cross-rule, filterable log of every rule run and action policy dispatch across the space. Rule executions and action policy dispatcher decisions are shown separately, with different scopes. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md b/explore-analyze/alerting/experimental-alerting-system/rules/rule-event-field-reference.md similarity index 70% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md rename to explore-analyze/alerting/experimental-alerting-system/rules/rule-event-field-reference.md index df31b979e6..42a157e16c 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/rule-event-field-reference.md @@ -1,16 +1,20 @@ --- -navigation_title: Rule event and field reference +navigation_title: Rule events applies_to: stack: experimental 9.5+ serverless: experimental products: - id: kibana -description: "Field reference for .rule-events documents in Kibana's experimental alerting system. Covers signal and alert base fields, episode fields, and the append-only data stream behavior." +description: "How the experimental alerting system in Kibana writes rule events to .rule-events: signal and alert document types, shared base fields, episode fields, and the append-only data stream behavior." --- -# Rule event and field reference in the {{alerting-v2-system}} [experimental-alerting-system-rule-reference] +# Rule events in {{alerting-v2-system}} [rule-reference] -This page is a field reference for `.rule-events` documents written by the {{alerting-v2-system}}. Use it when writing {{esql}} queries against `.rule-events`, for example, to replay an episode's history, investigate a signal, or build dashboards from rule output. +This page explains the two types of documents the {{alerting-v2-system}} writes to `.rule-events` and how the data stream behaves, so you can write {{esql}} queries against `.rule-events` with confidence, for example, to replay an episode's history, investigate a signal, or build dashboards from rule output. + + :::{important} The `.rule-events` and `.alert-actions` data streams are [system indices](/reference/glossary/index.md#glossary-system-index). {{kib}} manages their versioning, retention, and lifecycle through [index lifecycle management (ILM)](/manage-data/lifecycle/index-lifecycle-management.md). Older backing indices are deleted automatically when the retention window expires. Do not change mappings or index settings for these streams yourself. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md b/explore-analyze/alerting/experimental-alerting-system/rules/use-rule-builder.md similarity index 95% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md rename to explore-analyze/alerting/experimental-alerting-system/rules/use-rule-builder.md index 1e0c360527..bc5c59dd44 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/use-rule-builder.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/use-rule-builder.md @@ -8,7 +8,7 @@ products: description: "Create Threshold Alert rules in Kibana's experimental alerting system using a guided form that generates ES|QL automatically." --- -# Create a rule using the rule builder in the {{alerting-v2-system}} [experimental-alerting-system-use-rule-builder] +# Create a rule using the rule builder in the {{alerting-v2-system}} [use-rule-builder] The rule builder provides a guided form for creating rules without writing {{esql}} by hand. The builder generates the {{esql}} query automatically from structured inputs for the data source, aggregation, filters, and alert conditions. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md b/explore-analyze/alerting/experimental-alerting-system/rules/view-manage-rules.md similarity index 96% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md rename to explore-analyze/alerting/experimental-alerting-system/rules/view-manage-rules.md index 015a1f0830..9a5b58915f 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/view-manage-rules.md @@ -8,7 +8,7 @@ products: description: "Search, filter, and bulk-manage rules in Kibana's experimental alerting system. Use inline editing, the rule summary flyout, and the rule details page to manage rules." --- -# View and manage rules in the {{alerting-v2-system}} [experimental-alerting-system-manage-rules] +# View and manage rules in the {{alerting-v2-system}} [manage-rules] Rule management is part of the {{alerting-v2-system}} in {{kib}}. This page covers how to find and filter rules in the rules list, quick-edit settings without leaving the list, use the rule summary flyout, and navigate the rule details page including the alert activity timeline. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md b/explore-analyze/alerting/experimental-alerting-system/rules/yaml-rule-schema-reference.md similarity index 98% rename from explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md rename to explore-analyze/alerting/experimental-alerting-system/rules/yaml-rule-schema-reference.md index 4ce7e1c1c4..4519c8208e 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md +++ b/explore-analyze/alerting/experimental-alerting-system/rules/yaml-rule-schema-reference.md @@ -8,7 +8,7 @@ products: description: "YAML rule definitions in Kibana's experimental alerting system support fields for detection mode, schedule, query, grouping, and recovery. Reference tables list all valid field values." --- -# YAML rule schema reference for the {{alerting-v2-system}} [experimental-alerting-system-yaml-rule-schema-reference] +# YAML rule schema reference for the {{alerting-v2-system}} [yaml-rule-schema-reference] YAML rule schema is part of the {{alerting-v2-system}} in {{kib}}. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create an ES|QL rule](create-esql-rule.md#yaml-editor). diff --git a/explore-analyze/toc.yml b/explore-analyze/toc.yml index 97aba50ce6..4be535c3b2 100644 --- a/explore-analyze/toc.yml +++ b/explore-analyze/toc.yml @@ -385,36 +385,36 @@ toc: - file: report-and-share/reporting-troubleshooting-pdf.md - file: alerting.md children: - - file: alerting/kibana-alerting-experimental/rules.md + - file: alerting/experimental-alerting-system/rules.md children: - - file: alerting/kibana-alerting-experimental/rules/create-a-rule.md + - file: alerting/experimental-alerting-system/rules/create-a-rule.md children: - - file: alerting/kibana-alerting-experimental/rules/create-esql-rule.md + - file: alerting/experimental-alerting-system/rules/create-esql-rule.md children: - - file: alerting/kibana-alerting-experimental/rules/yaml-rule-schema-reference.md - - file: alerting/kibana-alerting-experimental/rules/create-rules-action-policies-agent-builder.md - - file: alerting/kibana-alerting-experimental/rules/use-rule-builder.md - - file: alerting/kibana-alerting-experimental/rules/create-rule-from-discover.md - - file: alerting/kibana-alerting-experimental/rules/configure-a-rule.md - children: - - file: alerting/kibana-alerting-experimental/rules/configure-rule-mode.md - - file: alerting/kibana-alerting-experimental/rules/configure-rule-query.md - - file: alerting/kibana-alerting-experimental/rules/configure-rule-severity.md - - file: alerting/kibana-alerting-experimental/rules/configure-rule-grouping.md - - file: alerting/kibana-alerting-experimental/rules/configure-rule-schedule.md - - file: alerting/kibana-alerting-experimental/rules/configure-rule-thresholds.md - - file: alerting/kibana-alerting-experimental/rules/configure-no-data-handling.md - - file: alerting/kibana-alerting-experimental/rules/configure-rule-tags.md - - file: alerting/kibana-alerting-experimental/rules/view-manage-rules.md - - file: alerting/kibana-alerting-experimental/rules/review-rule-execution-history.md - - file: alerting/kibana-alerting-experimental/rules/esql-query-patterns.md - children: - - file: alerting/kibana-alerting-experimental/rules/esql-first-rule-query.md - - file: alerting/kibana-alerting-experimental/rules/esql-threshold-queries.md - - file: alerting/kibana-alerting-experimental/rules/esql-no-data-detection.md - - file: alerting/kibana-alerting-experimental/rules/esql-slo-burn-rate.md - - file: alerting/kibana-alerting-experimental/rules/esql-persistent-breach.md - - file: alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md + - file: alerting/experimental-alerting-system/rules/yaml-rule-schema-reference.md + - file: alerting/experimental-alerting-system/rules/create-rules-action-policies-agent-builder.md + - file: alerting/experimental-alerting-system/rules/use-rule-builder.md + - file: alerting/experimental-alerting-system/rules/create-rule-from-discover.md + - file: alerting/experimental-alerting-system/rules/configure-a-rule.md + children: + - file: alerting/experimental-alerting-system/rules/configure-rule-mode.md + - file: alerting/experimental-alerting-system/rules/configure-rule-query.md + - file: alerting/experimental-alerting-system/rules/configure-rule-severity.md + - file: alerting/experimental-alerting-system/rules/configure-rule-grouping.md + - file: alerting/experimental-alerting-system/rules/configure-rule-schedule.md + - file: alerting/experimental-alerting-system/rules/configure-rule-thresholds.md + - file: alerting/experimental-alerting-system/rules/configure-no-data-handling.md + - file: alerting/experimental-alerting-system/rules/configure-rule-tags.md + - file: alerting/experimental-alerting-system/rules/view-manage-rules.md + - file: alerting/experimental-alerting-system/rules/review-rule-execution-history.md + - file: alerting/experimental-alerting-system/rules/esql-query-patterns.md + children: + - file: alerting/experimental-alerting-system/rules/esql-first-rule-query.md + - file: alerting/experimental-alerting-system/rules/esql-threshold-queries.md + - file: alerting/experimental-alerting-system/rules/esql-no-data-detection.md + - file: alerting/experimental-alerting-system/rules/esql-slo-burn-rate.md + - file: alerting/experimental-alerting-system/rules/esql-persistent-breach.md + - file: alerting/experimental-alerting-system/rules/rule-event-field-reference.md - hidden: alerting/compare-alerting-systems.md - hidden: alerting/system-overview.md - hidden: alerting/experimental-alerting-system/how-it-works.md