Watcher 工作原理

您可以添加 Watch，以便在满足特定条件时自动执行操作。条件通常基于您加载到 Watch 中的数据，也称为Watch Payload。此 Payload 可以从不同的来源加载 - 来自 Elasticsearch、外部 HTTP 服务，甚至两者结合。

例如，您可以配置一个 Watch，当日志数据中的搜索表明在过去 5 分钟内有太多 503 错误时，向系统管理员发送电子邮件。

本主题描述了 Watch 的元素以及 Watch 的操作方式。

Watch 定义编辑

一个 Watch 包含一个触发器、输入、条件和操作。操作定义了满足条件后需要执行的操作。此外，您可以定义条件和转换，以在执行操作之前处理和准备 Watch Payload。

例如，以下代码段显示了一个创建或更新 Watch 请求，该请求定义了一个查找日志错误事件的 Watch

PUT _watcher/watch/log_errors
{
  "metadata" : { 
    "color" : "red"
  },
  "trigger" : { 
    "schedule" : {
      "interval" : "5m"
    }
  },
  "input" : { 
    "search" : {
      "request" : {
        "indices" : "log-events",
        "body" : {
          "size" : 0,
          "query" : { "match" : { "status" : "error" } }
        }
      }
    }
  },
  "condition" : { 
    "compare" : { "ctx.payload.hits.total" : { "gt" : 5 }}
  },
  "transform" : { 
    "search" : {
        "request" : {
          "indices" : "log-events",
          "body" : {
            "query" : { "match" : { "status" : "error" } }
          }
        }
    }
  },
  "actions" : { 
    "my_webhook" : {
      "webhook" : {
        "method" : "POST",
        "host" : "mylisteninghost",
        "port" : 9200,
        "path" : "/{{watch_id}}",
        "body" : "Encountered {{ctx.payload.hits.total}} errors"
      }
    },
    "email_administrator" : {
      "email" : {
        "to" : "[email protected]",
        "subject" : "Encountered {{ctx.payload.hits.total}} errors",
        "body" : "Too many error in the system, see attached data",
        "attachments" : {
          "attached_data" : {
            "data" : {
              "format" : "json"
            }
          }
        },
        "priority" : "high"
      }
    }
  }
}

Watch 执行编辑

当您添加一个 Watch 时，Watcher 会立即将其触发器注册到相应的触发器引擎。具有 schedule 触发器的 Watch 会注册到 scheduler 触发器引擎。

调度程序跟踪时间并根据其计划触发 Watch。在包含一个或多个 .watches 分片的每个节点上，都会运行一个与 Watcher 生命周期绑定的调度程序。即使所有主分片和副本都已考虑在内，当触发 Watch 时，Watcher 也会确保每个 Watch 仅在一个分片上触发。您添加的副本分片越多，Watch 的执行分布就越分散。如果您添加或删除副本，则所有 Watch 都需要重新加载。如果分片被重新分配，则此特定分片的 primary 和所有副本都将重新加载。

由于 Watch 在包含 Watch 分片的节点上执行，因此您可以通过使用分片分配过滤来创建专用的 Watcher 节点。

您可以使用专用的 node.attr.role: watcher 属性配置节点，然后像这样配置 .watches 索引

response = client.indices.put_settings(
  index: '.watches',
  body: {
    'index.routing.allocation.include.role' => 'watcher'
  }
)
puts response

PUT .watches/_settings
{
  "index.routing.allocation.include.role": "watcher"
}

当 Watcher 服务停止时，调度程序也会随之停止。触发器引擎使用与执行 Watch 所使用的线程池不同的线程池。

当触发 Watch 时，Watcher 会将其排队以供执行。一个 watch_record 文档被创建并添加到 Watch 历史记录中，Watch 的状态被设置为 awaits_execution。

当执行开始时，Watcher 会为 Watch 创建一个 Watch 执行上下文。执行上下文为脚本和模板提供了对 Watch 元数据、Payload、Watch ID、执行时间和触发器信息的访问权限。有关更多信息，请参阅Watch 执行上下文。

在执行过程中，Watcher 会

当 Watch 执行完成时，执行结果将作为Watch 记录记录在 Watch 历史记录中。Watch 记录包括执行时间和持续时间、Watch 条件是否满足以及执行的每个操作的状态。

下图显示了 Watch 执行过程

Watch 确认和节流编辑

Watcher 支持基于时间和基于确认的节流。这使您能够防止对同一事件重复执行操作。

默认情况下，Watcher 使用基于时间的节流，节流周期为 5 秒。这意味着，如果 Watch 每秒执行一次，其操作最多每 5 秒执行一次，即使条件始终满足也是如此。您可以在每个操作的基础上或在 Watch 级别配置节流周期。

基于确认的节流使您能够告诉 Watcher，只要条件满足，就不要再发送有关 Watch 的任何通知。一旦条件评估为 false，确认将被清除，Watcher 将恢复正常执行 Watch 操作。

有关更多信息，请参阅确认和节流。

Watch 活动状态编辑

默认情况下，当您添加一个 Watch 时，它会立即设置为活动状态，注册到相应的触发器引擎，并根据其配置的触发器执行。

您也可以将 Watch 设置为非活动状态。非活动 Watch 不会注册到触发器引擎，也永远不会被触发。

要在创建 Watch 时将其设置为非活动状态，请将active 参数设置为inactive。要停用现有 Watch，请使用停用 Watch API。要重新激活非活动 Watch，请使用激活 Watch API。

停用 Watch 在各种情况下很有用。例如，如果您有一个监控外部系统的 Watch，并且您需要将该系统停机以进行维护，您可以停用 Watch 以防止它在维护窗口期间错误地报告可用性问题。

停用 Watch 还使您能够保留它以备将来使用，而无需将其从系统中删除。

脚本和模板编辑

在定义 Watch 时，您可以使用脚本和模板。脚本和模板可以引用 Watch 执行上下文中的元素，包括 Watch Payload。执行上下文定义了您可以在脚本中使用的变量以及模板中的参数占位符。

Watcher 使用 Elasticsearch 脚本基础设施，该基础设施支持内联 和存储的。脚本和模板由 Elasticsearch 编译和缓存，以优化重复执行。还支持自动加载。有关更多信息，请参阅脚本 和如何编写脚本。

Watch 执行上下文编辑

以下代码段显示了Watch 执行上下文的基本结构

{
  "ctx" : {
    "metadata" : { ... }, 
    "payload" : { ... }, 
    "watch_id" : "<id>", 
    "execution_time" : "20150220T00:00:10Z", 
    "trigger" : { 
      "triggered_time" : "20150220T00:00:10Z",
      "scheduled_time" : "20150220T00:00:00Z"
    },
    "vars" : { ... } 
}

使用脚本编辑

您可以使用脚本定义 条件 和 转换。默认脚本语言是 Painless。

脚本可以引用观察执行上下文中的任何值，或者通过脚本参数显式传递的值。

例如，如果观察元数据包含一个 color 字段（例如 "metadata" : {"color": "red"}），您可以通过 ctx.metadata.color 变量访问它的值。如果您在条件或转换定义中传递一个 color 参数（例如 "params" : {"color": "red"}），您可以通过 color 变量访问它的值。

使用模板编辑

您可以使用模板为观察定义动态内容。在执行时，模板会从观察执行上下文中提取数据。例如，您可以使用模板使用存储在观察有效负载中的数据填充 email 操作的 subject 字段。模板还可以访问通过模板参数显式传递的值。

您可以使用 Mustache 脚本语言指定模板。

例如，以下代码段显示了模板如何在发送的电子邮件中启用动态主题

{
  "actions" : {
    "email_notification" : {
      "email" : {
        "subject" : "{{ctx.metadata.color}} alert"
      }
    }
  }
}

内联模板和脚本编辑

要定义内联模板或脚本，您只需在字段的值中直接指定它。例如，以下代码段使用引用上下文元数据中 color 值的内联模板配置 email 操作的主题。

"actions" : {
  "email_notification" : {
     "email" : {
       "subject" : "{{ctx.metadata.color}} alert"
     }
   }
  }
}

对于脚本，您只需将内联脚本指定为 script 字段的值。例如

"condition" : {
  "script" : "return true"
}

您也可以通过使用正式的对象定义作为字段值来显式指定内联类型。例如

"actions" : {
  "email_notification" : {
    "email" : {
      "subject" : {
         "source" : "{{ctx.metadata.color}} alert"
      }
    }
  }
}

脚本的正式对象定义将是

"condition" : {
  "script" : {
    "source": "return true"
  }
}

存储的模板和脚本编辑

如果您 存储您的模板和脚本，您可以通过 ID 引用它们。

要引用存储的脚本或模板，请使用正式的对象定义并在 id 字段中指定其 ID。例如，以下代码段引用了 email_notification_subject 模板

{
  ...
  "actions" : {
    "email_notification" : {
      "email" : {
        "subject" : {
          "id" : "email_notification_subject",
          "params" : {
            "color" : "red"
          }
        }
      }
    }
  }
}