異常検知ジョブAPIの作成

異常検知ジョブをインスタンス化します。

リクエスト

PUT _ml/anomaly_detectors/<job_id>

前提条件

manage_ml クラスター権限が必要です。この権限は machine_learning_admin ビルトインロールに含まれています。

datafeed_config を含める場合、ソースインデックスに対して read インデックス権限も必要です。

説明

  • 異常検知ジョブを作成するには、Kibana またはこの API を使用する必要があります。Elasticsearch インデックス API を使用して .ml-config インデックスに直接ジョブを配置しないでください。Elasticsearch のセキュリティ機能が有効になっている場合、.ml-config インデックスに対してユーザーに write 権限を与えないでください。
  • datafeed_config を含め、Elasticsearch のセキュリティ機能が有効になっている場合、データフィードは作成時にそれを作成したユーザーが持っていたロールを記憶し、同じロールを使用してクエリを実行します。二次認証ヘッダーを提供した場合、それらの資格情報が代わりに使用されます。

パスパラメータ

  • <job_id>
  • (必須、文字列) 異常検知ジョブの識別子。この識別子は小文字の英数字 (a-z および 0-9)、ハイフン、アンダースコアを含むことができます。英数字で始まり、英数字で終わる必要があります。

Request body

  • allow_lazy_open

  • (オプション、ブール値) 高度な設定オプション。このジョブが、ノードに即座に割り当てられるための機械学習ノードの容量が不足している場合に開くことができるかどうかを指定します。デフォルト値は false です。ジョブを実行するための容量を持つ機械学習ノードがすぐに見つからない場合、異常検出ジョブを開くAPI はエラーを返します。ただし、これはクラスター全体の xpack.ml.max_lazy_ml_nodes 設定にも影響されます。詳細は 高度な機械学習設定 を参照してください。このオプションが true に設定されている場合、異常検出ジョブを開くAPI はエラーを返さず、ジョブは opening 状態で待機し、十分な機械学習ノードの容量が利用可能になるまで待機します。

  • analysis_config

  • (必須、オブジェクト) データを分析する方法を指定する分析設定。ジョブを作成した後は、分析設定を変更することはできません。すべてのプロパティは情報提供用です。
    analysis_config のプロパティ

    • bucket_span
    • (時間単位) 分析が集約される間隔のサイズ。通常、5m と 1h の間です。この値は、日数の整数または1日のバケットの整数に相当する必要があります。[8.1] 8.1で非推奨。これらの推奨事項を満たさない値は非推奨とされ、将来のバージョンで許可されなくなります。異常検出ジョブが集約を持つデータフィードを使用する場合、この値は日付ヒストグラム集約の間隔で割り切れる必要があります。デフォルト値は 5m です。詳細については、バケットスパン を参照してください。
    • categorization_analyzer
    • (オブジェクトまたは文字列) categorization_field_name が指定されている場合、カテゴリフィールドを解釈するために使用されるアナライザーを定義することもできます。このプロパティは categorization_filters と同時に使用することはできません。カテゴリ化アナライザーは、categorization_field がカテゴリ化プロセスによってどのように解釈されるかを指定します。構文は、分析エンドポイント で analyzer を定義するために使用されるものと非常に似ています。詳細については、ログメッセージのカテゴリ化 を参照してください。
      categorization_analyzer フィールドは、文字列またはオブジェクトとして指定できます。文字列の場合、組み込みアナライザー または他のプラグインによって追加されたものを参照する必要があります。オブジェクトの場合、次のプロパティがあります:
      categorization_analyzer のプロパティ
      • char_filter
      • (文字列またはオブジェクトの配列) 1つ以上の文字フィルター。組み込みの文字フィルターに加えて、他のプラグインが追加の文字フィルターを提供することがあります。このプロパティはオプションです。指定されていない場合、カテゴリ化の前に文字フィルターは適用されません。アナライザーの他の側面をカスタマイズしている場合、categorization_filters の同等物を達成する必要がある場合は、ここにパターン置換文字フィルターとして追加してください。
      • tokenizer
      • (文字列またはオブジェクト) 文字フィルターが適用された後に使用するトークナイザー の名前または定義。このプロパティは、categorization_analyzer がオブジェクトとして指定されている場合は必須です。機械学習は、英語のさまざまなログファイル形式で良好なカテゴリ化結果を生成することが確認された方法でトークン化する ml_standard というトークナイザーを提供します。そのトークナイザーを使用したいが、文字またはトークンフィルターを変更したい場合は、"tokenizer": "ml_standard" を categorization_analyzer に指定してください。さらに、ml_classic トークナイザーも利用可能で、製品の古いバージョン（6.2以前）のカスタマイズ不可能なトークナイザーと同じ方法でトークン化します。ml_classic は、バージョン 6.2 から 7.13 までのデフォルトのカテゴリ化トークナイザーであるため、これらのバージョンで作成されたジョブのデフォルトと同じカテゴリ化が必要な場合は、"tokenizer": "ml_classic" を categorization_analyzer に指定してください。
        Elasticsearch 8.10.0 から、機械学習プラグインの設定と状態の変更を追跡するために新しいバージョン番号が使用されます。この新しいバージョン番号は、製品バージョンから切り離されており、独立して増加します。
      • filter
      • (文字列またはオブジェクトの配列) 1つ以上のトークンフィルター。組み込みのトークンフィルターに加えて、他のプラグインが追加のトークンフィルターを提供することがあります。このプロパティはオプションです。指定されていない場合、カテゴリ化の前にトークンフィルターは適用されません。
    • categorization_field_name
    • (文字列) このプロパティが指定されている場合、指定されたフィールドの値がカテゴリ化されます。結果のカテゴリは、by_field_name、over_field_name、または partition_field_name を設定してキーワード mlcategory を使用することによって、検出器で使用されなければなりません。詳細については、ログメッセージのカテゴリ化 を参照してください。
    • categorization_filters
    • (文字列の配列) categorization_field_name が指定されている場合、オプションのフィルターを定義することもできます。このプロパティは正規表現の配列を期待します。これらの式は、カテゴリ化フィールドの値から一致するシーケンスをフィルタリングするために使用されます。この機能を使用して、カテゴリが定義される際に考慮されるシーケンスを除外することで、カテゴリ化を微調整できます。たとえば、ログファイルに表示されるSQL文を除外できます。詳細については、ログメッセージのカテゴリ化 を参照してください。このプロパティは categorization_analyzer と同時に使用することはできません。トークン化の前に適用される単純な正規表現フィルターを定義したい場合、このプロパティを設定するのが最も簡単な方法です。トークナイザーやトークン化後のフィルタリングをカスタマイズしたい場合は、categorization_analyzer プロパティを代わりに使用し、フィルターを pattern_replace 文字フィルターとして含めてください。効果はまったく同じです。
    • detectors
    • (配列) 検出器設定オブジェクトの配列。検出器設定オブジェクトは、ジョブが分析するデータフィールドを指定します。また、使用される分析関数も指定します。ジョブに対して複数の検出器を指定できます。
      detectors 配列に少なくとも1つの検出器が含まれていない場合、分析は行われず、エラーが返されます。
      detectors のプロパティ
      • by_field_name
      • (文字列) データを分割するために使用されるフィールド。特に、このプロパティは、自分の履歴に関して分割を分析するために使用されます。分割の文脈で異常な値を見つけるために使用されます。
      • custom_rules
      • (配列) 検出器の動作をカスタマイズするためのカスタムルールオブジェクトの配列。たとえば、ルールは、結果をスキップすべき条件を検出器に指示することがあります。Kibanaでは、カスタムルールをジョブルールと呼びます。詳細な例については、カスタムルールで検出器をカスタマイズする を参照してください。
        custom_rules のプロパティ
      • actions
      • (配列) ルールが適用されるときにトリガーされるアクションのセット。複数のアクションが指定されている場合、すべてのアクションの効果が組み合わされます。利用可能なアクションには次のものが含まれます:
        • skip_result: 結果は作成されません。これがデフォルト値です。skip_model_update も指定しない限り、モデルは通常通り対応する系列値で更新されます。
        • skip_model_update: その系列の値はモデルの更新に使用されません。skip_result も指定しない限り、結果は通常通り作成されます。このアクションは、特定の値が一貫して異常であると予想され、それが他の結果に悪影響を与える方法でモデルに影響を与える場合に適しています。
      • conditions
      • (配列) ルールが適用されるときのオプションの数値条件。ルールは、空でないスコープまたは少なくとも1つの条件を持っている必要があります。複数の条件は論理 AND で組み合わされます。条件には次のプロパティがあります:
        conditions のプロパティ
        • applies_to
        • (文字列) 条件が適用される結果プロパティを指定します。利用可能なオプションは actual、typical、diff_from_typical、time です。検出器が lat_long、metric、rare、または freq_rare 関数を使用している場合、time に適用される条件のみを指定できます。
        • operator
        • (文字列) 条件演算子を指定します。利用可能なオプションは gt (より大きい)、gte (より大きいまたは等しい)、lt (より小さい)、および lte (より小さいまたは等しい) です。
        • value
        • (倍精度) applies_to フィールドに対して operator を使用して比較される値。
      • scope
      • (オブジェクト) ルールが適用される系列のオプションのスコープ。ルールは、空でないスコープまたは少なくとも1つの条件を持っている必要があります。デフォルトでは、スコープはすべての系列を含みます。スコープは、by_field_name、over_field_name、または partition_field_name にも指定されているフィールドのいずれかに対して許可されます。フィールドのスコープを追加するには、スコープオブジェクト内にフィールド名をキーとして追加し、その値を次のプロパティを持つオブジェクトに設定します:
        scope のプロパティ
        • filter_id
        • (文字列) 使用するフィルターのID。
        • filter_type
        • (文字列) include (フィルター内の値にルールが適用される) または exclude (フィルター内でない値にルールが適用される) のいずれか。デフォルトは include です。
      • detector_description
      • (文字列) 検出器の説明。たとえば、Low event rate。
      • detector_index
      • (整数) 検出器の一意の識別子。この識別子は、analysis_config 内の検出器の順序に基づいており、ゼロから始まります。
        このプロパティに値を指定した場合、それは無視されます。
      • exclude_frequent
      • (文字列) 次のいずれかの値を含みます: all、none、by、または over。設定されている場合、頻繁なエンティティは異常結果に影響を与えることが除外されます。エンティティは、時間の経過とともに頻繁であるか、集団内で頻繁であると見なされることがあります。両方のフィールドでオーバーおよびバイを使用している場合、exclude_frequent を両方のフィールドに all に設定するか、by または over に設定できます。
      • field_name
      • (文字列) 検出器が関数で使用するフィールド。このフィールドを指定しないでください。イベントレート関数（count または rare など）を使用する場合。
        field_name には二重引用符またはバックスラッシュを含めることはできません。
      • function
      • (文字列) 使用される分析関数。たとえば、count、rare、mean、min、max、および sum。詳細については、関数リファレンス を参照してください。
      • over_field_name
      • (文字列) データを分割するために使用されるフィールド。特に、このプロパティは、すべての分割の履歴に関して分割を分析するために使用されます。すべての分割の集団における異常な値を見つけるために使用されます。詳細については、集団分析の実行 を参照してください。
      • partition_field_name
      • (string) 分析をセグメント化するために使用されるフィールド。このプロパティを使用すると、このフィールドの各値に対して完全に独立したベースラインが得られます。
      • use_null
      • (Boolean) by または partition フィールドに値がない場合に、新しい系列が null 系列として使用されるかどうかを定義します。デフォルト値は false です。
    • influencers
    • (array of strings) インフルエンサーのフィールド名のカンマ区切りリスト。通常、これらはデテクタ構成で使用される by、over、または partition フィールドです。また、デテクタに特に名前が付けられていないフィールド名を使用することもできますが、入力データの一部として利用可能です。複数のデテクタを使用する場合、インフルエンサーの使用が推奨されます。これは、各インフルエンサーエンティティの結果を集約します。
    • latency
    • (time units) 時間順序が乱れたデータを期待するウィンドウのサイズ。デフォルト値は 0（遅延なし）です。非ゼロの値を指定する場合は、1 秒以上である必要があります。時間単位の詳細については、時間単位を参照してください。
      遅延は、post data API を使用してデータを送信する場合にのみ適用されます。
    • model_prune_window
    • (Optional, time units) 高度な構成オプション。指定された時間の間に更新されていないモデルのプルーニングに影響します。値は bucket_span の倍数に設定する必要があります。値が低すぎると、モデルから重要な情報が削除される可能性があります。通常、30d 以上に設定します。設定しない場合、モデルのプルーニングは、モデルメモリの状態がソフトリミットまたはハードリミットに達した場合にのみ発生します。バージョン 8.1 以降に作成されたジョブのデフォルト値は、30d または bucket_span の 20 倍の大きい方です。
    • multivariate_by_fields
    • (Boolean) この機能は内部使用のために予約されています。顧客環境での使用はサポートされておらず、公式 GA 機能のサポート SLA の対象ではありません。
      true に設定すると、分析は指定された by フィールド値のメトリック間の相関関係を自動的に見つけ、これらの相関関係が維持されなくなると異常を報告します。たとえば、ホスト A の CPU とメモリ使用率がホスト B の同じメトリックと通常高い相関関係があるとします。この相関関係は、負荷分散されたアプリケーションを実行しているために発生する可能性があります。このプロパティを有効にすると、たとえばホスト A の CPU 使用率が高く、ホスト B の CPU 使用率が低い場合に異常が報告されます。つまり、ホスト A の CPU がホスト B の CPU に対して異常である場合に異常が表示されます。
      multivariate_by_fields プロパティを使用するには、デテクタで by_field_name も指定する必要があります。
    • per_partition_categorization
    • (Optional, object) カテゴリ化が partition フィールドとどのように相互作用するかに関連する設定。
      per_partition_categorization のプロパティ
      • enabled
      • (Boolean) この設定を有効にするには、mlcategory キーワードを使用するすべてのデテクタで partition_field_name プロパティを同じ値に設定する必要があります。そうしないと、ジョブの作成に失敗します。
      • stop_on_warn
      • (Boolean) この設定は、パーティションごとのカテゴリ化が有効な場合にのみ true に設定できます。true の場合、カテゴリ化とその後の異常検出は、カテゴリ化の状態が warn に変更されたパーティションで停止します。この設定により、カテゴリ化が一部のパーティションではうまく機能するが他のパーティションでは機能しないことが期待されるジョブを持つことが可能になります。悪いカテゴリ化のコストを、うまく機能しないパーティションで永遠に支払う必要はありません。
    • summary_count_field_name
    • (string) このプロパティが指定されている場合、ジョブに供給されるデータは事前に要約されていることが期待されます。このプロパティ値は、要約された生データポイントのカウントを含むフィールドの名前です。同じ summary_count_field_name がジョブ内のすべてのデテクタに適用されます。
      summary_count_field_name プロパティは metric 関数と一緒に使用できません。

  • analysis_limits

  • (Optional, object) 数学モデルをメモリに保持するために必要なリソースに制限を適用できます。これらの制限は概算であり、ジョブごとに設定できます。他のプロセス、たとえば Elasticsearch Java プロセスによって使用されるメモリを制御するものではありません。
    analysis_limits のプロパティ
    • categorization_examples_limit
    • (long) メモリと結果データストアに保存されるカテゴリごとの最大例数。デフォルト値は 4 です。この値を増やすと、より多くの例が利用可能になりますが、より多くのストレージが必要になります。この値を 0 に設定すると、例は保存されません。
      categorization_examples_limit は、カテゴリ化を使用する分析にのみ適用されます。詳細については、ログメッセージのカテゴリ化を参照してください。
    • model_memory_limit
    • (long or string) 分析処理に必要なメモリリソースの概算最大量。この制限に近づくと、データのプルーニングがより積極的になります。この制限を超えると、新しいエンティティはモデル化されません。バージョン 6.1 以降に作成されたジョブのデフォルト値は 1024mb です。ただし、xpack.ml.max_model_memory_limit 設定の値が 0 より大きく、1024mb より小さい場合、その値が代わりに使用されます。xpack.ml.max_model_memory_limit が設定されていないが xpack.ml.use_auto_machine_memory_percent が設定されている場合、デフォルトの model_memory_limit はクラスター内で割り当て可能な最大サイズに設定され、1024mb に制限されます。デフォルト値は比較的小さく、高リソース使用が意識的な決定であることを保証します。高いカーディナリティフィールドを分析することが期待されるジョブがある場合は、より高い値を使用する必要があるでしょう。
      Elasticsearch 8.10.0 から、機械学習プラグインの構成と状態の変更を追跡するために新しいバージョン番号が使用されます。この新しいバージョン番号は製品バージョンから切り離されており、独立して増加します。
      数値を文字列の代わりに指定すると、単位は MiB と見なされます。明確さのために文字列を指定することが推奨されます。b または kb のバイトサイズ単位を指定し、数値が明確なメガバイト数に相当しない場合、最も近い MiB に切り捨てられます。最小有効値は 1 MiB です。1 MiB 未満の値を指定すると、エラーが発生します。サポートされているバイトサイズ単位の詳細については、バイトサイズ単位を参照してください。
      xpack.ml.max_model_memory_limit 設定に値を指定すると、その設定値より大きい model_memory_limit 値を持つジョブを作成しようとするとエラーが発生します。詳細については、機械学習設定を参照してください。
  • background_persist_interval
  • (Optional, time units) 高度な構成オプション。モデルの定期的な永続化の間隔。デフォルト値は 3 時間から 4 時間の間のランダムな値で、すべてのジョブが正確に同じ時間に永続化されるのを避けます。許可される最小値は 1 時間です。
    非常に大きなモデル（数 GB）の場合、永続化には 10 ～ 20 分かかる可能性があるため、background_persist_interval の値を低く設定しないでください。
  • custom_settings
  • (Optional, object) 高度な構成オプション。ジョブに関するカスタムメタデータを含みます。たとえば、機械学習結果にカスタム URL を追加するに示されているように、カスタム URL 情報を含むことができます。
  • daily_model_snapshot_retention_after_days

  • (Optional, long) 高度な構成オプションで、このジョブの古いモデルスナップショットの自動削除に影響します。これは、毎日の最初のスナップショットのみが保持される期間（日数）を指定します。この期間は、このジョブの最新のスナップショットのタイムスタンプに対して相対的です。有効な値は 0 から model_snapshot_retention_days までです。新しいジョブの場合、デフォルト値は 1 です。バージョン 7.8.0 より前に作成されたジョブの場合、デフォルト値は model_snapshot_retention_days に一致します。詳細については、モデルスナップショットを参照してください。
    Elasticsearch 8.10.0 から、機械学習プラグインの構成と状態の変更を追跡するために新しいバージョン番号が使用されます。この新しいバージョン番号は製品バージョンから切り離されており、独立して増加します。

  • data_description

  • (Required, object) データ記述は、post data API を使用してジョブにデータを送信する際の入力データの形式を定義します。データフィードを使用する場合、time_field のみを設定する必要があり、残りのプロパティは自動的に設定されます。post data API を介してデータが受信されると、Elasticsearch に保存されません。異常検出の結果のみが保持されます。
    data_description のプロパティ

    • format
    • (string) 現在、xcontent 形式のみがサポートされており、これがデフォルト値です。
    • time_field
    • (string) タイムスタンプを含むフィールドの名前。デフォルト値は time です。
    • time_format
    • (string) 時間形式。epoch、epoch_ms、またはカスタムパターンを使用できます。デフォルト値は epoch で、UNIX または Epoch 時間（1970 年 1 月 1 日からの秒数）を指します。値 epoch_ms は、時間がエポックからのミリ秒で測定されることを示します。epoch および epoch_ms 時間形式は、整数または実数値のいずれかを受け入れます。
      カスタムパターンは、Java DateTimeFormatter クラスに準拠する必要があります。日付時刻フォーマットパターンを使用する場合は、完全な日付、時間、タイムゾーンを提供することをお勧めします。たとえば、yyyy-MM-dd'T'HH:mm:ssX。指定したパターンが完全なタイムスタンプを生成するのに不十分な場合、ジョブの作成は失敗します。

  • datafeed_config

  • (Optional, object) データフィードは、ジョブによる分析のために Elasticsearch からデータを取得します。各異常検出ジョブに対して、1 つのデータフィードのみを関連付けることができます。
    datafeed のプロパティ
    • aggregations
    • (Optional, object) 設定されている場合、データフィードは集約検索を実行します。集約のサポートは限られており、低カーディナリティデータでのみ使用する必要があります。詳細については、パフォーマンス向上のためのデータの集約を参照してください。
    • chunking_config
    • (Optional, object) データフィードは、数ヶ月または数年にわたる長期間の検索が必要な場合があります。この検索は、Elasticsearch の負荷を管理するために時間チャンクに分割されます。チャンク設定は、これらの時間チャンクのサイズがどのように計算されるかを制御し、高度な構成オプションです。
      chunking_config のプロパティ
      • mode
      • (string) 利用可能なモードは 3 つあります:
      • auto: チャンクサイズは動的に計算されます。これは、データフィードが集約を使用しない場合のデフォルトおよび推奨値です。
      • manual: 指定された time_span に従ってチャンク処理が適用されます。このモードは、データフィードが集約を使用する場合に使用します。
      • off: チャンク処理は適用されません。
      • time_span
      • (時間単位) 各検索がクエリを実行する時間範囲。この設定は、モードが manual に設定されている場合にのみ適用されます。例えば: 3h。
    • datafeed_id
    • (オプション、文字列) データフィードを一意に識別する数値文字列。この識別子は、小文字の英数字 (a-z および 0-9)、ハイフン、アンダースコアを含むことができます。英数字で始まり、英数字で終わる必要があります。
      デフォルトでは、異常検出ジョブと同じIDになります。
    • delayed_data_check_config
    • (オプション、オブジェクト) データフィードが欠損データをチェックするかどうか、およびウィンドウのサイズを指定します。例えば: {"enabled": true, "check_window": "1h"}。
      データフィードは、すでに読み取られたインデックスを検索して、インデックスにその後追加されたデータがあるかどうかを判断することができます。欠損データが見つかった場合、query_delay オプションが低すぎる設定であり、データフィードがその時点を過ぎた後にデータがインデックスされていることを示す良い指標です。遅延データの取り扱いを参照してください。
      このチェックは、リアルタイムデータフィードでのみ実行されます。
      delayed_data_check_config のプロパティ
      • check_window
      • (時間単位) 遅延データを検索するための時間ウィンドウ。この時間ウィンドウは、最新の確定バケットで終了します。デフォルトでは null で、リアルタイムデータフィードが実行されるときに適切な check_window が計算されます。特に、デフォルトの check_window スパン計算は、2h または 8 * bucket_span の最大値に基づいています。
      • enabled
      • (ブール値) データフィードが定期的に遅延データをチェックするかどうかを指定します。デフォルトは true です。
    • frequency
    • (オプション、時間単位) データフィードがリアルタイムで実行されている間に、スケジュールされたクエリが行われる間隔。デフォルト値は、短いバケットスパンの場合はバケットスパン、長いバケットスパンの場合はバケットスパンの適切な分数です。例えば: 150s。 frequency がバケットスパンより短い場合、最後の (部分的な) バケットの中間結果が書き込まれ、その後最終的に完全なバケット結果によって上書きされます。データフィードが集約を使用する場合、この値は日付ヒストグラム集約の間隔で割り切れる必要があります。
    • indices
    • (必須、配列) インデックス名の配列。ワイルドカードがサポートされています。例えば: ["it_ops_metrics", "server*"]。
      リモートクラスターにインデックスがある場合、機械学習ノードは remote_cluster_client ロールを持っている必要があります。
    • indices_options
    • (オプション、オブジェクト) 検索中に使用されるインデックス拡張オプションを指定します。
      例えば:
      1. {
      2. "expand_wildcards": ["all"],
      3. "ignore_unavailable": true,
      4. "allow_no_indices": "false",
      5. "ignore_throttled": true
      6. }
      これらのオプションの詳細については、マルチターゲット構文を参照してください。
    • max_empty_searches
    • (オプション、整数) リアルタイムデータフィードがデータを一度も見たことがない場合 (初期トレーニング期間中を含む)、この数のリアルタイム検索がドキュメントを返さないと、自動的に停止し、関連するジョブを閉じます。言い換えれば、frequency 回のリアルタイム操作の max_empty_searches の後に停止します。設定されていない場合、データが見られない終了時間のないデータフィードは、明示的に停止されるまで開始されたままになります。デフォルトでは、この設定は設定されていません。
    • query
    • (オプション、オブジェクト) Elasticsearch クエリドメイン固有言語 (DSL)。この値は、Elasticsearch 検索 POST ボディのクエリオブジェクトに対応します。Elasticsearch によってサポートされるすべてのオプションを使用できます。このオブジェクトは、Elasticsearch にそのまま渡されます。デフォルトでは、このプロパティは次の値を持ちます: {"match_all": {"boost": 1}}。
    • query_delay
    • (オプション、時間単位) データがクエリされるリアルタイムからの秒数。例えば、午前10時4分のデータは午前10時6分までElasticsearchで検索できない場合、このプロパティを120秒に設定します。デフォルト値は 60s と 120s の間でランダムに選択されます。このランダム性は、同じノードで複数のジョブが実行されているときのクエリパフォーマンスを向上させます。詳細については、遅延データの処理を参照してください。
    • runtime_mappings
    • (オプション、オブジェクト) データフィード検索のランタイムフィールドを指定します。
      例えば:
      1. {
      2. "day_of_week": {
      3. "type": "keyword",
      4. "script": {
      5. "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"
      6. }
      7. }
      8. }
    1. -  (オプション、オブジェクト) カスタム式を評価し、データフィードにスクリプトフィールドを返すスクリプトを指定します。ジョブ内の検出器構成オブジェクトには、これらのスクリプトフィールドを使用する関数が含まれる場合があります。詳細については、[スクリプトフィールドを使用したデータの変換](https://www.elastic.co/guide/en/machine-learning/8.15/ml-configuring-transform.html)および[スクリプトフィールド](1ca72727e8d3ebf9.md#script-fields)を参照してください。  
    2. -   `````scroll_size
    • (オプション、符号なし整数) データフィードが集約を使用しない場合にElasticsearch検索で使用される size パラメータ。デフォルト値は 1000 です。最大値は index.max_result_window の値で、デフォルトは10,000です。
  • description
  • (オプション、文字列) ジョブの説明。
  • groups

  • (オプション、文字列の配列) ジョブグループのリスト。ジョブはグループに属さないか、複数のグループに属することができます。

  • model_plot_config

  • (オプション、オブジェクト) この高度な構成オプションは、モデル情報を結果と共に保存します。異常検出の詳細なビューを提供します。
    モデルプロットを有効にすると、システムのパフォーマンスにかなりのオーバーヘッドが追加される可能性があります。多くのエンティティを持つジョブには実行可能ではありません。
    モデルプロットは、モデルとその境界の簡略化された示唆的なビューを提供します。多変量相関や多モーダルデータなどの複雑な特徴は表示されません。そのため、モデルプロットでは見えない異常が報告されることがあります。
    モデルプロットの設定は、ジョブが作成されるときに構成するか、後で更新することができます。パフォーマンスの問題が発生した場合は、無効にする必要があります。
    model_plot_config のプロパティ
    • annotations_enabled
    • (ブール値) true の場合、分析されている各エンティティのモデル変更注釈の計算と保存を有効にします。デフォルトは enabled です。
    • enabled
    • (ブール値) true の場合、分析されている各エンティティのモデル境界の計算と保存を有効にします。デフォルトでは、これは有効になっていません。
    • terms
    • [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために作業しますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象ではありません。 (文字列) データ収集をこのカンマ区切りのパーティションまたはフィールド値のリストに制限します。用語が指定されていない場合、または空の文字列の場合、フィルタリングは適用されません。例えば、”CPU,NetworkIn,DiskWrites”。ワイルドカードはサポートされていません。シングルメトリックビューワーを使用する場合、指定された terms のみが表示されます。
  • model_snapshot_retention_days
  • (オプション、長整数) 高度な構成オプションで、このジョブの古いモデルスナップショットの自動削除に影響します。スナップショットが保持される最大期間 (日数) を指定します。この期間は、このジョブの最新のスナップショットのタイムスタンプに対して相対的です。デフォルト値は 10 で、これは最新のスナップショットより10日古いスナップショットが削除されることを意味します。詳細については、モデルスナップショットを参照してください。
  • renormalization_window_days
  • (オプション、長整数) 高度な構成オプション。新しいデータが見られるにつれて、スコアに対する調整が適用される期間。デフォルト値は30日または100 bucket_spans のうち長い方です。
  • results_index_name
  • (オプション、文字列) 機械学習結果インデックスの名前に影響を与えるテキスト文字列。デフォルト値は shared で、.ml-anomalies-shared という名前のインデックスが生成されます。
  • results_retention_days
  • (オプション、長整数) 高度な構成オプション。結果が保持される期間 (日数)。年齢は最新のバケット結果のタイムスタンプに対して計算されます。このプロパティに非null値がある場合、サーバー時間の00:30に1日1回、最新のバケット結果より指定された日数古い結果がElasticsearchから削除されます。デフォルト値はnullで、これはすべての結果が保持されることを意味します。システムによって生成された注釈も保持目的の結果としてカウントされます; それらは結果と同じ日数後に削除されます。ユーザーによって追加された注釈は永遠に保持されます。

例

異常検出ジョブとデータフィードを作成します:

Python

  1. resp = client.ml.put_job(
  2.    job_id="test-job1",
  3.    pretty=True,
  4.    analysis_config={
  5.    "bucket_span": "15m",
  6.    "detectors": [
  7.    {
  8.    "detector_description": "Sum of bytes",
  9.    "function": "sum",
  10.    "field_name": "bytes"
  11.    }
  12.    ]
  13.    },
  14.    data_description={
  15.    "time_field": "timestamp",
  16.    "time_format": "epoch_ms"
  17.    },
  18.    analysis_limits={
  19.    "model_memory_limit": "11MB"
  20.    },
  21.    model_plot_config={
  22.    "enabled": True,
  23.    "annotations_enabled": True
  24.    },
  25.    results_index_name="test-job1",
  26.    datafeed_config={
  27.    "indices": [
  28.    "kibana_sample_data_logs"
  29.    ],
  30.    "query": {
  31.    "bool": {
  32.    "must": [
  33.    {
  34.    "match_all": {}
  35.    }
  36.    ]
  37.    }
  38.    },
  39.    "runtime_mappings": {
  40.    "hour_of_day": {
  41.    "type": "long",
  42.    "script": {
  43.    "source": "emit(doc['timestamp'].value.getHour());"
  44.    }
  45.    }
  46.    },
  47.    "datafeed_id": "datafeed-test-job1"
  48.    },
  49. )
  50. print(resp)

Js

  1. const response = await client.ml.putJob({
  2.   job_id: "test-job1",
  3.   pretty: "true",
  4.   analysis_config: {
  5.    bucket_span: "15m",
  6.    detectors: [
  7.    {
  8.    detector_description: "Sum of bytes",
  9.    function: "sum",
  10.    field_name: "bytes",
  11.    },
  12.    ],
  13.   },
  14.   data_description: {
  15.    time_field: "timestamp",
  16.    time_format: "epoch_ms",
  17.   },
  18.   analysis_limits: {
  19.    model_memory_limit: "11MB",
  20.   },
  21.   model_plot_config: {
  22.    enabled: true,
  23.    annotations_enabled: true,
  24.   },
  25.   results_index_name: "test-job1",
  26.   datafeed_config: {
  27.    indices: ["kibana_sample_data_logs"],
  28.    query: {
  29.    bool: {
  30.    must: [
  31.    {
  32.    match_all: {},
  33.    },
  34.    ],
  35.    },
  36.    },
  37.    runtime_mappings: {
  38.    hour_of_day: {
  39.    type: "long",
  40.    script: {
  41.    source: "emit(doc['timestamp'].value.getHour());",
  42.    },
  43.    },
  44.    },
  45.    datafeed_id: "datafeed-test-job1",
  46.   },
  47. });
  48. console.log(response);

コンソール

  1. PUT _ml/anomaly_detectors/test-job1?pretty
  2. {
  3.   "analysis_config": {
  4.    "bucket_span": "15m",
  5.    "detectors": [
  6.    {
  7.    "detector_description": "Sum of bytes",
  8.    "function": "sum",
  9.    "field_name": "bytes"
  10.    }
  11.    ]
  12.   },
  13.   "data_description": {
  14.    "time_field": "timestamp",
  15.    "time_format": "epoch_ms"
  16.   },
  17.   "analysis_limits": {
  18.    "model_memory_limit": "11MB"
  19.   },
  20.   "model_plot_config": {
  21.    "enabled": true,
  22.    "annotations_enabled": true
  23.   },
  24.   "results_index_name": "test-job1",
  25.   "datafeed_config":
  26.   {
  27.    "indices": [
  28.    "kibana_sample_data_logs"
  29.    ],
  30.    "query": {
  31.    "bool": {
  32.    "must": [
  33.    {
  34.    "match_all": {}
  35.    }
  36.    ]
  37.    }
  38.    },
  39.    "runtime_mappings": {
  40.    "hour_of_day": {
  41.    "type": "long",
  42.    "script": {
  43.    "source": "emit(doc['timestamp'].value.getHour());"
  44.    }
  45.    }
  46.    },
  47.    "datafeed_id": "datafeed-test-job1"
  48.   }
  49. }

APIは次の結果を返します:

Js

  1. {
  2.   "job_id" : "test-job1",
  3.   "job_type" : "anomaly_detector",
  4.   "job_version" : "8.4.0",
  5.   "create_time" : 1656087283340,
  6.   "datafeed_config" : {
  7.    "datafeed_id" : "datafeed-test-job1",
  8.    "job_id" : "test-job1",
  9.    "authorization" : {
  10.    "roles" : [
  11.    "superuser"
  12.    ]
  13.    },
  14.    "query_delay" : "61499ms",
  15.    "chunking_config" : {
  16.    "mode" : "auto"
  17.    },
  18.    "indices_options" : {
  19.    "expand_wildcards" : [
  20.    "open"
  21.    ],
  22.    "ignore_unavailable" : false,
  23.    "allow_no_indices" : true,
  24.    "ignore_throttled" : true
  25.    },
  26.    "query" : {
  27.    "bool" : {
  28.    "must" : [
  29.    {
  30.    "match_all" : { }
  31.    }
  32.    ]
  33.    }
  34.    },
  35.    "indices" : [
  36.    "kibana_sample_data_logs"
  37.    ],
  38.    "scroll_size" : 1000,
  39.    "delayed_data_check_config" : {
  40.    "enabled" : true
  41.    },
  42.    "runtime_mappings" : {
  43.    "hour_of_day" : {
  44.    "type" : "long",
  45.    "script" : {
  46.    "source" : "emit(doc['timestamp'].value.getHour());"
  47.    }
  48.    }
  49.    }
  50.   },
  51.   "analysis_config" : {
  52.    "bucket_span" : "15m",
  53.    "detectors" : [
  54.    {
  55.    "detector_description" : "Sum of bytes",
  56.    "function" : "sum",
  57.    "field_name" : "bytes",
  58.    "detector_index" : 0
  59.    }
  60.    ],
  61.    "influencers" : [ ],
  62.    "model_prune_window" : "30d"
  63.   },
  64.   "analysis_limits" : {
  65.    "model_memory_limit" : "11mb",
  66.    "categorization_examples_limit" : 4
  67.   },
  68.   "data_description" : {
  69.    "time_field" : "timestamp",
  70.    "time_format" : "epoch_ms"
  71.   },
  72.   "model_plot_config" : {
  73.    "enabled" : true,
  74.    "annotations_enabled" : true
  75.   },
  76.   "model_snapshot_retention_days" : 10,
  77.   "daily_model_snapshot_retention_after_days" : 1,
  78.   "results_index_name" : "custom-test-job1",
  79.   "allow_lazy_open" : false
  80. }