创建 Elasticsearch 查询规则

编辑

创建 Elasticsearch 查询规则

编辑

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

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

定义条件

编辑

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

Define the condition to detect
  1. 定义您的查询

    如果您使用 查询 DSL,您必须选择一个索引和时间字段,然后提供您的查询。仅使用 queryfields_sourceruntime_mappings 字段,不考虑其他 DSL 字段。例如

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

    如果您使用 KQLLucene,您必须指定一个数据视图,然后定义一个基于文本的查询。例如,http.request.referrer: "https://example.com"

    如果您使用 ES|QL,您必须提供一个源命令,后跟一系列可选的处理命令,用管道符 (|) 分隔。 [8.16.0] 在 8.16.0 中添加。 例如

    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,请设置分组和阈值。

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

测试您的查询

编辑

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

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

Test Elasticsearch query returns number of matches when valid

如果您使用 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
(string) 条件的描述。例如:Query matched documents(查询匹配的文档)
context.date
(string) 规则满足条件的日期,采用 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
(string) 生成警报的规则的 URL。例如:/app/management/insightsAndAlerting/triggersActions/rule/47754354-d894-49d3-87ec-05745a74e2b7
context.message
(string) 规则的预构造消息。例如
文档计数在过去 1 小时内为 100。当大于 50 时发出警报。
context.sourceFields
(object) 如果规则配置为将源字段复制到警报中,则对于每个源字段,都有一个字符串数组,其中包含其值。例如:{'host.id': ['1'], 'host.name': ['host-1']}
context.title
(string) 规则的预构造标题。示例:rule 'my-query-rule' matched query(规则 'my-query-rule' 匹配查询)
context.value
(number) 满足规则阈值条件的值。
rule.params
(object) 规则参数,例如 searchTypetimeWindowSizetimeWindowUnit。有关此规则的参数的明确列表,请参阅 API 文档。

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

编辑

默认情况下,Exclude matches from previous run(排除上一次运行的匹配项) 已开启,并且该规则会检查多次运行中是否存在重复的文档匹配项。如果您配置的规则的计划间隔小于时间窗口,并且文档在多次运行中都匹配某个查询,则只会收到一次警报。

该规则使用匹配项的时间戳来避免多次对同一匹配项发出警报。当规则运行时,将使用最新匹配项的时间戳来评估规则条件。仅考虑上一次运行的最新时间戳和当前运行之间的匹配项。

假设您配置的规则每分钟运行一次。该规则使用 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

规则处于活动状态,并向用户发出警报。