異常検出ジョブAPIの更新

異常検出ジョブの特定のプロパティを更新します。

リクエスト

POST _ml/anomaly_detectors/<job_id>/_update

前提条件

  3. ## パスパラメータ
  5. - `````<job_id>
  • (必須、文字列) 異常検出ジョブの識別子。

リクエストボディ

ジョブが作成された後に更新できるプロパティは次のとおりです：

  • allow_lazy_open
  • (Boolean) 高度な設定オプション。このジョブが、ノードに即座に割り当てられるための機械学習ノードの容量が不足している場合に開くことができるかどうかを指定します。デフォルト値は false です。ジョブを実行するための容量を持つ機械学習ノードが即座に見つからない場合、オープン異常検出ジョブAPI はエラーを返します。ただし、これはクラスター全体の xpack.ml.max_lazy_ml_nodes 設定にも依存します。詳細は 高度な機械学習設定 を参照してください。このオプションが true に設定されている場合、オープン異常検出ジョブAPI はエラーを返さず、ジョブは十分な機械学習ノードの容量が利用可能になるまで opening 状態で待機します。
    ジョブがオープンの状態で更新を行う場合、データフィードを停止し、ジョブを閉じてから、ジョブを再オープンし、データフィードを再起動して変更を適用する必要があります。
  • analysis_limits
  • (Optional, object) 数学モデルをメモリに保持するために必要なリソースに制限を適用できます。これらの制限は概算であり、ジョブごとに設定できます。他のプロセス、たとえば Elasticsearch Java プロセスによって使用されるメモリを制御するものではありません。
    analysis_limits は、ジョブが閉じている間のみ更新できます。
    analysis_limits のプロパティ
    • 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 値を持つジョブを作成しようとするとエラーが発生します。詳細については、機械学習設定を参照してください。
      • model_memory_limit の値を現在の使用量以下に減少させることはできません。現在の使用量を確認するには、ジョブ統計を取得する APIの model_bytes 値を参照してください。
      • model_size_stats オブジェクト の memory_status プロパティの値が hard_limit の場合、これは一部のデータを処理できなかったことを意味します。model_memory_limit を増加させてジョブを再実行することを検討してください。
  • background_persist_interval
  • (時間単位) 高度な設定オプション。モデルの各定期的な永続化の間の時間。デフォルト値は3〜4時間のランダムな値で、すべてのジョブが正確に同じ時間に永続化されるのを避けます。許可される最小値は1時間です。
    非常に大きなモデル（数 GB）の場合、永続化には 10 ～ 20 分かかる可能性があるため、background_persist_interval の値を低く設定しないでください。
    ジョブがオープンの状態で更新を行う場合、データフィードを停止し、ジョブを閉じてから、ジョブを再オープンし、データフィードを再起動して変更を適用する必要があります。
  • custom_settings
  • (オブジェクト) 高度な設定オプション。ジョブに関するカスタムメタデータを含みます。たとえば、機械学習結果にカスタムURLを追加する に示されているように、カスタムURL情報を含むことができます。
  • daily_model_snapshot_retention_after_days
  • (long) 高度な設定オプションで、このジョブの古いモデルスナップショットの自動削除に影響します。これは、1日ごとに最初のスナップショットのみが保持される期間（日数）を指定します。この期間は、このジョブの最新のスナップショットのタイムスタンプに対して相対的です。有効な値は 0 から model_snapshot_retention_days までです。新しいジョブの場合、デフォルト値は 1 です。バージョン 7.8.0 より前に作成されたジョブの場合、デフォルト値は model_snapshot_retention_days に一致します。詳細については、モデルスナップショット を参照してください。
    Elasticsearch 8.10.0以降、新しいバージョン番号が機械学習プラグインの構成と状態の変更を追跡するために使用されます。この新しいバージョン番号は、製品バージョンから切り離されており、独立して増加します。
  • description

  • (string) ジョブの説明です。

  • detectors

  • (array) ディテクタ更新オブジェクトの配列。
    detectors のプロパティ
    • 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 です。
    • description
    • (文字列) 検出器の説明。たとえば、Low event rate。
    • detector_index
    • (整数) 検出器の一意の識別子。この識別子は、analysis_config 内の検出器の順序に基づいており、ゼロから始まります。
      特定のディテクタを更新する場合は、この識別子を使用する必要があります。ただし、ディテクタの detector_index 値を変更することはできません。
  • groups

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

  • model_plot_config

  • (オブジェクト) この高度な設定オプションは、モデル情報を結果と共に保存します。異常検出の詳細なビューを提供します。
    モデルプロットを有効にすると、システムのパフォーマンスにかなりのオーバーヘッドが追加される可能性があります。多くのエンティティを持つジョブには実行可能ではありません。
    モデルプロットは、モデルとその境界の簡略化された示唆的なビューを提供します。多変量相関や多モーダルデータなどの複雑な特徴は表示されません。そのため、モデルプロットでは見えない異常が報告されることがあります。
    モデルプロットの設定は、ジョブが作成されるときに構成するか、後で更新することができます。パフォーマンスの問題が発生した場合は、無効にする必要があります。
    model_plot_config のプロパティ
    • annotations_enabled
    • (ブール値) true の場合、分析されている各エンティティのモデル変更注釈の計算と保存を有効にします。デフォルトは enabled です。
    • enabled
    • (ブール値) true の場合、分析されている各エンティティのモデル境界の計算と保存を有効にします。デフォルトでは、これは有効になっていません。
    • terms
    • [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために作業しますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象ではありません。 (文字列) データ収集をこのカンマ区切りのパーティションまたはフィールド値のリストに制限します。用語が指定されていない場合、または空の文字列の場合、フィルタリングは適用されません。例えば、”CPU,NetworkIn,DiskWrites”。ワイルドカードはサポートされていません。シングルメトリックビューワーを使用する場合、指定された terms のみが表示されます。
  • model_prune_window
  • (時間単位) 高度な設定オプション。指定された時間の間に更新されていないモデルの剪定に影響します。値は bucket_span の倍数に設定する必要があります。値が低すぎると、モデルから重要な情報が削除される可能性があります。通常は 30d 以上に設定します。設定しない場合、モデルの剪定は、モデルメモリの状態がソフトリミットまたはハードリミットに達した場合にのみ発生します。8.1以降に作成されたジョブの場合、デフォルト値は 30d または bucket_span の20倍の大きい方です。
  • model_snapshot_retention_days

  • (long) 高度な設定オプションで、このジョブの古いモデルスナップショットの自動削除に影響します。これは、スナップショットが保持される最大期間（日数）を指定します。この期間は、このジョブの最新のスナップショットのタイムスタンプに対して相対的です。デフォルト値は 10 で、これは最新のスナップショットより10日古いスナップショットが削除されることを意味します。詳細については、モデルスナップショット を参照してください。

  • per_partition_categorization

  • (オブジェクト) カテゴリ化がパーティションフィールドとどのように相互作用するかに関連する設定です。
    per_partition_categorization のプロパティ
    • enabled
    • (Boolean) この設定を有効にするには、mlcategory キーワードを使用するすべてのデテクタで partition_field_name プロパティを同じ値に設定する必要があります。そうしないと、ジョブの作成に失敗します。
    • stop_on_warn
    • (Boolean) この設定は、パーティションごとのカテゴリ化が有効な場合にのみ true に設定できます。true の場合、カテゴリ化とその後の異常検出は、カテゴリ化の状態が warn に変更されたパーティションで停止します。この設定により、カテゴリ化が一部のパーティションではうまく機能するが他のパーティションでは機能しないことが期待されるジョブを持つことが可能になります。悪いカテゴリ化のコストを、うまく機能しないパーティションで永遠に支払う必要はありません。
    • renormalization_window_days
    • (long) 高度な設定オプション。新しいデータが見られるときにスコアに適用される調整の期間。デフォルト値は30日または100 bucket_spans の長い方です。
      ジョブがオープンの状態で更新を行う場合、データフィードを停止し、ジョブを閉じてから、ジョブを再オープンし、データフィードを再起動して変更を適用する必要があります。
    • results_retention_days
    • (long) 高度な設定オプション。結果が保持される期間（日数）。年齢は最新のバケット結果のタイムスタンプに対して相対的に計算されます。このプロパティに非null値がある場合、サーバー時間の00:30に1日1回、最新のバケット結果より指定された日数古い結果がElasticsearchから削除されます。デフォルト値はnullで、これはすべての結果が保持されることを意味します。システムによって生成された注釈も保持目的の結果としてカウントされ、結果と同じ日数が経過した後に削除されます。ユーザーによって追加された注釈は永遠に保持されます。

例

Python

  1. resp = client.ml.update_job(
  2.    job_id="low_request_rate",
  3.    description="An updated job",
  4.    detectors={
  5.    "detector_index": 0,
  6.    "description": "An updated detector description"
  7.    },
  8.    groups=[
  9.    "kibana_sample_data",
  10.    "kibana_sample_web_logs"
  11.    ],
  12.    model_plot_config={
  13.    "enabled": True
  14.    },
  15.    renormalization_window_days=30,
  16.    background_persist_interval="2h",
  17.    model_snapshot_retention_days=7,
  18.    results_retention_days=60,
  19. )
  20. print(resp)

Ruby

  1. response = client.ml.update_job(
  2.   job_id: 'low_request_rate',
  3.   body: {
  4.    description: 'An updated job',
  5.    detectors: {
  6.    detector_index: 0,
  7.    description: 'An updated detector description'
  8.    },
  9.    groups: [
  10.    'kibana_sample_data',
  11.    'kibana_sample_web_logs'
  12.    ],
  13.    model_plot_config: {
  14.    enabled: true
  15.    },
  16.    renormalization_window_days: 30,
  17.    background_persist_interval: '2h',
  18.    model_snapshot_retention_days: 7,
  19.    results_retention_days: 60
  20.   }
  21. )
  22. puts response

Js

  1. const response = await client.ml.updateJob({
  2.   job_id: "low_request_rate",
  3.   description: "An updated job",
  4.   detectors: {
  5.    detector_index: 0,
  6.    description: "An updated detector description",
  7.   },
  8.   groups: ["kibana_sample_data", "kibana_sample_web_logs"],
  9.   model_plot_config: {
  10.    enabled: true,
  11.   },
  12.   renormalization_window_days: 30,
  13.   background_persist_interval: "2h",
  14.   model_snapshot_retention_days: 7,
  15.   results_retention_days: 60,
  16. });
  17. console.log(response);

コンソール

  1. POST _ml/anomaly_detectors/low_request_rate/_update
  2. {
  3.   "description":"An updated job",
  4.   "detectors": {
  5.    "detector_index": 0,
  6.    "description": "An updated detector description"
  7.   },
  8.   "groups": ["kibana_sample_data","kibana_sample_web_logs"],
  9.   "model_plot_config": {
  10.    "enabled": true
  11.   },
  12.   "renormalization_window_days": 30,
  13.   "background_persist_interval": "2h",
  14.   "model_snapshot_retention_days": 7,
  15.   "results_retention_days": 60
  16. }

異常検出ジョブが更新されると、更新されたプロパティ値を含むジョブ設定情報の概要が受信されます。たとえば：

Js

  1. {
  2.   "job_id" : "low_request_rate",
  3.   "job_type" : "anomaly_detector",
  4.   "job_version" : "8.4.0",
  5.   "create_time" : 1656105950893,
  6.   "finished_time" : 1656105965744,
  7.   "model_snapshot_id" : "1656105964",
  8.   "custom_settings" : {
  9.    "created_by" : "ml-module-sample",
  10.    "custom_urls" : [
  11.    {
  12.    "url_name" : "Raw data",
  13.    "url_value" : "discover#/?_g=(time:(from:'$earliest$',mode:absolute,to:'$latest$'))&_a=(index:'90943e30-9a47-11e8-b64d-95841ca0b247')"
  14.    },
  15.    {
  16.    "url_name" : "Data dashboard",
  17.    "url_value" : "dashboards#/view/edf84fe0-e1a0-11e7-b6d5-4dc382ef7f5b?_g=(time:(from:'$earliest$',mode:absolute,to:'$latest$'))&_a=(filters:!(),query:(language:kuery,query:''))"
  18.    }
  19.    ]
  20.   },
  21.   "groups" : [
  22.    "kibana_sample_data",
  23.    "kibana_sample_web_logs"
  24.   ],
  25.   "description" : "An updated job",
  26.   "analysis_config" : {
  27.    "bucket_span" : "1h",
  28.    "summary_count_field_name" : "doc_count",
  29.    "detectors" : [
  30.    {
  31.    "detector_description" : "An updated detector description",
  32.    "function" : "low_count",
  33.    "detector_index" : 0
  34.    }
  35.    ],
  36.    "influencers" : [ ],
  37.    "model_prune_window" : "30d"
  38.   },
  39.   "analysis_limits" : {
  40.    "model_memory_limit" : "11mb",
  41.    "categorization_examples_limit" : 4
  42.   },
  43.   "data_description" : {
  44.    "time_field" : "timestamp",
  45.    "time_format" : "epoch_ms"
  46.   },
  47.   "model_plot_config" : {
  48.    "enabled" : true,
  49.    "annotations_enabled" : true
  50.   },
  51.   "renormalization_window_days" : 30,
  52.   "background_persist_interval" : "2h",
  53.   "model_snapshot_retention_days" : 7,
  54.   "daily_model_snapshot_retention_after_days" : 1,
  55.   "results_retention_days" : 60,
  56.   "results_index_name" : "custom-low_request_rate",
  57.   "allow_lazy_open" : false
  58. }