Kibana アラーティングルール

コア概念

ルールは3つの部分で構成されます：conditions（検出対象）、schedule（チェック頻度）、actions（条件が満たされたときの処理）。条件が満たされると、ルールはalertsを生成し、connectors経由でactionsをトリガーします。

認証

すべてのアラーティング API 呼び出しには、API キー認証または Basic 認証が必要です。すべての変更リクエストには kbn-xsrf ヘッダーを含める必要があります。

kbn-xsrf: true

必要な権限

• 適切な Kibana フィーチャー（例：Stack Rules、Observability、Security）に対する all 権限
• アクションをルールに添付するための Actions と Connectors に対する read 権限

API リファレンス

ベースパス：<kibana_url>/api/alerting（または非デフォルトスペースの場合は /s/<space_id>/api/alerting）。

操作	メソッド	エンドポイント
ルール作成	POST	/api/alerting/rule/{id}
ルール更新	PUT	/api/alerting/rule/{id}
ルール取得	GET	/api/alerting/rule/{id}
ルール削除	DELETE	/api/alerting/rule/{id}
ルール検索	GET	/api/alerting/rules/_find
ルールタイプ一覧	GET	/api/alerting/rule_types
ルール有効化	POST	/api/alerting/rule/{id}/_enable
ルール無効化	POST	/api/alerting/rule/{id}/_disable
全アラート消音	POST	/api/alerting/rule/{id}/_mute_all
全アラート音復旧	POST	/api/alerting/rule/{id}/_unmute_all
アラート消音	POST	/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute
アラート音復旧	POST	/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute
API キー更新	POST	/api/alerting/rule/{id}/_update_api_key
スヌーズ作成	POST	/api/alerting/rule/{id}/snooze_schedule
スヌーズ削除	DELETE	/api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId}
ヘルスチェック	GET	/api/alerting/_health

ルールの作成

必須フィールド

フィールド	タイプ	説明
name	string	表示名（一意である必要はありません）
rule_type_id	string	ルールタイプ（例：.es-query、.index-threshold）
consumer	string	所有者アプリ：alerts、apm、discover、infrastructure、logs、metrics、ml、monitoring、securitySolution、siem、stackAlerts、uptime
params	object	ルールタイプ固有のパラメータ
schedule	object	チェック間隔（例：{"interval": "5m"}）

オプショナルフィールド

フィールド	タイプ	説明
actions	array	条件が満たされたときに実行するアクション（各々がコネクタを参照）
tags	array	ルールを整理するためのタグ
enabled	boolean	ルールが即座に実行されるかどうか（デフォルト：true）
notify_when	string	onActionGroupChange、onActiveAlert、または onThrottleInterval（アクションごと設定推奨）
alert_delay	object	N連続マッチ後にのみアラート（例：{"active": 3}）
flapping	object/null	フラッピング検出設定をオーバーライド

例：Elasticsearch クエリルールの作成

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"]
  }'

同じ構造が他のルールタイプにも適用されます。適切な rule_type_id（例：.index-threshold、.es-query）を設定し、対応する params オブジェクトを提供してください。GET /api/alerting/rule_types を使用してパラメータスキーマを確認できます。

ルールの更新

PUT /api/alerting/rule/{id} — 完全なルール本体を送信してください。rule_type_id と consumer は作成後は変更不可です。別のユーザーが同時にルールを更新した場合は 409 Conflict を返します。最新版を再取得して再試行してください。

ルールの検索

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

クエリパラメータ：per_page、page、search、default_search_operator、search_fields、sort_field、sort_order、has_reference、fields、filter、filter_consumers。

高度なクエリには filter パラメータを KQL 構文で使用します：

filter=alert.attributes.tags:"production"

ライフサイクル操作

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

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

# すべてのアラートを消音
curl -X POST ".../api/alerting/rule/{id}/_mute_all" -H "kbn-xsrf: true"

# 特定のアラートを消音
curl -X POST ".../api/alerting/rule/{rule_id}/alert/{alert_id}/_mute" -H "kbn-xsrf: true"

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

Terraform プロバイダー

elasticstack プロバイダーリソース 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"]
}

重要な Terraform ノート：

• params は jsonencode() 経由で JSON エンコード文字列として渡す必要があります
• elasticstack_kibana_action_connector データソースまたはリソースを使用してアクション内のコネクタ ID を参照します
• 既存ルールをインポート：terraform import elasticstack_kibana_alerting_rule.my_rule <space_id>/<rule_id>（デフォルトスペースは default を使用）

ルールから Kibana ワークフローをトリガーする

プレビュー機能 — Elastic Stack 9.3 および Elastic Cloud Serverless で利用可能。API は変更される場合があります。

ワークフローID をコネクタID として使用して、ワークフローをルールアクションとしてアタッチします。params: {} を設定します — アラートコンテキストはワークフロー内の event オブジェクトを通じて自動的に流れます。

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" }
      }
    ]
  }'

UI：Stack Management > Rules > Actions > Workflows。enabled: true のワークフローのみピッカーに表示されます。

ワークフロー YAML 構造、{{ event }} コンテキストフィールド、ステップタイプ、パターンについては、利用可能な場合は kibana-connectors スキルを参照してください。

ルール内のコネクタとアクション

各アクションはコネクタ ID、アクション group、アクション params（Mustache テンプレート使用）、およびアクションごとの frequency オブジェクトを参照します。主要フィールド：

• group — このアクションをトリガーするトリガー状態（例："query matched"、"Recovered"）。有効なグループは GET /api/alerting/rule_types で確認できます。
• frequency.summary — すべてのアラートのダイジェストの場合は true；アラートごとの場合は false。
• frequency.notify_when — onActionGroupChange | onActiveAlert | onThrottleInterval。
• frequency.throttle — 最小繰り返し間隔（例："10m"）；onThrottleInterval でのみ適用。

アクション構造、Mustache 変数（{{rule.name}}、{{context.*}}、{{alerts.new.count}}）、Mustache ラムダ（EvalMath、FormatDate、ParseHjson）、リカバリアクション、マルチチャネルパターンの詳細なリファレンスについては、利用可能な場合は kibana-connectors スキルを参照してください。

ベストプラクティス

1. ルールレベルではなく、アクションごとにアクション頻度を設定します。 ルールレベルの notify_when フィールドはアクションレベルの frequency オブジェクトに廃止予定です。ルールレベルで設定し、後で Kibana UI でルールを編集する場合、自動的にアクションレベルの値に変換されます。

2. アラートサマリーを使用して通知ノイズを削減します。 アラートごとに1つの通知を送信する代わりに、カスタム間隔で定期的なサマリーを送信するようにアクションを設定します。"summary": true を使用し、throttle 間隔を設定します。これは多くのホストまたはドキュメントを監視するルールに特に価値があります。

3. 各チャネルに対して適切なアクション頻度を選択します。 ページング/チケットシステムには onActionGroupChange を使用します（一度トリガーし、一度解決）。監査ログを Index コネクタに記録するには onActiveAlert を使用します。ダッシュボードまたは低優先度の通知には、"30m" のような throttle で onThrottleInterval を使用します。

4. 常にリカバリアクションを追加します。 リカバリアクションのないルールは、PagerDuty、Jira、ServiceNow のインシデントを無期限に開いたままにします。コネクタのネイティブな閉じる/解決イベントアクション（例：PagerDuty の場合は eventAction: "resolve"）を Recovered アクショングループで使用します。

5. 合理的なチェック間隔を設定します。 推奨される最小間隔は 1m です。多くのルール全体で非常に短い間隔は、Task Manager スループットを詰まらせ、スケジュールドリフトを増加させます。サーバー設定 xpack.alerting.rules.minimumScheduleInterval.value がこれを強制します。

6. alert_delay を使用して一時的なスパイクを抑制します。 {"active": 3} を設定すると、アラートは3つの連続実行が条件に一致した後にのみ発火され、簡潔な異常をフィルタリングします。

7. フラッピング検出を有効にします。 アクティブと復旧の間で急速に切り替わるアラートは「フラッピング」とマークされ、通知は抑制されます。これはデフォルトでオンですが、flapping オブジェクトでルールごとに調整できます。

8. server.publicBaseUrl を使用してディープリンクを作成します。 kibana.yml で server.publicBaseUrl を設定すると、通知内で {{rule.url}} および {{kibanaBaseUrl}} 変数が有効な URL に解決されます。

9. ルールに一貫してタグを付けます。 production、staging、team-platform などのタグを使用して、Find API および UI でフィルタリングと整理を行います。

10. Kibana Spaces を使用 してルールをチーム別または環境別に分離します。非デフォルトスペースの場合は API パスの前に /s/<space_id>/ を付けます。コネクタもスペーススコープされているため、各スペースで一致するコネクタを作成します。

よくある落とし穴

1. kbn-xsrf ヘッダーが見つかりません。 すべての POST、PUT、DELETE リクエストには kbn-xsrf: true または任意の真値が必要です。これを省略すると 400 エラーが返されます。

2. 誤った consumer 値。 無効なコンシューマー（例：observability の代わりに infrastructure）を使用すると、400 エラーが発生します。GET /api/alerting/rule_types によってルールタイプのサポートされているコンシューマーを確認します。

3. 更新時の不変フィールド。 PUT で rule_type_id または consumer を変更することはできません。ルールを削除して再作成する必要があります。

4. ルールレベルの notify_when と throttle は廃止予定。 ルールレベルでこれらを設定すると機能しますが、アクションレベルの周波数設定と競合します。常に各アクションオブジェクト内の frequency を使用します。

5. ルール ID の競合。 既存 ID で /api/alerting/rule/{id} に POST すると 409 が返されます。ID を省略して自動生成するか、最初に存在をチェックします。

6. API キー所有権。 ルールはそれらを作成または最後に更新したユーザーの API キーを使用して実行されます。そのユーザーの権限が変更されたり、ユーザーが削除された場合、ルールはサイレントに失敗する可能性があります。_update_api_key を使用して再関連付けします。

7. ルールごとのアクション数が多すぎます。 数千のアラートを複数のアクションで生成するルールは、Task Manager を詰まらせる可能性があります。サーバー設定 xpack.alerting.rules.run.actions.max（デフォルトは異なる）が実行ごとのアクション数を制限します。ルールを設計して、アラートサマリーを使用するか、用語サイズを制限します。

8. 長時間実行ルール。 高コストなクエリを実行するルールは、xpack.alerting.rules.run.timeout（デフォルト 5m）後にキャンセルされます。キャンセルされた場合、その実行からのすべてのアラートとアクションは破棄されます。クエリを最適化するか、特定のルールタイプのタイムアウトを増加させます。

9. 同時更新の競合。 最後に読み込んだ以降、別のユーザーがルールを変更した場合、PUT は 409 を返します。更新する前に常に最新版を GET してください。

10. インポート/エクスポートはシークレットを失います。 Saved Objects 経由でエクスポートされたルールはインポート時に無効になります。コネクタはシークレットを失い、再設定する必要があります。

例

閾値アラートを作成： 「任意のホストで CPU が 90% を超えて 5 分間続く場合、アラートしてください。」rule_type_id: ".index-threshold"、aggField: "system.cpu.total.pct"、threshold: [0.9]、timeWindowSize: 5 を使用します。"threshold met" で PagerDuty アクションをアタッチし、インシデントを自動的に閉じるための一致する Recovered アクションをアタッチします。

タグでルールを検索： 「すべての本番アラーティングルールを表示します。」GET /api/alerting/rules/_find に filter=alert.attributes.tags:"production" と sort_field=name を使用して結果をページング処理します。

一時的にルールを一時停止： 「ルール abc123 を次の月曜日まで無効化します。」POST /api/alerting/rule/abc123/_disable。準備ができたら _enable で再有効化します。ルールは無効化されている間、すべての設定を保持します。

ガイドライン

• すべての POST、PUT、DELETE に kbn-xsrf: true を含めます。これを省略すると 400 が返されます。
• frequency を各アクションオブジェクト内に設定します — ルールレベルの notify_when と throttle は廃止予定です。
• rule_type_id と consumer は作成後は変更不可です。変更するにはルールを削除して再作成します。
• 非デフォルト Kibana Spaces の場合は、パスの前に /s/<space_id>/api/alerting/ を付けます。
• アクティブアクションを常に Recovered アクションとペアリングして、PagerDuty、Jira、ServiceNow インシデントを自動的に閉じます。
• まず GET /api/alerting/rule_types を実行して、有効な consumer 値とアクショングループ名を確認します。
• alert_delay を使用して一時的なスパイクを抑制します。flapping オブジェクトを使用して不安定な条件からのノイズを減らします。

追加リソース

• 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