Link Search Menu Expand Document Documentation Menu
文档

异常检测 API

使用这些异常检测操作以编程方式创建和管理检测器。

目录

创建异常检测器

1.0 版引入

创建一个异常检测器。

此命令创建一个名为 test-detector 的单实体检测器，它根据 value 字段的总和查找异常，并将结果存储在自定义的 opensearch-ad-plugin-result-test 索引中

请求

POST _plugins/_anomaly_detection/detectors
{
  "name": "test-detector",
  "description": "Test detector",
  "time_field": "timestamp",
  "indices": [
    "server_log*"
  ],
  "feature_attributes": [
    {
      "feature_name": "test",
      "feature_enabled": true,
      "aggregation_query": {
        "test": {
          "sum": {
            "field": "value"
          }
        }
      }
    }
  ],
  "filter_query": {
    "bool": {
      "filter": [
        {
          "range": {
            "value": {
              "gt": 1
            }
          }
        }
      ],
      "adjust_pure_negative": true,
      "boost": 1
    }
  },
  "detection_interval": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  },
  "window_delay": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  },
  "result_index" : "opensearch-ad-plugin-result-test"
}

示例响应

{
  "_id": "VEHKTXwBwf_U8gjUXY2s",
  "_version": 1,
  "_seq_no": 5,
  "anomaly_detector": {
    "name": "test-detector",
    "description": "Test detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "from": 1,
                "to": null,
                "include_lower": false,
                "include_upper": true,
                "boost": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "shingle_size": 8,
    "schema_version": 0,
    "feature_attributes": [
      {
        "feature_id": "U0HKTXwBwf_U8gjUXY2m",
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "last_update_time": 1633392680364,
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    },
    "detector_type": "SINGLE_ENTITY"
  },
  "_primary_term": 1
}

通过指定类别字段来创建高基数检测器

请求

POST _plugins/_anomaly_detection/detectors
{
  "name": "test-hc-detector",
  "description": "Test detector",
  "time_field": "timestamp",
  "indices": [
    "server_log*"
  ],
  "feature_attributes": [
    {
      "feature_name": "test",
      "feature_enabled": true,
      "aggregation_query": {
        "test": {
          "sum": {
            "field": "value"
          }
        }
      }
    }
  ],
  "filter_query": {
    "bool": {
      "filter": [
        {
          "range": {
            "value": {
              "gt": 1
            }
          }
        }
      ],
      "adjust_pure_negative": true,
      "boost": 1
    }
  },
  "detection_interval": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  },
  "window_delay": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  },
  "category_field": [
    "ip"
  ]
}

示例响应

{
  "_id": "b0HRTXwBwf_U8gjUw43R",
  "_version": 1,
  "_seq_no": 6,
  "anomaly_detector": {
    "name": "test-hc-detector",
    "description": "Test detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "from": 1,
                "to": null,
                "include_lower": false,
                "include_upper": true,
                "boost": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "shingle_size": 8,
    "schema_version": 0,
    "feature_attributes": [
      {
        "feature_id": "bkHRTXwBwf_U8gjUw43K",
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "last_update_time": 1633393165265,
    "category_field": [
      "ip"
    ],
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    },
    "detector_type": "MULTI_ENTITY"
  },
  "_primary_term": 1
}

您最多可以指定两个类别字段

"category_field": [
  "ip"
]

"category_field": [
  "ip", "error_type"
]

您可以指定以下选项。

选项 描述 类型 必需
名称 检测器的名称。 字符串 是
描述 检测器的描述。 字符串 否
时间字段 时间字段的名称。 字符串 是
索引 用作数据源的索引列表。 列表 是
feature_attributes 指定 feature_name，将 enabled 参数设置为 true，并指定一个聚合查询。 列表 是
filter_query 为您的特征提供可选的过滤查询。 对象 否
detection_interval 异常检测器的时间间隔。 对象 是
window_delay 为数据收集添加额外的处理时间。 对象 否
category_field 使用维度对数据进行分类或切片。类似于 SQL 中的 GROUP BY。 列表 否

验证检测器

1.2 中引入

返回检测器配置是否存在可能阻止 OpenSearch 创建检测器的任何问题。

您可以使用验证检测器 API 操作在创建检测器之前识别检测器配置中的问题。

请求正文包含检测器配置，其格式与 创建检测器 API 的请求正文相同。

您有以下验证选项

  • 仅根据检测器配置进行验证，并查找任何会完全阻止检测器创建的问题
POST _plugins/_anomaly_detection/detectors/_validate
POST _plugins/_anomaly_detection/detectors/_validate/detector
  • 根据源数据进行验证，以查看检测器完成模型训练的可能性。
POST _plugins/_anomaly_detection/detectors/_validate/model

此 API 操作的响应要么返回阻止性问题作为检测器类型响应，要么返回指示可以修改的字段以增加模型训练成功完成可能性的响应。模型类型问题不需要在检测器创建成功时修复，但如果它们没有得到解决，检测器可能无法成功训练。

请求

POST _plugins/_anomaly_detection/detectors/_validate
POST _plugins/_anomaly_detection/detectors/_validate/detector
{
  "name": "test-detector",
  "description": "Test detector",
  "time_field": "timestamp",
  "indices": [
    "server_log*"
  ],
  "feature_attributes": [
    {
      "feature_name": "test",
      "feature_enabled": true,
      "aggregation_query": {
        "test": {
          "sum": {
            "field": "value"
          }
        }
      }
    }
  ],
  "filter_query": {
    "bool": {
      "filter": [
        {
          "range": {
            "value": {
              "gt": 1
            }
          }
        }
      ],
      "adjust_pure_negative": true,
      "boost": 1
    }
  },
  "detection_interval": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  },
  "window_delay": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  }
}

如果验证检测器 API 在检测器配置中没有发现任何问题，它将返回一个空响应

示例响应

{}

如果验证检测器 API 发现问题，它会返回一条消息，解释配置中的错误。在此示例中，特征查询聚合了一个数据源中不存在的字段。

示例响应

{
  "detector": {
    "feature_attributes": {
      "message": "Feature has invalid query returning empty aggregated data: average_total_rev",
      "sub_issues": {
        "average_total_rev": "Feature has invalid query returning empty aggregated data"
      }
    }
  }
}

以下请求根据源数据进行验证，以查看模型训练是否可能成功。在此示例中，数据每 5 分钟摄入一次，检测器间隔设置为 1 分钟。

POST _plugins/_anomaly_detection/detectors/_validate/model
{
  "name": "test-detector",
  "description": "Test detector",
  "time_field": "timestamp",
  "indices": [
    "server_log*"
  ],
  "feature_attributes": [
    {
      "feature_name": "test",
      "feature_enabled": true,
      "aggregation_query": {
        "test": {
          "sum": {
            "field": "value"
          }
        }
      }
    }
  ],
  "filter_query": {
    "bool": {
      "filter": [
        {
          "range": {
            "value": {
              "gt": 1
            }
          }
        }
      ],
      "adjust_pure_negative": true,
      "boost": 1
    }
  },
  "detection_interval": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  },
  "window_delay": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  }
}

如果验证检测器 API 发现您的配置有改进空间，它会返回一个包含建议的响应，说明如何更改配置以改进模型训练。

示例响应

在此示例中，验证检测器 API 返回一个响应，表明将检测器间隔长度更改为至少四分钟可以增加模型训练成功的几率。

{
  "model": {
    "detection_interval": {
      "message": "The selected detector interval might collect sparse data. Consider changing interval length to: 4",
      "suggested_value": {
        "period": {
          "interval": 4,
          "unit": "Minutes"
        }
      }
    }
  }
}

另一个响应可能表明您可以更改 filter_query（数据过滤器），因为当前过滤的数据过于稀疏，无法正确训练模型，这可能是因为索引也在摄入所选过滤器之外的数据。使用另一个 filter_query 可以使您的数据更密集。

{
  "model": {
    "filter_query": {
      "message": "Data is too sparse after data filter is applied. Consider changing the data filter"
    }
  }
}

获取检测器

1.0 版引入

根据 detector_id 返回有关检测器的所有信息。

请求

GET _plugins/_anomaly_detection/detectors/<detectorId>

示例响应

{
  "_id": "VEHKTXwBwf_U8gjUXY2s",
  "_version": 1,
  "_primary_term": 1,
  "_seq_no": 5,
  "anomaly_detector": {
    "name": "test-detector",
    "description": "Test detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "from": 1,
                "to": null,
                "include_lower": false,
                "include_upper": true,
                "boost": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "shingle_size": 8,
    "schema_version": 0,
    "feature_attributes": [
      {
        "feature_id": "U0HKTXwBwf_U8gjUXY2m",
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "last_update_time": 1633392680364,
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    },
    "detector_type": "SINGLE_ENTITY"
  }
}

“作业”是您计划定期运行的东西，因此它仅适用于实时异常检测，而不适用于只运行一次的历史分析。

当您启动实时检测器时，异常检测插件会创建一个作业，如果作业已存在，则会更新它。当您启动或重新启动实时检测器时，插件会创建一个新的实时任务，用于记录运行时信息，例如检测器配置快照、实时作业状态（初始化/运行/停止）、初始化进度等。

单个检测器只能有一个实时作业（作业 ID 与检测器 ID 相同），但它可以有多个实时任务，因为每次重新启动实时作业都会创建一个新的实时任务。您可以通过 plugins.anomaly_detection.max_old_ad_task_docs_per_detector 设置来限制实时任务的数量。

历史分析没有关联的作业。当您启动或重新运行检测器的历史分析时，异常检测插件会创建一个新的历史批处理任务，用于跟踪历史分析运行时信息，例如状态、协调/工作节点、任务进度等。您可以通过 plugins.anomaly_detection.max_old_ad_task_docs_per_detector 设置来限制历史任务的数量。

使用 job=true 获取实时分析任务信息。

请求

GET _plugins/_anomaly_detection/detectors/<detectorId>?job=true

示例响应

{
  "_id": "VEHKTXwBwf_U8gjUXY2s",
  "_version": 1,
  "_primary_term": 1,
  "_seq_no": 5,
  "anomaly_detector": {
    "name": "test-detector",
    "description": "Test detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "from": 1,
                "to": null,
                "include_lower": false,
                "include_upper": true,
                "boost": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "shingle_size": 8,
    "schema_version": 0,
    "feature_attributes": [
      {
        "feature_id": "U0HKTXwBwf_U8gjUXY2m",
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "last_update_time": 1633392680364,
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    },
    "detector_type": "SINGLE_ENTITY"
  },
  "anomaly_detector_job": {
    "name": "VEHKTXwBwf_U8gjUXY2s",
    "schedule": {
      "interval": {
        "start_time": 1633393656357,
        "period": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "enabled": true,
    "enabled_time": 1633393656357,
    "last_update_time": 1633393656357,
    "lock_duration_seconds": 60,
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    }
  }
}

使用 task=true 获取实时和历史分析任务信息。

请求

GET _plugins/_anomaly_detection/detectors/<detectorId>?task=true

示例响应

{
  "_id": "VEHKTXwBwf_U8gjUXY2s",
  "_version": 1,
  "_primary_term": 1,
  "_seq_no": 5,
  "anomaly_detector": {
    "name": "test-detector",
    "description": "Test detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "from": 1,
                "to": null,
                "include_lower": false,
                "include_upper": true,
                "boost": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "shingle_size": 8,
    "schema_version": 0,
    "feature_attributes": [
      {
        "feature_id": "U0HKTXwBwf_U8gjUXY2m",
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "last_update_time": 1633392680364,
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    },
    "detector_type": "SINGLE_ENTITY"
  },
  "realtime_detection_task": {
    "task_id": "nkTZTXwBjd8s6RK4QlMq",
    "last_update_time": 1633393776375,
    "started_by": "admin",
    "error": "",
    "state": "RUNNING",
    "detector_id": "VEHKTXwBwf_U8gjUXY2s",
    "task_progress": 0,
    "init_progress": 1,
    "execution_start_time": 1633393656362,
    "is_latest": true,
    "task_type": "REALTIME_SINGLE_ENTITY",
    "coordinating_node": "SWD7ihu9TaaW1zKwFZNVNg",
    "detector": {
      "name": "test-detector",
      "description": "Test detector",
      "time_field": "timestamp",
      "indices": [
        "server_log*"
      ],
      "filter_query": {
        "bool": {
          "filter": [
            {
              "range": {
                "value": {
                  "from": 1,
                  "to": null,
                  "include_lower": false,
                  "include_upper": true,
                  "boost": 1
                }
              }
            }
          ],
          "adjust_pure_negative": true,
          "boost": 1
        }
      },
      "detection_interval": {
        "period": {
          "interval": 1,
          "unit": "Minutes"
        }
      },
      "window_delay": {
        "period": {
          "interval": 1,
          "unit": "Minutes"
        }
      },
      "shingle_size": 8,
      "schema_version": 0,
      "feature_attributes": [
        {
          "feature_id": "U0HKTXwBwf_U8gjUXY2m",
          "feature_name": "test",
          "feature_enabled": true,
          "aggregation_query": {
            "test": {
              "sum": {
                "field": "value"
              }
            }
          }
        }
      ],
      "last_update_time": 1633392680364,
      "user": {
        "name": "admin",
        "backend_roles": [
          "admin"
        ],
        "roles": [
          "own_index",
          "all_access"
        ],
        "custom_attribute_names": [],
        "user_requested_tenant": "__user__"
      },
      "detector_type": "SINGLE_ENTITY"
    },
    "estimated_minutes_left": 0,
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    }
  },
  "historical_analysis_task": {
    "task_id": "99DaTXwB6HknB84StRN1",
    "last_update_time": 1633393797040,
    "started_by": "admin",
    "state": "RUNNING",
    "detector_id": "VEHKTXwBwf_U8gjUXY2s",
    "task_progress": 0.89285713,
    "init_progress": 1,
    "current_piece": 1633328940000,
    "execution_start_time": 1633393751412,
    "is_latest": true,
    "task_type": "HISTORICAL_SINGLE_ENTITY",
    "coordinating_node": "SWD7ihu9TaaW1zKwFZNVNg",
    "worker_node": "2Z4q22BySEyzakYt_A0A2A",
    "detector": {
      "name": "test-detector",
      "description": "Test detector",
      "time_field": "timestamp",
      "indices": [
        "server_log*"
      ],
      "filter_query": {
        "bool": {
          "filter": [
            {
              "range": {
                "value": {
                  "from": 1,
                  "to": null,
                  "include_lower": false,
                  "include_upper": true,
                  "boost": 1
                }
              }
            }
          ],
          "adjust_pure_negative": true,
          "boost": 1
        }
      },
      "detection_interval": {
        "period": {
          "interval": 1,
          "unit": "Minutes"
        }
      },
      "window_delay": {
        "period": {
          "interval": 1,
          "unit": "Minutes"
        }
      },
      "shingle_size": 8,
      "schema_version": 0,
      "feature_attributes": [
        {
          "feature_id": "U0HKTXwBwf_U8gjUXY2m",
          "feature_name": "test",
          "feature_enabled": true,
          "aggregation_query": {
            "test": {
              "sum": {
                "field": "value"
              }
            }
          }
        }
      ],
      "last_update_time": 1633392680364,
      "user": {
        "name": "admin",
        "backend_roles": [
          "admin"
        ],
        "roles": [
          "own_index",
          "all_access"
        ],
        "custom_attribute_names": [],
        "user_requested_tenant": "__user__"
      },
      "detector_type": "SINGLE_ENTITY"
    },
    "detection_date_range": {
      "start_time": 1632788951329,
      "end_time": 1633393751329
    },
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    }
  }
}

更新检测器

1.0 版引入

更新检测器，包括描述或添加/删除特征的任何更改。要更新检测器，您需要首先停止实时检测和历史分析。

您无法更新类别字段。

请求

PUT _plugins/_anomaly_detection/detectors/<detectorId>
{
  "name": "test-detector",
  "description": "Test update detector",
  "time_field": "timestamp",
  "indices": [
    "server_log*"
  ],
  "feature_attributes": [
    {
      "feature_name": "test",
      "feature_enabled": true,
      "aggregation_query": {
        "test": {
          "sum": {
            "field": "value"
          }
        }
      }
    }
  ],
  "filter_query": {
    "bool": {
      "filter": [
        {
          "range": {
            "value": {
              "gt": 1
            }
          }
        }
      ],
      "adjust_pure_negative": true,
      "boost": 1
    }
  },
  "detection_interval": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  },
  "window_delay": {
    "period": {
      "interval": 1,
      "unit": "Minutes"
    }
  }
}

示例响应

{
  "_id": "VEHKTXwBwf_U8gjUXY2s",
  "_version": 2,
  "_seq_no": 7,
  "anomaly_detector": {
    "name": "test-detector",
    "description": "Test update detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "from": 1,
                "to": null,
                "include_lower": false,
                "include_upper": true,
                "boost": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "shingle_size": 8,
    "schema_version": 0,
    "feature_attributes": [
      {
        "feature_id": "3kHiTXwBwf_U8gjUlY15",
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "last_update_time": 1633394267522,
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    },
    "detector_type": "SINGLE_ENTITY"
  },
  "_primary_term": 1
}

删除检测器

1.0 版引入

根据 detector_id 删除检测器。要删除检测器，您需要首先停止实时检测和历史分析。

请求

DELETE _plugins/_anomaly_detection/detectors/<detectorId>

示例响应

{
  "_index": ".opensearch-anomaly-detectors",
  "_id": "70TxTXwBjd8s6RK4j1Pj",
  "_version": 2,
  "result": "deleted",
  "forced_refresh": true,
  "_shards": {
    "total": 2,
    "successful": 2,
    "failed": 0
  },
  "_seq_no": 9,
  "_primary_term": 1
}

预览检测器

1.0 版引入

将日期范围传递给异常检测器，以返回该日期范围内的任何异常。

预览单实体检测器

请求

POST _plugins/_anomaly_detection/detectors/_preview
{
  "period_start": 1633048868000,
  "period_end": 1633394468000,
  "detector": {
    "name": "test-detector",
    "description": "Test update detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "feature_attributes": [
      {
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "gt": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    }
  }
}

示例响应

{
  "anomaly_result": [
    {
      "detector_id": null,
      "data_start_time": 1633049280000,
      "data_end_time": 1633049340000,
      "schema_version": 0,
      "feature_data": [
        {
          "feature_id": "8EHmTXwBwf_U8gjU0Y0u",
          "feature_name": "test",
          "data": 0
        }
      ],
      "anomaly_grade": 0,
      "confidence": 0
    },
    ...
  ],
  "anomaly_detector": {
    "name": "test-detector",
    "description": "Test update detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "from": 1,
                "to": null,
                "include_lower": false,
                "include_upper": true,
                "boost": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "shingle_size": 8,
    "schema_version": 0,
    "feature_attributes": [
      {
        "feature_id": "8EHmTXwBwf_U8gjU0Y0u",
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "detector_type": "SINGLE_ENTITY"
  }
}

如果您指定类别字段，每个结果都与一个实体关联

请求

POST _plugins/_anomaly_detection/detectors/_preview
{
  "period_start": 1633048868000,
  "period_end": 1633394468000,
  "detector": {
    "name": "test-detector",
    "description": "Test update detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "feature_attributes": [
      {
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "gt": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "category_field": [
      "error_type"
    ]
  }
}

示例响应

{
  "anomaly_result": [
    {
      "detector_id": null,
      "data_start_time": 1633049280000,
      "data_end_time": 1633049340000,
      "schema_version": 0,
      "feature_data": [
        {
          "feature_id": "tkTpTXwBjd8s6RK4DlOZ",
          "feature_name": "test",
          "data": 0
        }
      ],
      "anomaly_grade": 0,
      "confidence": 0,
      "entity": [
        {
          "name": "error_type",
          "value": "error1"
        }
      ]
    },
    ...
  ],
  "anomaly_detector": {
    "name": "test-detector",
    "description": "Test update detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "from": 1,
                "to": null,
                "include_lower": false,
                "include_upper": true,
                "boost": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "shingle_size": 8,
    "schema_version": 0,
    "feature_attributes": [
      {
        "feature_id": "tkTpTXwBjd8s6RK4DlOZ",
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "category_field": [
      "error_type"
    ],
    "detector_type": "MULTI_ENTITY"
  }
}

您可以使用检测器 ID 预览检测器

POST _plugins/_anomaly_detection/detectors/_preview
{
  "detector_id": "VEHKTXwBwf_U8gjUXY2s",
  "period_start": 1633048868000,
  "period_end": 1633394468000
}

或者

POST _opendistro/_anomaly_detection/detectors/VEHKTXwBwf_U8gjUXY2s/_preview
{
  "period_start": 1633048868000,
  "period_end": 1633394468000
}

示例响应

{
  "anomaly_result": [
    {
      "detector_id": "VEHKTXwBwf_U8gjUXY2s",
      "data_start_time": 1633049280000,
      "data_end_time": 1633049340000,
      "schema_version": 0,
      "feature_data": [
        {
          "feature_id": "3kHiTXwBwf_U8gjUlY15",
          "feature_name": "test",
          "data": 0
        }
      ],
      "anomaly_grade": 0,
      "confidence": 0,
      "user": {
        "name": "admin",
        "backend_roles": [
          "admin"
        ],
        "roles": [
          "own_index",
          "all_access"
        ],
        "custom_attribute_names": [],
        "user_requested_tenant": "__user__"
      }
    },
    ...
  ],
  "anomaly_detector": {
    "name": "test-detector",
    "description": "Test update detector",
    "time_field": "timestamp",
    "indices": [
      "server_log*"
    ],
    "filter_query": {
      "bool": {
        "filter": [
          {
            "range": {
              "value": {
                "from": 1,
                "to": null,
                "include_lower": false,
                "include_upper": true,
                "boost": 1
              }
            }
          }
        ],
        "adjust_pure_negative": true,
        "boost": 1
      }
    },
    "detection_interval": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "window_delay": {
      "period": {
        "interval": 1,
        "unit": "Minutes"
      }
    },
    "shingle_size": 8,
    "schema_version": 0,
    "feature_attributes": [
      {
        "feature_id": "3kHiTXwBwf_U8gjUlY15",
        "feature_name": "test",
        "feature_enabled": true,
        "aggregation_query": {
          "test": {
            "sum": {
              "field": "value"
            }
          }
        }
      }
    ],
    "last_update_time": 1633394267522,
    "user": {
      "name": "admin",
      "backend_roles": [
        "admin"
      ],
      "roles": [
        "own_index",
        "all_access"
      ],
      "custom_attribute_names": [],
      "user_requested_tenant": "__user__"
    },
    "detector_type": "SINGLE_ENTITY"
  }
}

启动检测器作业

1.0 版引入

启动实时或历史异常检测器作业。

启动实时检测器作业

请求

POST _plugins/_anomaly_detection/detectors/<detectorId>/_start

示例响应

{
  "_id": "VEHKTXwBwf_U8gjUXY2s",
  "_version": 3,
  "_seq_no": 6,
  "_primary_term": 1
}

_id 表示实时作业 ID，它与检测器 ID 相同。

启动历史分析

POST _plugins/_anomaly_detection/detectors/<detectorId>/_start
{
  "start_time": 1633048868000,
  "end_time": 1633394468000
}

示例响应

{
  "_id": "f9DsTXwB6HknB84SoRTY",
  "_version": 1,
  "_seq_no": 958,
  "_primary_term": 1
}

_id 表示历史批处理任务 ID，它是一个随机的通用唯一标识符 (UUID)。

停止检测器作业

1.0 版引入

停止实时或历史异常检测器作业。

停止实时检测器作业

请求

POST _plugins/_anomaly_detection/detectors/<detectorId>/_stop

示例响应

{
  "_id": "VEHKTXwBwf_U8gjUXY2s",
  "_version": 0,
  "_seq_no": 0,
  "_primary_term": 0
}

停止历史分析

1.1 版本引入

POST _plugins/_anomaly_detection/detectors/<detectorId>/_stop?historical=true

示例响应

{
  "_id": "f9DsTXwB6HknB84SoRTY",
  "_version": 0,
  "_seq_no": 0,
  "_primary_term": 0
}

搜索检测器

1.0 版引入

返回搜索查询的所有异常检测器。

使用 server_log* 索引搜索检测器

请求

GET _plugins/_anomaly_detection/detectors/_search
POST _plugins/_anomaly_detection/detectors/_search
{
  "query": {
    "wildcard": {
      "indices": {
        "value": "server_log*"
      }
    }
  }
}

示例响应

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": ".opensearch-anomaly-detectors",
        "_id": "Zi5zTXwBwf_U8gjUTfJG",
        "_version": 1,
        "_seq_no": 1,
        "_primary_term": 1,
        "_score": 1,
        "_source": {
          "name": "test",
          "description": "test",
          "time_field": "timestamp",
          "indices": [
            "server_log"
          ],
          "filter_query": {
            "match_all": {
              "boost": 1
            }
          },
          "detection_interval": {
            "period": {
              "interval": 5,
              "unit": "Minutes"
            }
          },
          "window_delay": {
            "period": {
              "interval": 1,
              "unit": "Minutes"
            }
          },
          "shingle_size": 8,
          "schema_version": 0,
          "feature_attributes": [
            {
              "feature_id": "ZS5zTXwBwf_U8gjUTfIn",
              "feature_name": "test_feature",
              "feature_enabled": true,
              "aggregation_query": {
                "test_feature": {
                  "sum": {
                    "field": "value"
                  }
                }
              }
            }
          ],
          "last_update_time": 1633386974533,
          "category_field": [
            "error_type"
          ],
          "user": {
            "name": "admin",
            "backend_roles": [
              "admin"
            ],
            "roles": [
              "own_index",
              "all_access"
            ],
            "custom_attribute_names": [],
            "user_requested_tenant": "__user__"
          },
          "detector_type": "MULTI_ENTITY"
        }
      },
      ...
    ]
  }
}

搜索检测器任务

1.1 版本引入

搜索检测器任务。

搜索高基数检测器的最新检测器级别历史分析任务

请求

GET _plugins/_anomaly_detection/detectors/tasks/_search
POST _plugins/_anomaly_detection/detectors/tasks/_search
{
  "query": {
    "bool": {
      "filter": [
        {
          "term": {
            "detector_id": "Zi5zTXwBwf_U8gjUTfJG"
          }
        },
        {
          "term": {
            "task_type": "HISTORICAL_HC_DETECTOR"
          }
        },
        {
          "term": {
            "is_latest": "true"
          }
        }
      ]
    }
  }
}

示例响应

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0,
    "hits": [
      {
        "_index": ".opensearch-anomaly-detection-state",
        "_id": "fm-RTXwBYwCbWecgB753",
        "_version": 34,
        "_seq_no": 928,
        "_primary_term": 1,
        "_score": 0,
        "_source": {
          "detector_id": "Zi5zTXwBwf_U8gjUTfJG",
          "error": "",
          "detection_date_range": {
            "start_time": 1630794960000,
            "end_time": 1633386960000
          },
          "task_progress": 1,
          "last_update_time": 1633389090738,
          "execution_start_time": 1633388922742,
          "state": "FINISHED",
          "coordinating_node": "2Z4q22BySEyzakYt_A0A2A",
          "task_type": "HISTORICAL_HC_DETECTOR",
          "execution_end_time": 1633389090738,
          "started_by": "admin",
          "init_progress": 0,
          "is_latest": true,
          "detector": {
            "category_field": [
              "error_type"
            ],
            "description": "test",
            "ui_metadata": {
              "features": {
                "test_feature": {
                  "aggregationBy": "sum",
                  "aggregationOf": "value",
                  "featureType": "simple_aggs"
                }
              },
              "filters": []
            },
            "feature_attributes": [
              {
                "feature_id": "ZS5zTXwBwf_U8gjUTfIn",
                "feature_enabled": true,
                "feature_name": "test_feature",
                "aggregation_query": {
                  "test_feature": {
                    "sum": {
                      "field": "value"
                    }
                  }
                }
              }
            ],
            "schema_version": 0,
            "time_field": "timestamp",
            "last_update_time": 1633386974533,
            "indices": [
              "server_log"
            ],
            "window_delay": {
              "period": {
                "unit": "Minutes",
                "interval": 1
              }
            },
            "detection_interval": {
              "period": {
                "unit": "Minutes",
                "interval": 5
              }
            },
            "name": "testhc",
            "filter_query": {
              "match_all": {
                "boost": 1
              }
            },
            "shingle_size": 8,
            "user": {
              "backend_roles": [
                "admin"
              ],
              "custom_attribute_names": [],
              "roles": [
                "own_index",
                "all_access"
              ],
              "name": "admin",
              "user_requested_tenant": "__user__"
            },
            "detector_type": "MULTI_ENTITY"
          },
          "user": {
            "backend_roles": [
              "admin"
            ],
            "custom_attribute_names": [],
            "roles": [
              "own_index",
              "all_access"
            ],
            "name": "admin",
            "user_requested_tenant": "__user__"
          }
        }
      }
    ]
  }
}

搜索高基数检测器历史分析的最新实体级别任务

请求

GET _plugins/_anomaly_detection/detectors/tasks/_search
POST _plugins/_anomaly_detection/detectors/tasks/_search
{
  "query": {
    "bool": {
      "filter": [
        {
          "term": {
            "detector_id": "Zi5zTXwBwf_U8gjUTfJG"
          }
        },
        {
          "term": {
            "task_type": "HISTORICAL_HC_ENTITY"
          }
        },
        {
          "term": {
            "is_latest": "true"
          }
        }
      ]
    }
  },
  "sort": [
    {
      "execution_start_time": {
        "order": "desc"
      }
    }
  ],
  "size": 100
}

搜索和聚合所有实体级别历史任务的状态

parent_task_id 与您可以通过分析检测器 API 获取的任务 ID 相同：GET _plugins/_anomaly_detection/detectors/<detector_ID>/_profile/ad_task。

请求

GET _plugins/_anomaly_detection/detectors/tasks/_search
POST _plugins/_anomaly_detection/detectors/tasks/_search
{
  "size": 0,
  "query": {
    "bool": {
      "filter": [
        {
          "term": {
            "detector_id": {
              "value": "Zi5zTXwBwf_U8gjUTfJG",
              "boost": 1
            }
          }
        },
        {
          "term": {
            "parent_task_id": {
              "value": "fm-RTXwBYwCbWecgB753",
              "boost": 1
            }
          }
        },
        {
          "terms": {
            "task_type": [
              "HISTORICAL_HC_ENTITY"
            ],
            "boost": 1
          }
        }
      ]
    }
  },
  "aggs": {
    "test": {
      "terms": {
        "field": "state",
        "size": 100
      }
    }
  }
}

示例响应

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 32,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "test": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "FINISHED",
          "doc_count": 32
        }
      ]
    }
  }
}

搜索检测器结果

1.0 版引入

返回搜索查询的所有结果。

您有以下搜索选项

  • 要仅搜索默认结果索引，只需使用搜索 API

    POST _plugins/_anomaly_detection/detectors/results/_search/

  • 要同时搜索自定义结果索引和默认结果索引，您可以将自定义结果索引添加到搜索 API

    POST _plugins/_anomaly_detection/detectors/results/_search/<custom_result_index>

    或者，添加自定义结果索引并将 only_query_custom_result_index 参数设置为 false

    POST _plugins/_anomaly_detection/detectors/results/_search/<custom_result_index>?only_query_custom_result_index=false

  • 要仅搜索自定义结果索引，请将自定义结果索引添加到搜索 API 并将 only_query_custom_result_index 参数设置为 true

    POST _plugins/_anomaly_detection/detectors/results/_search/<custom_result_index>?only_query_custom_result_index=true

以下示例搜索实时分析中等级大于 0 的异常结果

请求

GET _plugins/_anomaly_detection/detectors/results/_search/opensearch-ad-plugin-result-test
POST _plugins/_anomaly_detection/detectors/results/_search/opensearch-ad-plugin-result-test
{
  "query": {
    "bool": {
      "filter": [
        {
          "term": {
            "detector_id": "EWy02nwBm38sXcF2AiFJ"
          }
        },
        {
          "range": {
            "anomaly_grade": {
              "gt": 0
            }
          }
        }
      ],
      "must_not": [
        {
          "exists": {
            "field": "task_id"
          }
        }
      ]
    }
  }
}

如果像此示例中一样指定自定义结果索引，则搜索结果 API 会同时搜索默认结果索引和自定义结果索引。

如果您未指定自定义结果索引，并且只使用 _plugins/_anomaly_detection/detectors/results/_search URL，则异常检测插件将仅搜索默认结果索引。

实时检测不会在异常结果中保留任务 ID，因此任务 ID 将为 null。

有关响应正文字段的信息，请参阅异常结果映射。

示例响应

{
  "took": 4,
  "timed_out": false,
  "_shards": {
    "total": 3,
    "successful": 3,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 90,
      "relation": "eq"
    },
    "max_score": 0,
    "hits": [
      {
        "_index": ".opensearch-anomaly-results-history-2021.10.04-1",
        "_id": "686KTXwB6HknB84SMr6G",
        "_version": 1,
        "_seq_no": 103622,
        "_primary_term": 1,
        "_score": 0,
        "_source": {
          "detector_id": "EWy02nwBm38sXcF2AiFJ",
          "confidence": 0.918886275269358,
          "model_id": "EWy02nwBm38sXcF2AiFJ_entity_error16",
          "schema_version": 4,
          "anomaly_score": 1.1093755891885446,
          "execution_start_time": 1633388475001,
          "data_end_time": 1633388414989,
          "data_start_time": 1633388114989,
          "feature_data": [
            {
              "feature_id": "ZS5zTXwBwf_U8gjUTfIn",
              "feature_name": "test_feature",
              "data": 0.532
            }
          ],
          "relevant_attribution": [
            {
              "feature_id": "ZS5zTXwBwf_U8gjUTfIn",
              "data": 1.0
            }
          ],
          "expected_values": [
            {
              "likelihood": 1,
              "value_list": [
                {
                  "feature_id": "ZS5zTXwBwf_U8gjUTfIn",
                  "data": 2
                }
              ]
            }
          ],
          "execution_end_time": 1633388475014,
          "user": {
            "backend_roles": [
              "admin"
            ],
            "custom_attribute_names": [],
            "roles": [
              "own_index",
              "all_access"
            ],
            "name": "admin",
            "user_requested_tenant": "__user__"
          },
          "anomaly_grade": 0.031023547546561225,
          "entity": [
            {
              "name": "error_type",
              "value": "error16"
            }
          ]
        }
      },
      ...
    ]
  }
}

您可以根据需要多次运行历史分析。因此，同一个检测器可能存在多个任务。

您可以先搜索最新的历史批处理任务，然后再搜索历史批处理任务结果。

使用 task_id 搜索历史分析中等级大于 0 的异常结果

请求

GET _plugins/_anomaly_detection/detectors/results/_search
POST _plugins/_anomaly_detection/detectors/results/_search
{
  "query": {
    "bool": {
      "filter": [
        {
          "term": {
            "detector_id": "Zi5zTXwBwf_U8gjUTfJG"
          }
        },
        {
          "range": {
            "anomaly_grade": {
              "gt": 0
            }
          }
        },
        {
          "term": {
            "task_id": "fm-RTXwBYwCbWecgB753"
          }
        }
      ]
    }
  }
}

示例响应

{
  "took": 915,
  "timed_out": false,
  "_shards": {
    "total": 3,
    "successful": 3,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4115,
      "relation": "eq"
    },
    "max_score": 0,
    "hits": [
      {
        "_index": ".opensearch-anomaly-results-history-2021.10.04-1",
        "_id": "VRyRTXwBDx7vzPBV8jYC",
        "_version": 1,
        "_seq_no": 149657,
        "_primary_term": 1,
        "_score": 0,
        "_source": {
          "detector_id": "Zi5zTXwBwf_U8gjUTfJG",
          "confidence": 0.9642989263957601,
          "task_id": "fm-RTXwBYwCbWecgB753",
          "model_id": "Zi5zTXwBwf_U8gjUTfJG_entity_error24",
          "schema_version": 4,
          "anomaly_score": 1.2260712437521946,
          "execution_start_time": 1633388982692,
          "data_end_time": 1631721300000,
          "data_start_time": 1631721000000,
          "feature_data": [
            {
              "feature_id": "ZS5zTXwBwf_U8gjUTfIn",
              "feature_name": "test_feature",
              "data": 10
            }
          ],
          "execution_end_time": 1633388982709,
          "user": {
            "backend_roles": [
              "admin"
            ],
            "custom_attribute_names": [],
            "roles": [
              "own_index",
              "all_access"
            ],
            "name": "admin",
            "user_requested_tenant": "__user__"
          },
          "anomaly_grade": 0.14249628345655782,
          "entity": [
            {
              "name": "error_type",
              "value": "error1"
            }
          ]
        }
      },
      ...
    ]
  }
}

搜索热门异常

1.2 中引入

返回高基数检测器的热门异常结果，按分类字段值分桶。

您可以传递 historical 布尔参数来指定您是要分析实时结果还是历史结果。

请求

GET _plugins/_anomaly_detection/detectors/<detectorId>/results/_topAnomalies?historical=false
{
  "size": 3,
  "category_field": [
    "ip"
  ],
  "order": "severity",
  "task_id": "example-task-id",
  "start_time_ms": 123456789000,
  "end_time_ms": 987654321000
}

示例响应

{
  "buckets": [
    {
      "key": {
        "ip": "1.2.3.4"
      },
      "doc_count": 10,
      "max_anomaly_grade": 0.8
    },
    {
      "key": {
        "ip": "5.6.7.8"
      },
      "doc_count": 12,
      "max_anomaly_grade": 0.6
    },
    {
      "key": {
        "ip": "9.10.11.12"
      },
      "doc_count": 3,
      "max_anomaly_grade": 0.5
    }
  ]
}

您可以指定以下选项。

选项 描述 类型 必需
大小 指定您要查看的热门桶的数量。默认值为 10。最大数量为 10,000。 整型 否
category_field 指定要聚合的类别字段集。默认为检测器的所有类别字段。 列表 否
顺序 指定 severity（异常等级）或 occurrence（异常数量）。默认为 severity。 字符串 否
task_id 指定一个历史任务 ID 以仅查看来自该特定任务的结果。仅在 historical=true 时使用，否则异常检测插件将忽略此参数。 字符串 否
start_time_ms 指定开始分析结果的时间，以 Epoch 毫秒为单位。 长整型 (long) 是
end_time_ms 指定结束分析结果的时间，以 Epoch 毫秒为单位。 长整型 (long) 是

获取检测器统计信息

1.0 版引入

提供有关插件性能的信息。

获取所有统计信息

请求

GET _plugins/_anomaly_detection/stats

示例响应

{
  "anomaly_detectors_index_status": "green",
  "anomaly_detection_state_status": "green",
  "single_entity_detector_count": 2,
  "detector_count": 5,
  "multi_entity_detector_count": 3,
  "anomaly_detection_job_index_status": "green",
  "models_checkpoint_index_status": "green",
  "anomaly_results_index_status": "green",
  "nodes": {
    "2Z4q22BySEyzakYt_A0A2A": {
      "ad_execute_request_count": 95,
      "models": [
        {
          "detector_id": "WTBnTXwBjd8s6RK4b1Sz",
          "model_type": "rcf",
          "last_used_time": 1633398197185,
          "model_id": "WTBnTXwBjd8s6RK4b1Sz_model_rcf_0",
          "last_checkpoint_time": 1633396573679
        },
        ...
      ],
      "ad_canceled_batch_task_count": 0,
      "ad_hc_execute_request_count": 75,
      "ad_hc_execute_failure_count": 0,
      "model_count": 28,
      "ad_execute_failure_count": 1,
      "ad_batch_task_failure_count": 0,
      "ad_total_batch_task_execution_count": 27,
      "ad_executing_batch_task_count": 3
    },
    "SWD7ihu9TaaW1zKwFZNVNg": {
      "ad_execute_request_count": 12,
      "models": [
        {
          "detector_id": "Zi5zTXwBwf_U8gjUTfJG",
          "model_type": "entity",
          "last_used_time": 1633398375008,
          "model_id": "Zi5zTXwBwf_U8gjUTfJG_entity_error13",
          "last_checkpoint_time": 1633392973682,
          "entity": [
            {
              "name": "error_type",
              "value": "error13"
            }
          ]
        },
        ...
      ],
      "ad_canceled_batch_task_count": 1,
      "ad_hc_execute_request_count": 0,
      "ad_hc_execute_failure_count": 0,
      "model_count": 15,
      "ad_execute_failure_count": 2,
      "ad_batch_task_failure_count": 0,
      "ad_total_batch_task_execution_count": 27,
      "ad_executing_batch_task_count": 4
    },
    "TQDUXEzyTJyV0H6_T4hYUw": {
      "ad_execute_request_count": 0,
      "models": [
        {
          "detector_id": "Zi5zTXwBwf_U8gjUTfJG",
          "model_type": "entity",
          "last_used_time": 1633398375004,
          "model_id": "Zi5zTXwBwf_U8gjUTfJG_entity_error24",
          "last_checkpoint_time": 1633388177359,
          "entity": [
            {
              "name": "error_type",
              "value": "error24"
            }
          ]
        },
        ...
      ],
      "ad_canceled_batch_task_count": 0,
      "ad_hc_execute_request_count": 0,
      "ad_hc_execute_failure_count": 0,
      "model_count": 22,
      "ad_execute_failure_count": 0,
      "ad_batch_task_failure_count": 0,
      "ad_total_batch_task_execution_count": 28,
      "ad_executing_batch_task_count": 3
    }
  }
}

model_count 参数显示每个节点内存中运行的模型总数。对于历史分析，您会看到以下字段的值

  • ad_total_batch_task_execution_count
  • ad_executing_batch_task_count
  • ad_canceled_batch_task_count
  • ad_batch_task_failure_count

如果尚未运行任何历史分析，这些值将显示为 0。

获取特定节点的所有统计信息

请求

GET _plugins/_anomaly_detection/<nodeId>/stats

获取节点的特定统计信息

请求

GET _plugins/_anomaly_detection/<nodeId>/stats/<stat>

例如，获取节点 SWD7ihu9TaaW1zKwFZNVNg 的 ad_execute_request_count 值

GET _plugins/_anomaly_detection/SWD7ihu9TaaW1zKwFZNVNg/stats/ad_execute_request_count

示例响应

{
  "nodes": {
    "SWD7ihu9TaaW1zKwFZNVNg": {
      "ad_execute_request_count": 12
    }
  }
}

获取特定类型的统计信息

请求

GET _plugins/_anomaly_detection/stats/<stat>

例如

GET _plugins/_anomaly_detection/stats/ad_executing_batch_task_count

示例响应

{
  "nodes": {
    "2Z4q22BySEyzakYt_A0A2A": {
      "ad_executing_batch_task_count": 3
    },
    "SWD7ihu9TaaW1zKwFZNVNg": {
      "ad_executing_batch_task_count": 3
    },
    "TQDUXEzyTJyV0H6_T4hYUw": {
      "ad_executing_batch_task_count": 4
    }
  }
}

分析检测器

1.0 版引入

返回与检测器当前状态和内存使用情况相关的信息，包括当前错误和 shingle 大小，以帮助排除检测器故障。

此命令通过识别为每个检测器运行异常检测器作业的节点来帮助定位日志。

它还有助于跟踪初始化百分比、所需的 shingle 以及剩余估计时间。

请求

GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile/
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all=true
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile/<type>
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile/<type1>,<type2>

示例响应

GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile

{
  "state": "DISABLED",
  "error": "Stopped detector: AD models memory usage exceeds our limit."
}

GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all=true&pretty

{
  "state": "RUNNING",
  "error": "",
  "models": [
    {
      "model_id": "3Dh6TXwBwf_U8gjURE0F_entity_KSLSh0Wv05RQXiBAQHTEZg",
      "entity": [
        {
          "name": "ip",
          "value": "192.168.1.1"
        },
        {
          "name": "error_type",
          "value": "error8"
        }
      ],
      "model_size_in_bytes": 403491,
      "node_id": "2Z4q22BySEyzakYt_A0A2A"
    },
    ...
  ],
  "total_size_in_bytes": 12911712,
  "init_progress": {
    "percentage": "100%"
  },
  "total_entities": 33,
  "active_entities": 32,
  "ad_task": {
    "ad_task": {
      "task_id": "D3I5TnwBYwCbWecg7lN9",
      "last_update_time": 1633399993685,
      "started_by": "admin",
      "state": "RUNNING",
      "detector_id": "3Dh6TXwBwf_U8gjURE0F",
      "task_progress": 0,
      "init_progress": 0,
      "execution_start_time": 1633399991933,
      "is_latest": true,
      "task_type": "HISTORICAL_HC_DETECTOR",
      "coordinating_node": "2Z4q22BySEyzakYt_A0A2A",
      "detector": {
        "name": "testhc-mc",
        "description": "test",
        "time_field": "timestamp",
        "indices": [
          "server_log"
        ],
        "filter_query": {
          "match_all": {
            "boost": 1
          }
        },
        "detection_interval": {
          "period": {
            "interval": 5,
            "unit": "Minutes"
          }
        },
        "window_delay": {
          "period": {
            "interval": 1,
            "unit": "Minutes"
          }
        },
        "shingle_size": 8,
        "schema_version": 0,
        "feature_attributes": [
          {
            "feature_id": "2zh6TXwBwf_U8gjUQ039",
            "feature_name": "test",
            "feature_enabled": true,
            "aggregation_query": {
              "test": {
                "sum": {
                  "field": "value"
                }
              }
            }
          }
        ],
        "ui_metadata": {
          "features": {
            "test": {
              "aggregationBy": "sum",
              "aggregationOf": "value",
              "featureType": "simple_aggs"
            }
          },
          "filters": []
        },
        "last_update_time": 1633387430916,
        "category_field": [
          "ip",
          "error_type"
        ],
        "user": {
          "name": "admin",
          "backend_roles": [
            "admin"
          ],
          "roles": [
            "own_index",
            "all_access"
          ],
          "custom_attribute_names": [],
          "user_requested_tenant": "__user__"
        },
        "detector_type": "MULTI_ENTITY"
      },
      "detection_date_range": {
        "start_time": 1632793800000,
        "end_time": 1633398600000
      },
      "user": {
        "name": "admin",
        "backend_roles": [
          "admin"
        ],
        "roles": [
          "own_index",
          "all_access"
        ],
        "custom_attribute_names": [],
        "user_requested_tenant": "__user__"
      }
    },
    "node_id": "2Z4q22BySEyzakYt_A0A2A",
    "task_id": "D3I5TnwBYwCbWecg7lN9",
    "task_type": "HISTORICAL_HC_DETECTOR",
    "detector_task_slots": 10,
    "total_entities_count": 32,
    "pending_entities_count": 22,
    "running_entities_count": 10,
    "running_entities": [      """[{"name":"ip","value":"192.168.1.1"},{"name":"error_type","value":"error9"}]""",
          ...],
    "entity_task_profiles": [
      {
        "shingle_size": 8,
        "rcf_total_updates": 1994,
        "threshold_model_trained": true,
        "threshold_model_training_data_size": 0,
        "model_size_in_bytes": 1593240,
        "node_id": "2Z4q22BySEyzakYt_A0A2A",
        "entity": [
          {
            "name": "ip",
            "value": "192.168.1.1"
          },
          {
            "name": "error_type",
            "value": "error7"
          }
        ],
        "task_id": "E3I5TnwBYwCbWecg9FMm",
        "task_type": "HISTORICAL_HC_ENTITY"
      },
      ...
    ]
  },
  "model_count": 32
}

GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile/total_size_in_bytes

{
  "total_size_in_bytes": 13369344
}

您只能在历史分析中看到 ad_task 字段。

model_count 参数显示检测器在每个节点内存中运行的模型总数。如果您在集群上运行了多个模型并想知道其数量，这会很有用。

如果配置了类别字段，您可以看到该字段中唯一值的数量以及所有内存中运行模型的活跃实体。

您可以使用此数据估算异常检测所需的内存量，以便决定如何调整集群大小。例如，如果一个检测器有一百万个实体，但只有其中 10 个在内存中活跃，您需要纵向或横向扩展集群。

对于单实体检测器

示例响应

{
  "state": "INIT",
  "total_size_in_bytes": 0,
  "init_progress": {
    "percentage": "0%",
    "needed_shingles": 128
  },
  "ad_task": {
    "ad_task": {
      "task_id": "cfUNOXwBFLNqSEcxAlde",
      "last_update_time": 1633044731640,
      "started_by": "admin",
      "state": "RUNNING",
      "detector_id": "qL4NOXwB__6eNorTAKtJ",
      "task_progress": 0.49603173,
      "init_progress": 1,
      "current_piece": 1632739800000,
      "execution_start_time": 1633044726365,
      "is_latest": true,
      "task_type": "HISTORICAL_SINGLE_ENTITY",
      "coordinating_node": "bCtWtxWPThq0BIn5P5I4Xw",
      "worker_node": "dIyavWhmSYWGz65b4u-lpQ",
      "detector": {
        "name": "detector1",
        "description": "test",
        "time_field": "timestamp",
        "indices": [
          "server_log"
        ],
        "filter_query": {
          "match_all": {
            "boost": 1
          }
        },
        "detection_interval": {
          "period": {
            "interval": 5,
            "unit": "Minutes"
          }
        },
        "window_delay": {
          "period": {
            "interval": 1,
            "unit": "Minutes"
          }
        },
        "shingle_size": 8,
        "schema_version": 0,
        "feature_attributes": [
          {
            "feature_id": "p74NOXwB__6eNorTAKss",
            "feature_name": "test-feature",
            "feature_enabled": true,
            "aggregation_query": {
              "test_feature": {
                "sum": {
                  "field": "value"
                }
              }
            }
          }
        ],
        "ui_metadata": {
          "features": {
            "test-feature": {
              "aggregationBy": "sum",
              "aggregationOf": "value",
              "featureType": "simple_aggs"
            }
          },
          "filters": []
        },
        "last_update_time": 1633044725832,
        "user": {
          "name": "admin",
          "backend_roles": [
            "admin"
          ],
          "roles": [
            "own_index",
            "all_access"
          ],
          "custom_attribute_names": [],
          "user_requested_tenant": "__user__"
        },
        "detector_type": "SINGLE_ENTITY"
      },
      "detection_date_range": {
        "start_time": 1632439925885,
        "end_time": 1633044725885
      },
      "user": {
        "name": "admin",
        "backend_roles": [
          "admin"
        ],
        "roles": [
          "own_index",
          "all_access"
        ],
        "custom_attribute_names": [],
        "user_requested_tenant": "__user__"
      }
    },
    "shingle_size": 8,
    "rcf_total_updates": 1994,
    "threshold_model_trained": true,
    "threshold_model_training_data_size": 0,
    "model_size_in_bytes": 1593240,
    "node_id": "dIyavWhmSYWGz65b4u-lpQ",
    "detector_task_slots": 1
  }
}

total_entities 参数显示实体总数，包括检测器的类别字段数。

获取实体总数对于具有多个类别字段的检测器的实时分析来说是一个昂贵的操作。默认情况下，对于实时检测配置文件，检测器最多计数 10,000 个实体。对于历史分析，异常检测插件默认只检测前 1,000 个实体并将其缓存到内存中，因此获取历史分析的实体总数成本不高。

profile 操作还提供有关每个实体的信息，例如实体的 last_sample_timestamp 和 last_active_timestamp。last_sample_timestamp 显示输入数据源索引中包含该实体的最后一个文档，而 last_active_timestamp 显示实体模型最后一次出现在模型缓存中的时间戳。

如果某个实体没有异常结果，则可能是该实体没有任何样本数据，或者内存和磁盘 I/O 等资源相对于实体数量受到限制。

请求

GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all=true
{
  "entity": [
    {
      "name": "host",
      "value": "i-00f28ec1eb8997686"
    }
  ]
}

示例响应

{
  "is_active": true,
  "last_active_timestamp": 1604026394879,
  "last_sample_timestamp": 1604026394879,
  "init_progress": {
    "percentage": "100%"
  },
  "model": {
    "model_id": "TFUdd3UBBwIAGQeRh5IS_entity_i-00f28ec1eb8997686",
    "model_size_in_bytes": 712480,
    "node_id": "MQ-bTBW3Q2uU_2zX3pyEQg"
  },
  "state": "RUNNING"
}

要仅获取历史分析的配置文件信息，请指定 ad_task。对于多类别高基数检测器，指定 _all 是一项昂贵的操作。

请求

GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile/ad_task

示例响应

{
  "ad_task": {
    "ad_task": {
      "task_id": "CHI0TnwBYwCbWecgqgRA",
      "last_update_time": 1633399648413,
      "started_by": "admin",
      "state": "RUNNING",
      "detector_id": "3Dh6TXwBwf_U8gjURE0F",
      "task_progress": 0,
      "init_progress": 0,
      "execution_start_time": 1633399646784,
      "is_latest": true,
      "task_type": "HISTORICAL_HC_DETECTOR",
      "coordinating_node": "2Z4q22BySEyzakYt_A0A2A",
      "detector": {
        "name": "testhc-mc",
        "description": "test",
        "time_field": "timestamp",
        "indices": [
          "server_log"
        ],
        "filter_query": {
          "match_all": {
            "boost": 1
          }
        },
        "detection_interval": {
          "period": {
            "interval": 5,
            "unit": "Minutes"
          }
        },
        "window_delay": {
          "period": {
            "interval": 1,
            "unit": "Minutes"
          }
        },
        "shingle_size": 8,
        "schema_version": 0,
        "feature_attributes": [
          {
            "feature_id": "2zh6TXwBwf_U8gjUQ039",
            "feature_name": "test",
            "feature_enabled": true,
            "aggregation_query": {
              "test": {
                "sum": {
                  "field": "value"
                }
              }
            }
          }
        ],
        "ui_metadata": {
          "features": {
            "test": {
              "aggregationBy": "sum",
              "aggregationOf": "value",
              "featureType": "simple_aggs"
            }
          },
          "filters": []
        },
        "last_update_time": 1633387430916,
        "category_field": [
          "ip",
          "error_type"
        ],
        "user": {
          "name": "admin",
          "backend_roles": [
            "admin"
          ],
          "roles": [
            "own_index",
            "all_access"
          ],
          "custom_attribute_names": [],
          "user_requested_tenant": "__user__"
        },
        "detector_type": "MULTI_ENTITY"
      },
      "detection_date_range": {
        "start_time": 1632793800000,
        "end_time": 1633398600000
      },
      "user": {
        "name": "admin",
        "backend_roles": [
          "admin"
        ],
        "roles": [
          "own_index",
          "all_access"
        ],
        "custom_attribute_names": [],
        "user_requested_tenant": "__user__"
      }
    },
    "node_id": "2Z4q22BySEyzakYt_A0A2A",
    "task_id": "CHI0TnwBYwCbWecgqgRA",
    "task_type": "HISTORICAL_HC_DETECTOR",
    "detector_task_slots": 10,
    "total_entities_count": 32,
    "pending_entities_count": 22,
    "running_entities_count": 10,
    "running_entities" : [
      """[{"name":"ip","value":"192.168.1.1"},{"name":"error_type","value":"error9"}]""",
      ...
    ],
    "entity_task_profiles": [
      {
        "shingle_size": 8,
        "rcf_total_updates": 994,
        "threshold_model_trained": true,
        "threshold_model_training_data_size": 0,
        "model_size_in_bytes": 1593240,
        "node_id": "2Z4q22BySEyzakYt_A0A2A",
        "entity": [
          {
            "name": "ip",
            "value": "192.168.1.1"
          },
          {
            "name": "error_type",
            "value": "error6"
          }
        ],
        "task_id": "9XI0TnwBYwCbWecgsAd6",
        "task_type": "HISTORICAL_HC_ENTITY"
      },
      ...
    ]
  }
}

删除检测器结果

1.1 版本引入

根据查询删除检测器的结果。

删除检测器结果 API 仅删除默认结果索引中的异常结果文档。它不支持删除存储在任何自定义结果索引中的异常结果文档。

您需要手动从自定义结果索引中删除不需要的异常结果文档。

请求

DELETE _plugins/_anomaly_detection/detectors/results
{
  "query": {
    "bool": {
      "filter": [
        {
          "term": {
            "detector_id": {
              "value": "rlDtOHwBD5tpxlbyW7Nt"
            }
          }
        },
        {
          "term": {
            "task_id": {
              "value": "TM3tOHwBCi2h__AOXlyQ"
            }
          }
        },
        {
          "range": {
            "data_start_time": {
              "lte": 1632441600000
            }
          }
        }
      ]
    }
  }
}

示例响应

{
  "took": 48,
  "timed_out": false,
  "total": 28,
  "updated": 0,
  "created": 0,
  "deleted": 28,
  "batches": 1,
  "version_conflicts": 0,
  "noops": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "throttled_millis": 0,
  "requests_per_second": -1,
  "throttled_until_millis": 0,
  "failures": []
}

创建监视器

1.0 版引入

创建监视器以设置检测器的警报。

请求

POST _plugins/_alerting/monitors
{
  "type": "monitor",
  "name": "test-monitor",
  "enabled": true,
  "schedule": {
    "period": {
      "interval": 20,
      "unit": "MINUTES"
    }
  },
  "inputs": [
    {
      "search": {
        "indices": [
          ".opensearch-anomaly-results*"
        ],
        "query": {
          "size": 1,
          "query": {
            "bool": {
              "filter": [
                {
                  "range": {
                    "data_end_time": {
                      "from": "||-20m",
                      "to": "",
                      "include_lower": true,
                      "include_upper": true,
                      "boost": 1
                    }
                  }
                },
                {
                  "term": {
                    "detector_id": {
                      "value": "m4ccEnIBTXsGi3mvMt9p",
                      "boost": 1
                    }
                  }
                }
              ],
              "adjust_pure_negative": true,
              "boost": 1
            }
          },
          "sort": [
            {
              "anomaly_grade": {
                "order": "desc"
              }
            },
            {
              "confidence": {
                "order": "desc"
              }
            }
          ],
          "aggregations": {
            "max_anomaly_grade": {
              "max": {
                "field": "anomaly_grade"
              }
            }
          }
        }
      }
    }
  ],
  "triggers": [
    {
      "name": "test-trigger",
      "severity": "1",
      "condition": {
        "script": {
          "source": "return ctx.results[0].aggregations.max_anomaly_grade.value != null && ctx.results[0].aggregations.max_anomaly_grade.value > 0.7 && ctx.results[0].hits.hits[0]._source.confidence > 0.7",
          "lang": "painless"
        }
      },
      "actions": [
        {
          "name": "test-action",
          "destination_id": "ld7912sBlQ5JUWWFThoW",
          "message_template": {
            "source": "This is my message body."
          },
          "throttle_enabled": false,
          "subject_template": {
            "source": "TheSubject"
          }
        }
      ]
    }
  ]
}

示例响应

{
  "_id": "OClTEnIBmSf7y6LP11Jz",
  "_version": 1,
  "_seq_no": 10,
  "_primary_term": 1,
  "monitor": {
    "type": "monitor",
    "schema_version": 1,
    "name": "test-monitor",
    "enabled": true,
    "enabled_time": 1589445384043,
    "schedule": {
      "period": {
        "interval": 20,
        "unit": "MINUTES"
      }
    },
    "inputs": [
      {
        "search": {
          "indices": [
            ".opensearch-anomaly-results*"
          ],
          "query": {
            "size": 1,
            "query": {
              "bool": {
                "filter": [
                  {
                    "range": {
                      "data_end_time": {
                        "from": "||-20m",
                        "to": "",
                        "include_lower": true,
                        "include_upper": true,
                        "boost": 1
                      }
                    }
                  },
                  {
                    "term": {
                      "detector_id": {
                        "value": "m4ccEnIBTXsGi3mvMt9p",
                        "boost": 1
                      }
                    }
                  }
                ],
                "adjust_pure_negative": true,
                "boost": 1
              }
            },
            "sort": [
              {
                "anomaly_grade": {
                  "order": "desc"
                }
              },
              {
                "confidence": {
                  "order": "desc"
                }
              }
            ],
            "aggregations": {
              "max_anomaly_grade": {
                "max": {
                  "field": "anomaly_grade"
                }
              }
            }
          }
        }
      }
    ],
    "triggers": [
      {
        "id": "NilTEnIBmSf7y6LP11Jr",
        "name": "test-trigger",
        "severity": "1",
        "condition": {
          "script": {
            "source": "return ctx.results[0].aggregations.max_anomaly_grade.value != null && ctx.results[0].aggregations.max_anomaly_grade.value > 0.7 && ctx.results[0].hits.hits[0]._source.confidence > 0.7",
            "lang": "painless"
          }
        },
        "actions": [
          {
            "id": "NylTEnIBmSf7y6LP11Jr",
            "name": "test-action",
            "destination_id": "ld7912sBlQ5JUWWFThoW",
            "message_template": {
              "source": "This is my message body.",
              "lang": "mustache"
            },
            "throttle_enabled": false,
            "subject_template": {
              "source": "TheSubject",
              "lang": "mustache"
            }
          }
        ]
      }
    ],
    "last_update_time": 1589445384043
  }
}
剩余 350 字符

有问题？。

想贡献？ 或 。