elasticsearch-anomaly-detection

Elasticsearch 異常検知

時系列データに対して、ML 異常検知ジョブを作成、オープンし、開始します。適切なカウントファミリーの検出器の方向を選択し、バケットの間隔と時間フィールドを設定し、データフィードを正しいインデックスに接続して、推測ではなく統計情報で実行状態を確認します。

環境設定

このスキルは、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 を使用してください。

前提条件： ML 異常検知をセルフマネージドクラスターで使用するには、Platinum 相当のライセンスが必要です。Serverless プロジェクトには ML が含まれます。ジョブを作成および管理するには、呼び出し元に manage_ml 権限が必要です。

関連スキル： ジョブの実行開始後に異常スコア、影響要因、モデルの動作を解釈するには、このスキルではなく elasticsearch-anomaly-detection-explainer を使用してください。

プロセス

1. 対象インデックスと時間フィールドを特定します。 GET /_cat/indices で候補となるインデックスを一覧表示します（ユーザーがインデックス名を指定した場合はパターンを渡します）。選択したインデックスのフィールド型を GET /{index}/_mapping で取得します。判断時には、インデックスが存在することを確認し、時間フィールド（多くの場合は @timestamp）を特定し、ベースライン学習に十分なドキュメント量があることを検証します。インデックス名やフィールド名を推測してはいけません。デプロイ環境によって異なります。

2. 検出関数と方向を選択します。 ユーザーの意図を analysis_config.detectors のカウント系検出器に対応させます。

   • イベント量の急増、増加、異常な上昇 → high_count（または、ユーザーが急増に関心がある場合は、両方向を検知する count でも構いません）。low_count は使用しないでください。急増を見逃します。
   • 減少、停止、イベントの欠如、トラフィックの停止 → low_count。high_count は使用しないでください。減少や無音状態を見逃します。
   • メトリックの逸脱（CPU、レイテンシ、数値フィールド）→ field_name を設定した平均系関数（mean、high_mean、low_mean）。ユーザーが生のイベント量ではなく、数値メトリックについて尋ねている場合に限ります。

   判断時には、異常の種類と方向が一致する主検出器を1つ選択します。ドキュメント数に関する量の急増・減少の質問では、カウント系を使用します。平均系検出器は「イベント数」に関する質問には適していません。

3. 作成前に変更不可のジョブ構成を設定します。 これらのフィールドは PUT /_ml/anomaly_detectors/{job_id} の後に変更できません。

   • analysis_config.bucket_span — ユーザーが指定した間隔を使用します（例：15分間隔のバケットには 15m）。対象とする異常の粒度に合わせます。短すぎるとノイズが多くなり、長すぎると検出が遅くなります。
   • data_description.time_field — マッピングにある時間フィールド（一般的には @timestamp）。
   • analysis_config.detectors — 手順2で選択した関数と方向。

   量の急増を検出するジョブの本文例：

   {
     "analysis_config": {
       "bucket_span": "15m",
       "detectors": [{ "function": "high_count" }]
     },
     "data_description": { "time_field": "@timestamp" }
   }
   

   停止・減少を検出する例：

   {
     "analysis_config": {
       "bucket_span": "15m",
       "detectors": [{ "function": "low_count" }]
     },
     "data_description": { "time_field": "@timestamp" }
   }
   

4. ジョブを作成します。 ユーザーが指定したジョブ ID（または提案する説明的な ID）を指定して、PUT /_ml/anomaly_detectors/{job_id} を呼び出します。ジョブは closed 状態で開始します。作成しても分析は開始されません。

5. データフィードを作成します。 ジョブ作成の直後に PUT /_ml/datafeeds/datafeed-{job_id} を呼び出します。job_id には同じ ID を設定し、indices には対象インデックス（手順1で確認した正確な名前またはパターン）を設定します。また、関連するドキュメントを選択するクエリ（通常は match_all）を指定します。データフィード ID の規則は datafeed-{job_id} です。

   {
     "job_id": "{job_id}",
     "indices": ["{index}"],
     "query": { "match_all": {} }
   }
   

6. ジョブを開いてから、データフィードを開始します。この順序は必須です。省略したり、順序を入れ替えたりしないでください。

   1. POST /_ml/anomaly_detectors/{job_id}/_open — ジョブを opened に遷移させます。
   2. POST /_ml/datafeeds/datafeed-{job_id}/_start — データフィードを started に遷移させます。

   データフィードが存在する前にジョブを開こうとすると失敗します。ジョブを開く前にデータフィードを開始しようとしても失敗します。リソースを作成しただけで成功を報告してはいけません。両方がアクティブになるまで、ジョブは実行されていません。

7. 統計情報から実行状態を確認します。 次の項目で結果を検証します。

   • GET /_ml/anomaly_detectors/{job_id}/_stats — state: "opened" であることを確認します。
   • GET /_ml/datafeeds/datafeed-{job_id}/_stats — state: "started" であることを確認します。

   必要に応じて GET /_ml/anomaly_detectors/{job_id} を呼び出し、構成（検出器、bucket_span、time_field、データフィードのインデックス）を確認します。両方の統計状態を明示的に報告します。「created」は「opened」や「started」と同じではありません。

ティアダウン

ジョブを停止または削除するときは、起動時と逆の順序で操作します。

1. POST /_ml/datafeeds/datafeed-{job_id}/_stop — 最初にデータフィードを停止します。
2. POST /_ml/anomaly_detectors/{job_id}/_close — 次にジョブを閉じます。

ジョブを閉じる前にデータフィードを停止します。リセットまたは削除する前に、ジョブを閉じます。

ガイドライン

• 作成時に必須となるライフサイクルの順序： ジョブ → データフィード → ジョブを開く → データフィードを開始する。新しいジョブはすべて、この順序に従います。
• ボリューム異常で最も影響が大きい判断は、検出器の方向です。 ユーザーの表現を読み直してください。「急増」「急上昇」「異常な増加」→ high 方向、「減少」「停止」「止まる」「欠如」→ low 方向。
• 不変フィールド（bucket_span、検出器、time_field）に誤りがある場合は、削除して再作成する必要があります。最初の PUT の前に、マッピングと意図を確認してください。
• データフィードのインデックスは、ユーザーが指定した対象と一致させる必要があります。 indices には、指定された正確なインデックスまたはパターンを設定してください。近いものを推測して使わないでください。
• エンティティレベルの分析（by_field_name、over_field_name、partition_field_name）と高度な調整については、references/anomaly-detection-reference.md を参照してください。

全リファレンス

API パス、リクエスト／レスポンスのフィールド、スコアの意味、フィールド間の相互作用については、 references/anomaly-detection-reference.md を参照してください。

操作

HTTP API（略記）	elastic CLI コマンド
GET /_cat/indices	elastic es cat indices --index '<pattern>'
GET /{index}/_mapping	elastic es indices get-mapping --index '<index>'
PUT /_ml/anomaly_detectors/{job_id}	elastic es ml put-job --job-id '<job_id>' --analysis-config '<json>' --data-description '<json>'
PUT /_ml/datafeeds/datafeed-{job_id}	elastic es ml put-datafeed --datafeed-id 'datafeed-<job_id>' --job-id '<job_id>' --indices '<index>' --query '<json>'
POST /_ml/anomaly_detectors/{job_id}/_open	elastic es ml open-job --job-id '<job_id>'
POST /_ml/datafeeds/datafeed-{job_id}/_start	elastic es ml start-datafeed --datafeed-id 'datafeed-<job_id>'
GET /_ml/anomaly_detectors/{job_id}	elastic es ml get-jobs --job-id '<job_id>'
GET /_ml/anomaly_detectors/{job_id}/_stats	elastic es ml get-job-stats --job-id '<job_id>'
GET /_ml/datafeeds/datafeed-{job_id}/_stats	elastic es ml get-datafeed-stats --datafeed-id 'datafeed-<job_id>'
POST /_ml/datafeeds/datafeed-{job_id}/_stop	elastic es ml stop-datafeed --datafeed-id 'datafeed-<job_id>'
POST /_ml/anomaly_detectors/{job_id}/_close	elastic es ml close-job --job-id '<job_id>'