« 获取过滤器 API 打开异常检测作业 API »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›REST API ›机器学习异常检测 API

获取记录 API

编辑

获取记录 API编辑

检索异常检测作业的异常记录。

请求编辑

GET _ml/anomaly_detectors/<job_id>/results/records

先决条件编辑

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述编辑

记录包含详细的分析结果。它们根据检测器配置描述了在输入数据中识别出的异常活动。

根据输入数据的特征和大小，可能存在许多异常记录。实际上，通常太多而无法手动处理它们。因此，机器学习功能会对异常记录进行复杂的聚合，并将它们分组到桶中。

记录结果的数量取决于每个桶中发现的异常数量，这与建模的时间序列数量和检测器数量有关。

路径参数编辑

<job_id>
(必需，字符串) 异常检测作业的标识符。

查询参数编辑

desc
(可选，布尔值) 如果为 true，则结果按降序排序。
end
(可选，字符串) 返回时间戳早于此时间的记录。默认为 -1，这意味着它未设置，结果不会限制在特定时间戳。
exclude_interim
(可选，布尔值) 如果 true，则输出不包含中间结果。默认为 false，这意味着包含中间结果。
from
(可选，整数) 跳过指定数量的记录。默认为 0。
record_score
(可选，双精度) 返回异常分数大于或等于此值的记录。默认为 0.0。
size
(可选，整数) 指定要获取的最大记录数。默认为 100。
sort
(可选，字符串) 指定请求记录的排序字段。默认情况下，记录按 record_score 值排序。
start
(可选，字符串) 返回时间戳晚于此时间的记录。默认为 -1，这意味着它未设置，结果不会限制在特定时间戳。

请求主体编辑

您也可以在请求主体中指定查询参数；例外情况是 from 和 size，请使用 page 代替

page
page 的属性
from
(可选，整数) 跳过指定数量的记录。默认为 0。
size
(可选，整数) 指定要获取的最大记录数。默认为 100。

响应主体编辑

API 返回一个记录对象数组，这些对象具有以下属性

actual
(数组) 桶的实际值。
anomaly_score_explanation

(对象) 如果存在，它将提供有关影响初始异常分数的因素的信息。

anomaly_score_explanation 的属性
anomaly_characteristics_impact
(可选，整数) 检测到的异常的持续时间和幅度相对于历史平均值的冲击。
anomaly_length
(可选，整数) 检测到的异常的长度（以桶数表示）。
anomaly_type
(可选，字符串) 检测到的异常类型：峰值或谷值。
high_variance_penalty
(可选，布尔值) 指示是否降低具有较大置信区间的桶的异常分数。如果桶具有较大置信区间，则分数会降低。
incomplete_bucket_penalty
(可选，布尔值) 如果桶包含的样本少于预期，则分数会降低。如果桶包含的样本少于预期，则分数会降低。
lower_confidence_bound
(可选，双精度) 95% 置信区间的下限。
multimodal_distribution
(可选，布尔值) 指示桶值的概率分布是否具有多个众数。当存在多个众数时，典型值可能不是最可能的。
multi_bucket_impact
(可选，整数) 过去 12 个桶中实际值和典型值之间偏差的影响。
single_bucket_impact
(可选，整数) 当前桶中实际值和典型值之间偏差的影响。
typical_value
(可选，双精度) 此桶的典型（预期）值。
upper_confidence_bound
(可选，双精度) 95% 置信区间的上限。
bucket_span
(数字) 桶的长度（以秒为单位）。此值与作业中指定的 bucket_span 相匹配。
by_field_name
(字符串) 用于拆分数据的字段。特别是，此属性用于分析拆分相对于其自身历史记录的情况。它用于在拆分上下文中查找异常值。
by_field_value
(字符串) by_field_name 的值。
causes
(数组) 对于总体分析，必须在检测器中指定一个 over 字段。此属性包含一个异常记录数组，这些记录是为 over 字段识别的异常的原因。如果不存在 over 字段，则此字段不存在。此子资源包含 over_field_name 的最异常记录。出于可扩展性原因，最多返回 10 个最显著的异常原因。作为核心分析建模的一部分，这些低级异常记录会针对其父 over 字段记录进行聚合。causes 资源包含与 record 资源类似的元素，即 actual、typical、geo_results.actual_point、geo_results.typical_point、*_field_name 和 *_field_value。概率和分数不适用于原因。
detector_index
(数字) 检测器的唯一标识符。
field_name
(字符串) 某些函数需要一个字段才能对其进行操作，例如 sum()。对于这些函数，此值是要分析的字段的名称。
function
(字符串) 发生异常的函数，如检测器配置中指定。例如，max。
function_description
(字符串) 发生异常的函数的描述，如检测器配置中指定。
geo_results

(可选，对象) 如果检测器函数是 lat_long，则此对象包含实际值和典型值的纬度和经度的逗号分隔字符串。

geo_results 的属性
actual_point
(字符串) 桶的实际值，格式化为 geo_point。
typical_point
(字符串) 桶的典型值，格式化为 geo_point。
influencers
(数组) 如果在检测器配置中指定了 influencers，则此数组包含导致或应归咎于异常的影响因素。
initial_record_score
(数字) 0-100 之间的归一化分数，基于此记录异常性的概率。这是在处理桶时计算出的初始值。
is_interim
(布尔值) 如果 true，则这是一个中间结果。换句话说，结果是根据部分输入数据计算的。
job_id
(字符串) 异常检测作业的标识符。
multi_bucket_impact
(数字) 指示异常是多桶还是单桶的程度。该值在 -5.0 到 +5.0 的范围内，其中 -5.0 表示异常纯粹是单桶，而 +5.0 表示异常纯粹是多桶。
over_field_name
(字符串) 用于拆分数据的字段。特别是，此属性用于分析拆分相对于所有拆分历史记录的情况。它用于在所有拆分的总体中查找异常值。有关更多信息，请参阅 执行总体分析。
over_field_value
(字符串) over_field_name 的值。
partition_field_name
(字符串) 用于对分析进行分段的字段。当您使用此属性时，您将为该字段的每个值拥有完全独立的基线。
partition_field_value
(字符串) partition_field_name 的值。
probability
(数字) 单个异常发生的概率，范围为 0 到 1。例如，0.0000772031。此值可以保持超过 300 位小数的精度，因此提供 record_score 作为此值的易于理解的友好解释。
record_score
(数字) 0-100 之间的归一化分数，基于此记录异常性的概率。与 initial_record_score 不同，此值将在分析新数据时通过重新归一化过程进行更新。
result_type
(字符串) 内部。这始终设置为 record。
timestamp
(日期) 为其计算这些结果的桶的开始时间。
typical
(数组) 根据分析建模，桶的典型值。

根据正在分析的字段，会添加其他记录属性。例如，如果它正在分析 hostname 作为by 字段，则会将字段 hostname 添加到结果文档中。此信息使您能够更轻松地过滤异常结果。

示例编辑

response = client.ml.get_records(
  job_id: 'low_request_rate',
  body: {
    sort: 'record_score',
    desc: true,
    start: '1454944100000'
  }
)
puts response
GET _ml/anomaly_detectors/low_request_rate/results/records
{
  "sort": "record_score",
  "desc": true,
  "start": "1454944100000"
}
{
  "count" : 4,
  "records" : [
    {
      "job_id" : "low_request_rate",
      "result_type" : "record",
      "probability" : 1.3882308899968812E-4,
      "multi_bucket_impact" : -5.0,
      "record_score" : 94.98554565630553,
      "initial_record_score" : 94.98554565630553,
      "bucket_span" : 3600,
      "detector_index" : 0,
      "is_interim" : false,
      "timestamp" : 1577793600000,
      "function" : "low_count",
      "function_description" : "count",
      "typical" : [
        28.254208230188834
      ],
      "actual" : [
        0.0
      ]
    },
  ...
  ]
}
« 获取过滤器 API 打开异常检测作业 API »