Loading

YAML rule schema reference for the experimental alerting system

YAML rule schema is part of the experimental alerting system in Kibana. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to Create rules using the YAML editor.

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 ES|QL query, max 10,000 characters The query that checks your data on each run.
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.
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.

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 breach results for the active group. query uses a separate recovery query.
recovery_policy.query.base string Valid ES|QL query Required when recovery_policy.type is query. The query that checks whether the condition has cleared.

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.
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.
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.
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.
Field Type Accepted values Description
notification_policies[].ref string Format: policies/<id> Links a notification policy to the rule.

All duration fields accept the following units:

Unit Example Meaning
s 30s Seconds
m 5m Minutes
h 1h Hours
d 7d Days