Yelp/elastalert 规则过滤器编写指南

Yelp/elastalert 规则过滤器编写指南

elastalert Easy & Flexible Alerting With ElasticSearch 项目地址: https://gitcode.com/gh_mirrors/el/elastalert

前言

在 Yelp/elastalert 项目中，过滤器是规则配置中最核心的部分之一。它们决定了哪些 Elasticsearch 文档会被选中并触发警报。本文将深入讲解如何为 elastalert 规则编写有效的过滤器，帮助开发者构建精准的告警机制。

过滤器基础

elastalert 的过滤器直接使用 Elasticsearch 的查询 DSL（领域特定语言）。当你在规则配置文件中定义过滤器时，它们会被原样传递给 Elasticsearch 执行查询。所有匹配这些过滤器的结果都会被传递给规则进行进一步处理。

过滤器在配置文件中以如下结构呈现：

filter:
  and:
    filters:
      - [你的过滤器列表]

常用过滤器类型详解

1. query_string 查询

query_string 是最灵活且功能强大的过滤器类型，支持 Lucene 查询语法，可用于多字段的部分或完全匹配。

示例用法：

filter:
- query:
    query_string:
      query: "username: bob"
- query:
    query_string:
      query: "_type: login_logs"
- query:
    query_string:
      query: "field: value OR otherfield: othervalue"

特点：

• 支持布尔逻辑（AND/OR/NOT）
• 支持通配符和模糊匹配
• 可以同时查询多个字段
• 适用于全文搜索场景

2. term 精确匹配

term 过滤器用于精确匹配字段值，特别适合非文本字段或未分词的字符串字段。

示例：

filter:
- term:
    name_field: "bob"
- term:
    _type: "login_logs"

重要注意事项：

• 对于已分词的文本字段，term 查询可能表现不符合预期
• 默认情况下，许多字符串字段会被分词（按空格分割）
• "foo bar" 的 term 查询可能无法匹配看起来相同的字段值
• 对于分词字段的全文匹配，应使用 query_string

3. terms 多值匹配

terms 过滤器允许你指定一个字段的多个可能值，相当于多个 term 查询的 OR 组合。

基本用法：

filter:
- terms:
    field: ["value1", "value2"]  # 匹配 value1 或 value2

多字段匹配：

- terms:
    fieldX: ["value1", "value2"]
    fieldY: ["something", "something_else"]

4. wildcard 通配符查询

wildcard 过滤器支持使用通配符进行模式匹配。

示例：

filter:
- query:
    wildcard:
      field: "foo*bar"  # 匹配以foo开头，bar结尾的任何值

5. range 范围查询

range 过滤器用于匹配字段值在特定范围内的文档。

示例：

filter:
- range:
    status_code:
      from: 500
      to: 599  # 匹配500到599之间的状态码

布尔逻辑组合

根据 Elasticsearch 版本不同，布尔逻辑的实现方式有所差异。

Elasticsearch 2.X 版本

可以直接使用 not、and 和 or 组合过滤器：

filter:
- or:
    - term:
        field: "value"
    - wildcard:
        field: "foo*bar"
    - and:
        - not:
            term:
              field: "value"
        - not:
            term:
              _type: "something"

Elasticsearch 5.x 及以上版本

需要使用 query_string 来实现布尔逻辑：

filter:
 - query:
      query_string:
        query: "somefield: somevalue OR foo: bar"

从 Kibana 3 导入过滤器

elastalert 提供了两种方式从 Kibana 3 仪表板直接加载过滤器。

方法一：动态下载

filter:
  download_dashboard: "My Dashboard Name"

特点：

• 启动时会从 Elasticsearch 下载仪表板配置
• 依赖网络连接和仪表板名称不变
• 失败会导致规则加载失败

方法二：生成配置文件

使用 elastalert-rule-from-kibana 工具生成配置文件：

$ elastalert-rule-from-kibana
Elasticsearch host: elasticsearch.example.com
Elasticsearch port: 14900
Dashboard name: My Dashboard

优点：

• 生成静态配置文件，不依赖运行时连接
• 更可靠，适合生产环境

最佳实践建议

1. 性能考虑：复杂的查询可能影响性能，尽量使用最精确的过滤器
2. 字段分析：了解字段是否被分词，选择合适的查询类型
3. 测试验证：使用 Elasticsearch 的查询 API 先验证过滤器效果
4. 版本兼容：注意 Elasticsearch 版本差异对查询语法的影响
5. 组合使用：合理组合不同类型的过滤器实现精确匹配

通过掌握这些过滤器技术，你可以构建出高效、准确的 elastalert 告警规则，有效监控你的 Elasticsearch 数据。

elastalert Easy & Flexible Alerting With ElasticSearch 项目地址: https://gitcode.com/gh_mirrors/el/elastalert