创建 Elasticsearch 查询规则
编辑创建 Elasticsearch 查询规则
编辑Elasticsearch 查询规则类型运行用户配置的查询,将匹配数量与配置的阈值进行比较,并在满足阈值条件时计划运行操作。
在 Stack Management(堆栈管理) > Rules(规则) 中,点击 Create rule(创建规则)。选择 Elasticsearch query(Elasticsearch 查询) 规则类型,然后填写名称和可选标签。可以使用 Elasticsearch 查询特定领域语言 (DSL)、Elasticsearch 查询语言 (ES|QL)、Kibana 查询语言 (KQL) 或 Lucene 来定义 Elasticsearch 查询规则。
定义条件
编辑创建 Elasticsearch 查询规则时,您选择的查询类型会影响您必须提供的信息。例如
-
定义您的查询
如果您使用 查询 DSL,您必须选择一个索引和时间字段,然后提供您的查询。仅使用
query
、fields
、_source
和runtime_mappings
字段,不考虑其他 DSL 字段。例如{ "query":{ "match_all" : {} } }
如果您使用 KQL 或 Lucene,您必须指定一个数据视图,然后定义一个基于文本的查询。例如,
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
-
如果您使用查询 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
)。通过聚合计算的值将与此阈值进行比较。
- 设置时间窗口,该窗口定义要搜索文档的追溯时间。
- 如果您使用查询 DSL、KQL 或 Lucene,请设置在满足阈值条件时要发送到配置的操作的文档数量。
- 如果您使用查询 DSL、KQL 或 Lucene,请选择是否通过排除上一次运行的匹配项来避免警报重复。当您使用分组字段时,此选项不可用。
- 设置检查间隔,它定义了评估规则条件的频率。通常,此值应设置为小于时间窗口的值,以避免检测中出现间隙。
- 在高级选项中,您可以更改在发生警报之前必须满足规则条件的连续运行次数。默认值为
1
。 - 选择范围值,该值会影响访问该规则所需的 Kibana 功能权限。例如,当设置为
Stack Rules
时,您必须具有相应的 Management(管理)> Stack Rules(堆栈规则) 功能权限才能查看或编辑该规则。
测试您的查询
编辑使用 Test query(测试查询) 功能来验证您的查询是否有效。
如果您使用查询 DSL、KQL 或 Lucene,则查询会针对使用配置的时间窗口的选定索引运行。将显示与查询匹配的文档数量。例如
如果您使用 ES|QL 查询,则会显示一个表格。例如
如果查询无效,则会发生错误。
添加操作
编辑您可以选择在满足规则条件时以及不再满足规则条件时发送通知。特别是,此规则类型支持
- 警报摘要
- 在匹配查询时运行的操作
- 在不再满足规则条件时运行的恢复操作
对于每个操作,您必须选择一个连接器,该连接器为 Kibana 服务或第三方集成提供连接信息。有关所有受支持的连接器的更多信息,请转到 连接器。
选择连接器后,您必须设置操作频率。您可以选择在每个检查间隔或自定义间隔上创建警报摘要。例如,发送电子邮件通知,以自定义间隔汇总新的、正在进行的和已恢复的警报
或者,您可以设置操作频率,以便为每个警报运行操作。选择操作运行的频率(在每个检查间隔、仅当警报状态更改时或以自定义操作间隔)。您还必须选择一个操作组,该组指示操作是在匹配查询时还是在恢复警报时运行。每个连接器都支持每个操作组的一组特定操作。例如
您可以通过指定操作仅在匹配 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 中的变量列表,请单击“添加规则变量”按钮。例如
以下变量特定于 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
响应始终为每个字段返回一个值数组,因此使用 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) 规则参数,例如
searchType
、timeWindowSize
和timeWindowUnit
。有关此规则的参数的明确列表,请参阅 API 文档。
处理同一文档的多个匹配项
编辑默认情况下,Exclude matches from previous run(排除上一次运行的匹配项) 已开启,并且该规则会检查多次运行中是否存在重复的文档匹配项。如果您配置的规则的计划间隔小于时间窗口,并且文档在多次运行中都匹配某个查询,则只会收到一次警报。
该规则使用匹配项的时间戳来避免多次对同一匹配项发出警报。当规则运行时,将使用最新匹配项的时间戳来评估规则条件。仅考虑上一次运行的最新时间戳和当前运行之间的匹配项。
假设您配置的规则每分钟运行一次。该规则使用 1 小时的时间窗口,并检查查询的匹配项是否超过 99 个。Elasticsearch 查询规则类型执行以下操作
|
规则在过去一小时内找到 113 个匹配项: |
规则处于活动状态,并向用户发出警报。 |
|
规则在过去一小时内找到 127 个匹配项。其中 105 个匹配项是之前已发出警报的重复项,因此您实际有 22 个匹配项: |
无警报。 |
|
规则在过去一小时内找到 159 个匹配项。其中 88 个匹配项是之前已发出警报的重复项,因此您实际有 71 个匹配项: |
无警报。 |
|
规则在过去一小时内找到 190 个匹配项。其中 71 个是之前已发出警报的重复项,因此您实际有 119 个匹配项: |
规则处于活动状态,并向用户发出警报。 |