elasticsearch-anomaly-detection

Elasticsearch 异常检测

在时间序列数据上创建、打开并启动 ML 异常检测作业。选择合适的计数族检测器方向，配置桶跨度和时间字段，将数据馈送连接到正确的索引，并通过统计信息确认运行状态，而不是凭猜测。

环境配置

此技能通过 elastic CLI 执行 Elasticsearch 操作。如果未安装 elastic CLI，请告知用户其用途。不要猜测凭据、直接调用 HTTP API， 也不要尝试其他变通方法。

此技能以 HTTP 简写形式引用操作（例如 GET /、GET /_cat/indices、GET /{index}/_mapping、 GET /{index}/_settings/index.mode、POST /_query）。本文档末尾的 操作 表格 列出了每种简写对应的 elastic CLI 命令——始终使用 CLI，而不是直接调用 HTTP API。

前提条件： 在自托管集群上进行 ML 异常检测需要相当于 Platinum 的许可证。Serverless 项目包含 ML。调用方需要具备 manage_ml 权限才能创建和管理作业。

相关技能： 作业运行后，如需解读异常评分、影响因素和模型行为，请使用 elasticsearch-anomaly-detection-explainer，而不是此技能。

流程

1. 查找目标索引和时间字段。 使用 GET /_cat/indices 列出候选索引（用户指定索引时，传入匹配模式）。使用 GET /{index}/_mapping 获取所选索引的字段类型。需要确认索引存在、识别时间字段（通常为 @timestamp），并验证文档量足以用于基线学习。切勿猜测索引名或字段名——它们因部署而异。

2. 选择检测器函数和方向。 根据用户意图，在 analysis_config.detectors 中选择计数类检测器：

   • 事件量激增、骤增或异常增加 → high_count（也可以使用 count，它会检测两个方向；如果用户关注激增，也可接受）。不要使用 low_count——它会漏掉激增。
   • 事件量下降、服务中断、事件缺失或流量停止 → low_count。不要使用 high_count——它会漏掉下降和静默情况。
   • 指标偏差（CPU、延迟、数值字段）→ 使用均值类函数（mean、high_mean、low_mean），并设置 field_name——仅当用户询问数值指标时使用，不适用于原始事件量。

   需要选择一个方向与异常类型相符的主要检测器。对于文档计数的事件量激增／下降问题，应使用计数类检测器；均值类检测器不适合回答“有多少事件”这类问题。

3. 创建前设定不可变的作业结构。 以下字段在 PUT /_ml/anomaly_detectors/{job_id} 后无法更改：

   • analysis_config.bucket_span — 使用用户指定的时间间隔（例如，用 15m 表示 15 分钟的时间桶）。应匹配所关注异常的粒度；时间间隔过短会产生噪声，过长则会延迟检测。
   • data_description.time_field — 使用映射中的时间字段（通常为 @timestamp）。
   • analysis_config.detectors — 使用第 2 步选定的函数和方向。

   事件量激增检测器的作业正文示例：

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

   服务中断／事件量下降检测器的示例：

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

4. 创建作业。 使用用户指定的作业 ID（或建议一个描述性 ID）调用 PUT /_ml/anomaly_detectors/{job_id}。作业创建后处于 closed 状态——创建作业并不会启动分析。

5. 创建数据馈送。 创建作业后立即调用 PUT /_ml/datafeeds/datafeed-{job_id}。将 job_id 设为相同的 ID，将 indices 设为目标索引（使用第 1 步中的确切名称或匹配模式），并设置一个用于筛选相关文档的查询（通常为 match_all）。数据馈送 ID 的命名约定为 datafeed-{job_id}。

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

6. 先打开作业，再启动数据馈送——顺序不能颠倒。 必须按此顺序执行，不能跳过或调整：

   1. POST /_ml/anomaly_detectors/{job_id}/_open — 将作业转换为 opened 状态。
   2. POST /_ml/datafeeds/datafeed-{job_id}/_start — 将数据馈送转换为 started 状态。

   数据馈送不存在时，打开作业会失败。在打开作业之前启动数据馈送也会失败。仅创建资源后不能报告成功——只有作业和数据馈送都处于活动状态时，作业才算正在运行。

7. 通过统计信息确认运行状态。 使用以下请求验证结果：

   • GET /_ml/anomaly_detectors/{job_id}/_stats — 预期状态为 state: "opened"。
   • GET /_ml/datafeeds/datafeed-{job_id}/_stats — 预期状态为 state: "started"。

   也可以调用 GET /_ml/anomaly_detectors/{job_id}，确认配置（检测器、bucket_span、time_field、数据馈送索引）。明确报告两项统计信息中的状态——“已创建”不等于“已打开”和“已启动”。

拆除

停止或删除作业时，应按启动顺序的逆序操作：

1. POST /_ml/datafeeds/datafeed-{job_id}/_stop — 先停止数据馈送。
2. POST /_ml/anomaly_detectors/{job_id}/_close — 然后关闭作业。

关闭作业前先停止数据馈送。重置或删除作业前先关闭作业。

指南

• 必需的生命周期顺序（创建）： job → datafeed → 打开 job → 启动 datafeed。每个新 job 都遵循此 顺序。
• 检测器方向是影响最大的决策，尤其是针对数量异常。重新阅读用户的措辞：“spike”（激增）、 “surge”（骤增）和“unusual increase”（异常增加）→ 高方向；“drop”（下降）、“outage”（中断）、 “stops”（停止）和“absence”（缺失）→ 低方向。
• 不可变字段（bucket_span、detectors、time_field）若设置错误，必须删除并重新创建——在首次 PUT 前验证映射和意图。
• Datafeed 索引必须与用户指定的目标一致。 将 indices 指向用户指定的确切索引或模式，而不是 近似猜测。
• 实体级分析（by_field_name、over_field_name、partition_field_name）和高级调优请参阅 references/anomaly-detection-reference.md。

完整参考

有关 API 路径、请求／响应字段、分数含义和字段交互，请阅读 references/anomaly-detection-reference.md。

操作

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