YAML rule schema reference for the experimental alerting system

This page lists valid fields for YAML rule definitions in the experimental alerting system. For authoring guidance, refer to Create an ES|QL rule.

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 alert episodes (alert) or records point-in-time observations (signal). Set when the rule is created and can't be modified when editing the rule.
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.

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 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.

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.

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 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.

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 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.

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_strategy string no_breach, query, or none How recovery is detected.

-no_breach: Recovers an alert 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

Rules with kind: signal must omit recovery_strategy or set it to none. Any other value fails validation.

Only valid when kind: alert. Controls how many consecutive detections are required before an alert 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–1000 Number of consecutive breaches required before the alert 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 How long the condition must remain continuously breached before the alert episode becomes active. 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–1000 Number of consecutive clear evaluations required before the alert 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 How long the condition must remain continuously non-breaching before the alert episode recovers. For example: 5m.

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 Array of field names Fields to group results by. Each unique combination becomes its own series. Max 16 fields, each max 256 characters.

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 this setting, a quiet data source and a healthy one look identical to the rule.

Field Type Accepted values Description
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.
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. Rules with kind: signal must omit no_data_strategy or set it to none.

Artifacts let you attach reference material directly to a rule, such as a runbook or a linked dashboard. Kibana stores the artifact with the rule and displays it on the rule details page, so responders have context when an alert fires.

The artifacts array is optional and accepts up to 100 entries. Every artifact needs id and type. Use data or value for the content, as shown in the following table.

Field Type Accepted values Description
artifacts[].id string Any string Artifact identifier. Required. Max 256 characters.
artifacts[].type string Any string Use runbook or dashboard. Other strings are allowed. Max 128 characters.
artifacts[].data object Type-specific object Required. The artifact's content. Max 32 fields.
artifacts[].data.content string Non-empty string The Markdown body of a runbook. Kibana displays it on the Runbook tab of the rule details page. Required when type is runbook. Max 50,000 characters.
artifacts[].data.dashboard_id string Non-empty string ID of the dashboard to link. Required when type is dashboard. Max 1,024 characters.
artifacts[].value string Any string Required. Runbook Markdown (max 50,000 characters) or a dashboard ID (max 1,024 characters).

The following example attaches a runbook and a dashboard to the same rule.

artifacts:
  - id: checkout-runbook
    type: runbook
    data:
      content: |
        Fires when checkout error rate exceeds 10%.
  - id: checkout-errors-dashboard
    type: dashboard
    data:
      dashboard_id: "8ac12f90-3d2b-11ef-9a4e-0242ac120002"
  1. type determines which data field the artifact requires.
  2. The runbook Markdown goes in data.content.
  3. The dashboard ID goes in data.dashboard_id.

If Kibana loads a rule that still uses value, it converts that field to data. Write new YAML with data.

artifacts:
  - id: checkout-runbook
    type: runbook
    value: |
      Fires when checkout error rate exceeds 10%.
  - id: checkout-errors-dashboard
    type: dashboard
    value: "8ac12f90-3d2b-11ef-9a4e-0242ac120002"
  1. The runbook Markdown goes in value.
  2. The dashboard ID goes in value.

All duration fields accept the following units:

Unit Example Meaning
s 30s Seconds
m 5m Minutes
h 1h Hours
d 7d Days
  • Create an ES|QL rule: Author rules using the YAML editor, with a live sandbox for previewing results.
  • Configure a rule: Field-by-field guidance for each setting, with examples and when-to-use recommendations.