kibana-alerting-rules

Kibana アラートルール

Kibana アラートルールの作成、確認、更新、管理を行います。適切なルールタイプを選び、しきい値とグループ化のセマンティクスを設定し、依頼された場合にのみアクションを追加します。既存のカバレッジを調べるよう求められた場合は、ルールを読み取り専用で一覧表示または絞り込みます。

環境設定

このスキルは、elastic CLI を介して Elasticsearch の操作を実行します。 elastic CLI がインストールされていない場合は、何に必要なのかをユーザーに伝えてください。認証情報を推測したり、HTTP API を直接呼び出したり、ほかの回避策を試したりしないでください。

このスキルでは、HTTP の省略形で操作を記載しています（例：GET /、GET /_cat/indices、GET /{index}/_mapping、GET /{index}/_settings/index.mode、POST /_query）。このドキュメントの末尾にある操作の表には、各省略形に相当する elastic CLI コマンドが記載されています。HTTP API を直接呼び出すのではなく、必ず CLI を使用してください。

基本概念

ルールは、条件（params + rule_type_id）、スケジュール（条件をチェックする頻度）、アクション（アラート発生時に実行する任意のコネクター）の3つで構成されます。条件が満たされると、ルールによってアラートが作成され、アクションによってコネクター経由で通知が配信されます。ユーザーが通知の設定を明示的に依頼しない限り、コネクターやアクションを作成しないでください。ルールの定義だけで十分なタスクも多くあります。

必要な権限：対象の Kibana 機能（Stack Rules、Observability、Security など）で all、および Rules Settings で all。コネクターの管理には Actions and Connectors で all が必要です。ルールアクションとして既存のコネクターを追加するだけなら read で十分です。

**オンプレミスでの前提条件：**ルールを作成する前に、kibana.yml で安定した xpack.encryptedSavedObjects.encryptionKey を設定してください。このキーはルールの API キーとコネクターのシークレットを暗号化します。未設定の場合、再起動のたびにキーが再生成され、既存のルールが動作しなくなります。クラスター内のすべての Kibana ノードで同じキーを使用する必要があります。

手順

1. タスクを分類します。ユーザーが求めているのが、ルールの作成、ルールの検索／一覧表示（読み取り専用）、既存ルールの更新、またはライフサイクルの変更（有効化、無効化、ミュート、スヌーズ、削除）のいずれかを判断します。ルールの表示または一覧表示のみを求められた場合は、読み取り専用の依頼として扱い、作成、更新、有効化、削除を行わないでください。

2. **検索／一覧表示タスクでは、適切に絞り込み、ページ分割します。**結果をすべて出力するのではなく、検索結果を絞り込むクエリパラメーターを指定して GET kbn:/api/alerting/rules/_find を呼び出します。

   • タグで絞り込む場合：filter=alert.attributes.tags:"production"（保存オブジェクトの属性に対する KQL）。
   • **テキストで絞り込む場合：**必要に応じて search_fields と default_search_operator を指定して search を使用します。
   • **ページ分割：**結果が1ページを超える可能性がある場合は per_page を設定し、page を変えて繰り返します。
   • **並べ替え：**安定した一覧にするには sort_field=name と sort_order=asc を指定します。

   一致したルールの ID と名前を列挙します。一致するルールがない場合は、その旨を明確に伝え、結果を作り上げないでください。コネクターやストリームではなく、アラートルールを検索してください。

3. **作成タスクでは、パラメーターを記述する前にルールタイプを選びます。**ユーザーの意図に合ったメトリック／しきい値ルールタイプを選びます。ログ、異常検知、または無関係なタイプは選ばないでください。

   • 時間枠内の数値メトリック（ホスト／サービス単位でのグループ化は任意） → .index-threshold を consumer: "stackAlerts" と組み合わせます。
   • ドキュメント数または Query DSL 条件 → .es-query を consumer: "stackAlerts" と組み合わせます。
   • Metrics アプリの Observability メトリック → metrics.alert.threshold を consumer: "metrics" または "infrastructure" と組み合わせます。

   パラメータースキーマ、有効なコンシューマー、アクショングループについては、rule-types-reference.md を参照してください。ユーザーがインデックス、フィールド、しきい値、期間、グループ化フィールドを指定した場合は、4つすべてを params に明示的に設定してください。条件の代わりにコネクターやアクションを使用しないでください。

4. しきい値、継続時間、グループ化を正しく設定します。 これら3つの要素はそれぞれ独立しています。

   • しきい値： 集計値に対して threshold と thresholdComparator を設定します。フィールドのスケールに合わせます。ECS の system.cpu.total.pct は通常、小数表記です（90％の場合は 0.9）。90 を使用するのは、フィールドが0～100のスケールの場合に限ります。
   • 「N分間」： params に timeWindowSize と timeWindowUnit を設定します（各実行時に評価されるルックバック期間です）。 この期間に schedule.interval を合わせます（たとえば、両方を5分に設定します）。これにより、短時間の急増が異なる実行間隔で検出されてアラートを発するのを防げます。ユーザーが単一のルックバック期間ではなく、N 回連続で条件に一致することを望む場合にのみ、alert_delay: {"active": N} を追加します。
   • ホスト／エンティティごとのグループ化： .index-threshold では、groupBy: "top" を設定し、termField にグループ化フィールド（例：host.name）を指定して、すべてのエンティティを対象にするのに十分な termSize（「任意のホスト」）を設定します。グループ化しない場合、ルールは全体を集計するため、ホストごとにアラートを発しません。

5. 作成用のペイロードを作成します。 必須フィールド：name、rule_type_id、consumer、schedule、params。任意フィールド： tags、enabled、actions、alert_delay、flapping。ユーザーがルール ID を指定した場合は URL にその ID を使用します。 それ以外の場合は、Kibana に生成させます。

   パラメーターの例 — eval-alert-metrics に対し、任意のホストでCPU使用率が5分間90％を超えた場合：

   {
     "name": "CPU exceeds 90% for 5 minutes",
     "rule_type_id": ".index-threshold",
     "consumer": "stackAlerts",
     "schedule": { "interval": "5m" },
     "params": {
       "index": ["eval-alert-metrics"],
       "timeField": "@timestamp",
       "aggType": "avg",
       "aggField": "system.cpu.total.pct",
       "groupBy": "top",
       "termField": "host.name",
       "termSize": 1000,
       "threshold": [0.9],
       "thresholdComparator": ">",
       "timeWindowSize": 5,
       "timeWindowUnit": "m"
     },
     "tags": ["production"]
   }
   

   ユーザーがルール条件の作成のみを求めている場合は、actions を省略します。

6. 作成して確認します。 ペイロードを指定して POST kbn:/api/alerting/rule/{id} を呼び出します。409 Conflict の場合は ID がすでに存在します。確認するには GET kbn:/api/alerting/rule/{id} を呼び出すか、別の ID を選択します。作成に成功したら GET kbn:/api/alerting/rule/{id} を呼び出し、Kibana 上で確認してから、実際のルール ID、名前、有効状態をユーザーに伝えます。Kibana で確認する前に成功したと伝えてはいけません。

7. 更新タスクでは、読み取ってから置き換えます。 rule_type_id と consumer は変更できません。GET kbn:/api/alerting/rule/{id} を呼び出し、意図した変更を統合してから、完全なルール本文を指定して PUT kbn:/api/alerting/rule/{id} を呼び出します。409 Conflict の場合は、別のユーザーがルールを変更しています。再取得して再試行します。アクションごとに frequency オブジェクトを設定します。ルールレベルの notify_when と throttle は非推奨です。

8. ライフサイクルタスクでは、必要最小限のエンドポイントを呼び出します。 一時的に無効にするには POST kbn:/api/alerting/rule/{id}/_disable を呼び出します（ルールの設定は保持されます）。再度有効にするには POST kbn:/api/alerting/rule/{id}/_enable を呼び出します。すべてのアラートをミュートするには POST kbn:/api/alerting/rule/{id}/_mute_all を呼び出し、解除するには POST kbn:/api/alerting/rule/{id}/_unmute_all を呼び出します。アクティブなアラートを1つだけミュートするには POST kbn:/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute を呼び出し、解除するには POST kbn:/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute を呼び出します。スケジュールされたスヌーズを設定するには POST kbn:/api/alerting/rule/{id}/snooze_schedule を呼び出し、削除するには DELETE kbn:/api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId} を呼び出します。完全に削除するには DELETE kbn:/api/alerting/rule/{id} を呼び出します。API キーの所有権が原因でルールが失敗する場合は、 POST kbn:/api/alerting/rule/{id}/_update_api_key を呼び出します。

例

しきい値アラートを作成する

ユーザー：「任意のホストでCPU使用率が5分間90％を超えたらアラートしてください。クエリは eval-alert-metrics を使用します（system.cpu.total.pct を host.name でグループ化）。ID eval-cpu-rule でルールを作成してください。」

1. .index-threshold／stackAlerts を選択します。
2. 小数のしきい値 [0.9]、5分間の timeWindowSize／timeWindowUnit、および host.name に対する groupBy／termField を設定します。
3. schedule.interval: "5m" を指定して POST kbn:/api/alerting/rule/eval-cpu-rule を呼び出します。アクションは省略します。
4. GET kbn:/api/alerting/rule/eval-cpu-rule を呼び出し、結果をユーザーに伝えます。

タグでルールを検索する（読み取り専用）

ユーザー：「すべての本番環境のアラートルールを表示してください。」

1. GET kbn:/api/alerting/rules/_find を実行し、filter=alert.attributes.tags:"production"、適切な per_page、および sort_field=name を指定します。
2. total が per_page を超える場合は、ページを移動して結果を取得します。
3. ID と名前のみを報告します。変更は行いません。

ルールを一時的に一時停止する

ユーザー：「ルール abc123 を次の月曜日まで無効にしてください。」

1. POST kbn:/api/alerting/rule/abc123/_disable を実行します。
2. 後で POST kbn:/api/alerting/rule/abc123/_enable を実行して再有効化します。

複数のルールにまたがる計画的なダウンタイムでは、各ルールを個別に無効化またはスヌーズするより、メンテナンスウィンドウを使用してください。

ガイドライン

• 各アクションオブジェクト内で frequency を設定します。ルールレベルの notify_when と throttle は非推奨です。
• rule_type_id と consumer は作成後に変更できません。変更するには削除して再作成してください。
• デフォルト以外の Kibana Spaces では、パスの先頭に kbn:/s/<space_id>/api/alerting/ を付けます（コネクターもスペースごとにスコープされます）。
• ルールアクションで別のスペースのコネクターを参照することはできません。ルールとそのコネクターは同じ Space に属している必要があります。
• PagerDuty、Jira、ServiceNow では、アクティブな通知アクションと Recovered アクションを組み合わせます。
• 連続した一致を必須にするには alert_delay を使用し、不安定なアラートを抑制するにはフラッピング設定を使用します。flapping オブジェクトによるルールごとの調整は 9.3 以降で GA です。それ以前のバージョンでは、スペースレベルのフラッピング設定のみをサポートしています。
• アクションテンプレートをデバッグするには、任意のテンプレートフィールドで {{{.}}} を使用します。これにより変数コンテキスト全体が JSON として出力され、{{context.reason}} や {{alert.flapping}} のような正しいパスの確認に役立ちます。
• Security の検出ルールにはこのスキルを使用しないでください。consumer: "securitySolution"／"siem" は専用の Security Detections API（/api/detection_engine/rules）に属しており、ルールタイプ ID とライフサイクルが異なります。
• find API でフィルタリングできるように、ルールには一貫したタグ（production、staging、チーム名）を付けます。
• 推奨される最小チェック間隔は 1m です。高負荷なルールは、サーバー実行タイムアウト（デフォルトは 5m）後にキャンセルされます。

よくある問題

1. ルールタイプの誤り — メトリックのしきい値条件にログルールまたは ML ルールを使用している。
2. エンティティごとのグループ化の欠落 — ユーザーが「任意のホスト」または「サービスごと」と指定しているのに、全体を集約している。
3. しきい値のスケールの不一致 — 小数値の CPU フィールドで 90 と 0.9 を取り違えている。
4. 期間とスケジュールの混同 — 1 分間隔のスケジュールと 5 分間のウィンドウは、どちらも 5 分に設定した場合とは動作が異なります。
5. 依頼されていないアクション — ユーザーがルールの作成のみを依頼しているのに、コネクターを追加している。
6. 読み取り専用の制約違反 — ユーザーが一覧表示またはフィルタリングのみを依頼しているのに、ルールを作成または変更している。
7. 同時更新の競合 — 最新の GET を行わずに PUT すると 409 が返される。
8. インポート／エクスポート — 保存オブジェクトをインポートするとルールが無効化され、コネクターのシークレットが削除される。

参考資料

• rule-types-reference.md — ルールタイプ、パラメーター、コンシューマー、アクショングループ
• connectors-actions-terraform.md — アクション、ワークフロー、Terraform
• Kibana Alerting API
• アラートの概念
• ルールアクション変数
• アラートに関する本番環境での考慮事項

オペレーション

HTTP API (shorthand)	elastic CLI command
GET kbn:/api/alerting/rules/_find	elastic kb alerting get-alerting-rules-find [--filter '<kql>'] [--search '<q>'] [--per-page <n>] [--page <n>] [--sort-field <field>] [--sort-order asc|desc]
POST kbn:/api/alerting/rule/{id}	elastic kb alerting post-alerting-rule-id --id '<id>' --name '<name>' --rule-type-id '<type>' --consumer '<consumer>' --schedule '<json>' --params '<json>' [--tags '<json>'] [--actions '<json>'] [--enabled]
GET kbn:/api/alerting/rule/{id}	elastic kb alerting get-alerting-rule-id --id '<id>'
PUT kbn:/api/alerting/rule/{id}	elastic kb alerting put-alerting-rule-id --id '<id>' --name '<name>' --schedule '<json>' --params '<json>' [--tags '<json>'] [--actions '<json>']
DELETE kbn:/api/alerting/rule/{id}	elastic kb alerting delete-alerting-rule-id --id '<id>'
POST kbn:/api/alerting/rule/{id}/_enable	elastic kb alerting post-alerting-rule-id-enable --id '<id>'
POST kbn:/api/alerting/rule/{id}/_disable	elastic kb alerting post-alerting-rule-id-disable --id '<id>' [--untrack]
POST kbn:/api/alerting/rule/{id}/_mute_all	elastic kb alerting post-alerting-rule-id-mute-all --id '<id>'
POST kbn:/api/alerting/rule/{id}/_unmute_all	elastic kb alerting post-alerting-rule-id-unmute-all --id '<id>'
POST kbn:/api/alerting/rule/{id}/_update_api_key	elastic kb alerting post-alerting-rule-id-update-api-key --id '<id>'
POST kbn:/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute	elastic kb alerting post-alerting-rule-rule-id-alert-alert-id-mute --rule-id '<rule_id>' --alert-id '<alert_id>'
POST kbn:/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute	elastic kb alerting post-alerting-rule-rule-id-alert-alert-id-unmute --rule-id '<rule_id>' --alert-id '<alert_id>'
POST kbn:/api/alerting/rule/{id}/snooze_schedule	elastic kb alerting post-alerting-rule-id-snooze-schedule --id '<id>' --schedule '<json>'
DELETE kbn:/api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId}	elastic kb alerting delete-alerting-rule-ruleid-snooze-schedule-scheduleid --rule-id '<ruleId>' --schedule-id '<scheduleId>'