« 创建索引阈值规则 创建跟踪包含规则 »
Elastic 文档 ›Kibana 指南 [8.14] ›警报 ›规则类型

创建 Elasticsearch 查询规则

编辑

创建 Elasticsearch 查询规则编辑

Elasticsearch 查询规则类型运行用户配置的查询，将匹配项数量与配置的阈值进行比较，并在满足阈值条件时安排操作运行。

在 堆栈管理 > 规则 中，单击 创建规则。选择 Elasticsearch 查询 规则类型，然后填写名称和可选标签。可以使用 Elasticsearch 查询领域特定语言 (DSL)、Elasticsearch 查询语言 (ES|QL)、Kibana 查询语言 (KQL) 或 Lucene 来定义 Elasticsearch 查询规则。

定义条件编辑

创建 Elasticsearch 查询规则时，您选择的查询类型会影响您必须提供的信息。例如

Define the condition to detect

  1. 定义您的查询

    如果您使用 查询 DSL，则必须选择索引和时间字段，然后提供您的查询。仅使用 query、fields、_source 和 runtime_mappings 字段，其他 DSL 字段不被考虑。例如

    {
    "query":{
      "match_all" : {}
    }
 }

    如果您使用 KQL 或 Lucene，则必须指定数据视图，然后定义基于文本的查询。例如，http.request.referrer: "https://example.com"。

    [预览] 不要在生产环境中使用 ES|QL。此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 如果您使用 ES|QL，则必须提供一个源命令，后跟一个可选的处理命令序列，这些命令由管道字符 (|) 分隔。例如

    FROM kibana_sample_data_logs
| STATS total_bytes = SUM(bytes) BY host
| WHERE total_bytes > 200000
| SORT total_bytes DESC
| LIMIT 10

  2. 如果您使用查询 DSL、KQL 或 Lucene，请设置组和阈值。

    何时
    指定如何计算与阈值进行比较的值。该值通过在时间窗口内聚合数字字段来计算。聚合选项包括：count、average、sum、min 和 max。使用 count 时，使用文档计数，不需要聚合字段。
    超过或分组超过
    指定是否将聚合应用于所有文档，或者使用最多四个分组字段将其拆分为组。如果您选择使用分组，则为 terms 或 multi terms aggregation；当满足条件时，将为每个唯一的值集创建警报。为了限制高基数字段上的警报数量，您必须指定要针对阈值检查的组数。仅检查前几个组。
    阈值
    定义阈值和比较运算符 (is above、is above or equals、is below、is below or equals 或 is between)。由聚合计算的值将与该阈值进行比较。
  3. 设置时间窗口，该窗口定义了搜索文档的回溯时间。
  4. 如果您使用查询 DSL、KQL 或 Lucene，请设置要发送到配置操作的文档数量，这些文档在满足阈值条件时会发送。
  5. 如果您使用查询 DSL、KQL 或 Lucene，请选择是否通过排除先前运行中的匹配项来避免警报重复。使用分组字段时，此选项不可用。
  6. 设置检查间隔，该间隔定义了评估规则条件的频率。通常，此值应设置为小于时间窗口的值，以避免检测中的间隙。
  7. 在高级选项中，您可以更改必须满足规则条件才能触发警报的连续运行次数。默认值为 1。
  8. 选择范围值，该值会影响访问规则所需的 Kibana 功能权限。例如，当它设置为 Stack Rules 时，您必须具有相应的 管理 > 堆栈规则 功能权限才能查看或编辑规则。

测试您的查询编辑

使用 测试查询 功能来验证您的查询是否有效。

如果您使用查询 DSL、KQL 或 Lucene，则查询会使用配置的时间窗口针对选定的索引运行。将显示与查询匹配的文档数量。例如

Test Elasticsearch query returns number of matches when valid

[预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 如果您使用 ES|QL 查询，则会显示一个表格。例如

Test ES|QL query returns a table when valid

如果查询无效，则会发生错误。

添加操作编辑

您可以选择在满足规则条件时以及不再满足规则条件时发送通知。特别是，此规则类型支持

  • 警报摘要
  • 在查询匹配时运行的操作
  • 在不再满足规则条件时运行的恢复操作

对于每个操作，您必须选择一个连接器，该连接器提供 Kibana 服务或第三方集成的连接信息。有关所有支持的连接器的更多信息，请转到 连接器。

选择连接器后，您必须设置操作频率。您可以选择在每个检查间隔或自定义间隔创建警报摘要。例如，发送电子邮件通知，以自定义间隔汇总新的、正在进行的和已恢复的警报

UI for defining alert summary action in an Elasticsearch query rule

或者，您可以设置操作频率，以便每个警报都运行操作。选择操作运行的频率（在每个检查间隔、仅在警报状态更改时或在自定义操作间隔）。您还必须选择一个操作组，该组指示操作是在查询匹配时运行还是在警报恢复时运行。每个连接器都支持每个操作组的一组特定操作。例如

UI for defining a recovery action

您可以通过指定操作仅在与 KQL 查询匹配时或在警报在特定时间范围内发生时运行，来进一步细化操作运行的条件。

添加操作变量编辑

在 Kibana 中创建规则时，它会提供适合每个操作的示例消息。例如，以下消息是为每个警报运行的服务器日志连接器操作提供的

Elasticsearch query rule '{{rule.name}}' is active:

- Value: {{context.value}}
- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}
- Timestamp: {{context.date}}
- Link: {{context.link}}

规则使用规则操作变量和 Mustache 模板将上下文详细信息传递到警报通知中。有一组 对所有规则通用的变量 和一组特定于此规则的变量。要在 Kibana 中查看变量列表，请单击“添加规则变量”按钮。例如

Passing rule values to an action

以下变量特定于 Elasticsearch 查询规则

context.conditions
(字符串) 条件的描述。例如：Query matched documents。
context.date
(字符串) 规则满足条件的日期（以 ISO 格式表示）。例如：2024-04-30T00:55:42.765Z。
context.hits

(对象数组) 与查询匹配的最新文档。使用 Mustache 模板数组语法，您可以遍历这些匹配项以将 Elasticsearch 文档中的值获取到您的操作中。例如，电子邮件连接器操作中的消息可能包含

Elasticsearch query rule '{{rule.name}}' is active:

{{#context.hits}}
Document with {{_id}} and hostname {{_source.host.name}} has
{{_source.system.memory.actual.free}} bytes of memory free
{{/context.hits}}

由 context.hits 返回的文档包括 _source 字段。如果使用 Elasticsearch 查询搜索 API 的 fields 参数，文档还会返回 fields 字段，该字段可用于访问由 runtime_mappings 参数定义的任何运行时字段。例如

{{#context.hits}}
timestamp: {{_source.@timestamp}}
day of the week: {{fields.day_of_week}} 
{{/context.hits}}

此处的 fields 参数用于访问 day_of_week 运行时字段。

由于 fields 响应始终为每个字段返回一个值数组，因此 Mustache 模板数组语法用于在您的操作中遍历这些值。例如

{{#context.hits}}
Labels:
{{#fields.labels}}
- {{.}}
{{/fields.labels}}
{{/context.hits}}
context.link
(字符串) 生成警报的规则的 URL。例如：/app/management/insightsAndAlerting/triggersActions/rule/47754354-d894-49d3-87ec-05745a74e2b7。
context.message
(字符串) 规则的预制消息。例如
过去 1 小时内的文档计数为 100。当大于 50 时发出警报。
context.sourceFields
(对象) 如果规则配置为将源字段复制到警报中，则对于每个源字段，都有一个字符串数组，其中包含其值。例如：{'host.id': ['1'], 'host.name': ['host-1']}。
context.title
(字符串) 规则的预制标题。示例：rule 'my-query-rule' matched query。
context.value
(数字) 满足规则阈值条件的值。
rule.params
(对象) 规则参数，例如 searchType、timeWindowSize 和 timeWindowUnit。有关此规则的最终参数列表，请参阅 API 文档。

处理同一文档的多个匹配项edit

默认情况下，排除先前运行的匹配项已启用，并且规则会检查跨多个运行的文档匹配项的重复情况。如果您将规则配置为具有小于时间窗口的调度间隔，并且文档在多个运行中匹配查询，则只会提醒一次。

该规则使用匹配项的时间戳来避免对同一匹配项多次提醒。当规则运行时，使用最新匹配项的时间戳来评估规则条件。仅考虑从先前运行的最新时间戳到当前运行之间的匹配项。

假设您已配置一个规则，每分钟运行一次。该规则使用 1 小时的时窗，并检查查询是否有超过 99 个匹配项。Elasticsearch 查询规则类型执行以下操作

运行 1 (0:00)

规则在过去一小时内找到 113 个匹配项：113 > 99

规则处于活动状态，用户收到提醒。

运行 2 (0:01)

规则在过去一小时内找到 127 个匹配项。其中 105 个匹配项是之前已提醒过的重复项，因此您实际上有 22 个匹配项：22 !> 99

没有提醒。

运行 3 (0:02)

规则在过去一小时内找到 159 个匹配项。其中 88 个匹配项是之前已提醒过的重复项，因此您实际上有 71 个匹配项：71 !> 99

没有提醒。

运行 4 (0:03)

规则在过去一小时内找到 190 个匹配项。其中 71 个匹配项是之前已提醒过的重复项，因此您实际上有 119 个匹配项：119 > 99

规则处于活动状态，用户收到提醒。
« 创建索引阈值规则 创建跟踪包含规则 »