🇺🇸English

Kibana Alerting Rules

Core Concepts

A rule has three parts: conditions (what to detect), schedule (how often to check), and actions (what happens when conditions are met). When conditions are met, the rule creates alerts , which trigger actions via connectors.

Authentication

All alerting API calls require either API key auth or Basic auth. Every mutating request must include the kbn-xsrf header.

kbn-xsrf: true

Required Privileges

• all privileges for the appropriate Kibana feature (e.g., Stack Rules, Observability, Security)
• read privileges for Actions and Connectors (to attach actions to rules)

API Reference

Base path: <kibana_url>/api/alerting (or /s/<space_id>/api/alerting for non-default spaces).

Creating a Rule

Required Fields

Optional Fields

Example: Create an Elasticsearch Query Rule

curl -X POST "https://my-kibana:5601/api/alerting/rule/my-rule-id" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey <your-api-key>" \
  -d '{
    "name": "High error rate",
    "rule_type_id": ".es-query",
    "consumer": "stackAlerts",
    "schedule": { "interval": "5m" },
    "params": {
      "index": ["logs-*"],
      "timeField": "@timestamp",
      "esQuery": "{\"query\":{\"match\":{\"log.level\":\"error\"}}}",
      "threshold": [100],
      "thresholdComparator": ">",
      "timeWindowSize": 5,
      "timeWindowUnit": "m",
      "size": 100
    },
    "actions": [
      {
        "id": "my-slack-connector-id",
        "group": "query matched",
        "params": {
          "message": "Alert: {{rule.name}} - {{context.hits}} hits detected"
        },
        "frequency": {
          "summary": false,
          "notify_when": "onActionGroupChange"
        }
      }
    ],
    "tags": ["production", "errors"]
  }'

The same structure applies to other rule types — set the appropriate rule_type_id (e.g., .index-threshold, .es-query) and provide the matching params object. Use GET /api/alerting/rule_types to discover params schemas.

Updating a Rule

PUT /api/alerting/rule/{id} — send the complete rule body. rule_type_id and consumer are immutable after creation. Returns 409 Conflict if another user updated the rule concurrently; re-fetch and retry.

Finding Rules

curl -X GET "https://my-kibana:5601/api/alerting/rules/_find?per_page=20&page=1&search=cpu&sort_field=name&sort_order=asc" \
  -H "Authorization: ApiKey <your-api-key>"

Query parameters: per_page, page, search, default_search_operator, search_fields, sort_field, sort_order, has_reference, fields, filter, filter_consumers.

Use the filter parameter with KQL syntax for advanced queries:

filter=alert.attributes.tags:"production"

Lifecycle Operations

# Enable
curl -X POST ".../api/alerting/rule/{id}/_enable" -H "kbn-xsrf: true"

# Disable
curl -X POST ".../api/alerting/rule/{id}/_disable" -H "kbn-xsrf: true"

# Mute all alerts
curl -X POST ".../api/alerting/rule/{id}/_mute_all" -H "kbn-xsrf: true"

# Mute specific alert
curl -X POST ".../api/alerting/rule/{rule_id}/alert/{alert_id}/_mute" -H "kbn-xsrf: true"

# Delete
curl -X DELETE ".../api/alerting/rule/{id}" -H "kbn-xsrf: true"

Terraform Provider

Use the elasticstack provider resource elasticstack_kibana_alerting_rule.

terraform {
  required_providers {
    elasticstack = {
      source  = "elastic/elasticstack"
    }
  }
}

provider "elasticstack" {
  kibana {
    endpoints = ["https://my-kibana:5601"]
    api_key   = var.kibana_api_key
  }
}

resource "elasticstack_kibana_alerting_rule" "cpu_alert" {
  name         = "CPU usage critical"
  consumer     = "stackAlerts"
  rule_type_id = ".index-threshold"
  interval     = "1m"
  enabled      = true

  params = jsonencode({
    index              = ["metrics-*"]
    timeField          = "@timestamp"
    aggType            = "avg"
    aggField           = "system.cpu.total.pct"
    groupBy            = "top"
    termField          = "host.name"
    termSize           = 10
    threshold          = [0.9]
    thresholdComparator = ">"
    timeWindowSize     = 5
    timeWindowUnit     = "m"
  })

  tags = ["infrastructure", "production"]
}

Key Terraform notes:

• params must be passed as a JSON-encoded string via jsonencode()
• Use elasticstack_kibana_action_connector data source or resource to reference connector IDs in actions
• Import existing rules: terraform import elasticstack_kibana_alerting_rule.my_rule <space_id>/<rule_id> (use default for the default space)

Triggering Kibana Workflows from Rules

Preview feature — available from Elastic Stack 9.3 and Elastic Cloud Serverless. APIs may change.

Attach a workflow as a rule action using the workflow ID as the connector ID. Set params: {} — alert context flows automatically through the event object inside the workflow.

curl -X PUT "https://my-kibana:5601/api/alerting/rule/my-rule-id" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey <your-api-key>" \
  -d '{
    "name": "High error rate",
    "schedule": { "interval": "5m" },
    "params": { ... },
    "actions": [
      {
        "id": "<workflow-id>",
        "group": "query matched",
        "params": {},
        "frequency": { "summary": false, "notify_when": "onActionGroupChange" }
      }
    ]
  }'

In the UI: Stack Management > Rules > Actions > Workflows. Only enabled: true workflows appear in the picker.

For workflow YAML structure, {{ event }} context fields, step types, and patterns, refer to the kibana-connectors skill if available.

Connectors and Actions in Rules

Each action references a connector by ID, an action group, action params (using Mustache templates), and a per-action frequency object. Key fields:

• group — which trigger state fires this action (e.g., "query matched", "Recovered"). Discover valid groups via GET /api/alerting/rule_types.
• frequency.summary — true for a digest of all alerts; false for per-alert.
• frequency.notify_when — onActionGroupChange | onActiveAlert | onThrottleInterval.

For full reference on action structure, Mustache variables ({{rule.name}}, {{context.*}}, {{alerts.new.count}}), Mustache lambdas (EvalMath, FormatDate, ParseHjson), recovery actions, and multi-channel patterns, refer to the kibana-connectors skill if available.

Best Practices

1. Set action frequency per action, not per rule. The notify_when field at the rule level is deprecated in favor of per-action frequency objects. If you set it at the rule level and later edit the rule in the Kibana UI, it is automatically converted to action-level values.

2. Use alert summaries to reduce notification noise. Instead of sending one notification per alert, configure actions to send periodic summaries at a custom interval. Use "summary": true and set a throttle interval. This is especially valuable for rules that monitor many hosts or documents.

3. Choose the right action frequency for each channel. Use onActionGroupChange for paging/ticketing systems (fire once, resolve once). Use onActiveAlert for audit logging to an Index connector. Use onThrottleInterval with a throttle like for dashboards or lower-priority notifications.

Common Pitfalls

1. Missingkbn-xsrf header. All POST, PUT, DELETE requests require kbn-xsrf: true or any truthy value. Omitting it returns a 400 error.

2. Wrongconsumer value. Using an invalid consumer (e.g., observability instead of infrastructure) causes a 400 error. Check the rule type's supported consumers via GET /api/alerting/rule_types.

3. Immutable fields on update. You cannot change rule_type_id or consumer with PUT. You must delete and recreate the rule.

4. Setting these at the rule level still works but conflicts with action-level frequency settings. Always use inside each action object.

Examples

Create a threshold alert: "Alert me when CPU exceeds 90% on any host for 5 minutes." Use rule_type_id: ".index-threshold", aggField: "system.cpu.total.pct", threshold: [0.9], and timeWindowSize: 5. Attach a PagerDuty action on "threshold met" and a matching Recovered action to auto-close incidents.

Find rules by tag: "Show all production alerting rules." GET /api/alerting/rules/_find with filter=alert.attributes.tags:"production" and sort_field=name to page through results.

Pause a rule temporarily: "Disable rule abc123 until next Monday." POST /api/alerting/rule/abc123/_disable. Re-enable with _enable when ready; the rule retains all configuration while disabled.

Guidelines

• Include kbn-xsrf: true on every POST, PUT, and DELETE; omitting it returns 400.
• Set frequency inside each action object — rule-level notify_when and throttle are deprecated.
• rule_type_id and consumer are immutable after creation; delete and recreate the rule to change them.
• Prefix paths with /s/<space_id>/api/alerting/ for non-default Kibana Spaces.
• Always pair an active action with a Recovered action to auto-close PagerDuty, Jira, and ServiceNow incidents.
• Run GET /api/alerting/rule_types first to discover valid values and action group names.

Additional Resources

• Kibana Alerting API Reference
• Alerting Concepts
• Create and Manage Rules (UI)
• Rule Action Variables
• Alerting Production Considerations
• Terraform: elasticstack_kibana_alerting_rule
• Terraform: Managing Kibana Rule and Connector Resources

Weekly Installs

143

Repository

elastic/agent-skills

GitHub Stars

89

First Seen

11 days ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykFail

Installed on

cursor129

github-copilot123

opencode122

gemini-cli122

codex122

amp121