在源码目录下的 example_rules 文件夹中有几个不同类型的 规则 配置可以参考。
注意：
所有的时间选项的格式都是
<单位>:X, 其中单位可以是 weeks, days, hours, minutes 或者 seconds. 例如minutes: 15或者hours: 1.
¶规则配置列表
¶所有规则通用
¶必须
¶es_host(string, no default)
规则 要轮询(监控)的 ES 集群 hostname
¶es_port (number, no default)
ES 集群端口
¶index (string, no default)
要查询的索引. 可以使用通配符, 例如: index: my-index-*. 还可以使用包含 %Y表示年、%m表示月、%d表示天的格式化字符串. 如果要使用这种格式化字符串, 需要将 use_strftime_index 设置为 true
¶type (string, no default)
要使用的规则类型：RuleType（包含内置和自定义并导入的）. 对于导入模块的类型应该被声明为 module.file.RuleName.
¶alert (string or list, no defult)
要使用的告警器：Alerter.同 规则类型 包含内置和自定义导入的. 导入的告警器应该被声明为 module.file.AlertName.
¶filter (ES filter DSL, no default)
一个 ES 查询 DSL 的 filters 列表. ElastAlert 将会使用 {'filter': {'bool': {'must': [config.filter]}}} 的格式（and 操作）以及一个额外的 timestamp range filter 来查询 ES. 这些 filters 的查询出来的所有结果都会被传递到 RuleType 进行分析. 对于更多关于如何书写 filters, 后续有介绍, 或者参考官网.
¶非必须
¶buffer_time (time, default from config.yaml)
在当前 规则 中覆盖全局 config.yaml 的值. 如果 use_count_qeury或者use_terms_query 为true, 该值会被忽略.
¶realert (time, default: 1 min)
这个选项允许你在一段时间内忽略重复告警. 如果规则设置了query_key字段, 这个选项将会基于每一个 key 起作用.
- 对于给定
规则的所有匹配、或者说在query_key上拥有同一个值的匹配将会在给定时间段被忽略. - 所有
query_key字段没有值的匹配都会被分到一个值设为_missing的组.
忽略时间是从一个告警发出的时间点开始算的, 而不是触发事件的时间.
默认值是 1 分钟, 这意味着 ElastAlert 如果运行了很长一段时间且触发了很多规则，只有第一个告警会被发出. 如果想每一条都发出, 需要设置 realert 为 0.
¶exponential_realert (optional, time, no default)
使得 alert 成指数级增长直到 exponential_realert : 如果触发匹配 的时间距离上一次触发小于当前 alert 的两倍, 那么 alert 会翻倍.
¶示例
举个例子
realert设置为minutes: 10,exponential_realert设置为hours: 1- 一个
告警在 1:00 的时候触发, 另一个在 1:15, 则下一个告警至少要是 1:35 之后才能触发. - 如果在 1:35 到 2:15 之间触发了一个
告警,realert将增长到 1 个小时（最大值）. - 之后如果超过 2 个小时也没有触发
告警,realert就会恢复.
注意那些被忽略的
告警不会对realert产生影响（例如在 1:05 的时候）
¶name (string, defaults to the filename)
¶use_strftime_index (boolean, default False)
如果设置为 true, ElastAlert 将会在每一次对于 ES 的查询中使用 datetime.strftime 来对索引进行格式化. 参考 strftime 获取更多信息. 如果一个查询贯穿了好几天, 格式化之后的索引将会被用逗号拼接(其实就是使用 python 提供的字符串格式化 api 用一个格式匹配我们的想要的日期). 这对于缩小查询索引的范围是很有用的, 相对于通配符索引, 应该会有显著的提速.
¶owner (string, default empty string)
这个值可以被用来标识告警的持有者. 可选的, 这个字段可以被包含在任何告警类型中
¶priority (int, default 2)
该值被用来标识告警的相关优先级/重要程度. 可选的, 这个字段可以被包含在任意 告警 类型中（例如使用在 email 的主题或者正文文本中）.
category (string, default empty string)
该值被用来标识告警的分组. 可选的, 这个字段可以被包含在任意 告警 类型中（例如使用在 email 的主题或者正文文本中）.
¶query_delay (time, default 0 min)
这个选项将会使得 ElastAlert 减掉一个时间量, 让规则延迟运行. 这对于那些 ES 不是实时索引的数据是有用的.
¶use_ssl (boolean, default False)
是否使用 TLS 连接 ES. 环境变量 ES_USE_SSL 会覆盖这个字段
¶verify_certs (boolean, default True)
是否进行 TLS 证书验证 ES 连接
¶client_cert(string, no default)
客户端 PEM 证书
¶client_key(string, no default)
客户端私钥文件
¶es_username (string, no default)
ES 登录用户名. 环境变量 ES_USERNAME 会覆盖这个字段
¶es_password (string, no default)
ES 登录用户密码. 环境变量 ES_PASSWORD 会覆盖这个字段
¶es_url_prefix (string, no default)
ES 端点的 URL 前缀
¶es_send_get_body_as (string, default “GET”)
查询 ES 时使用的 HTTP 方法
¶aggregation (time, no default)
这个选项允许你将多个匹配聚合到一个告警中. 每当一个匹配发生, ElastAlert就会等待一个 aggregation 的周期, 然后在周期时间到达后, 发送所有在该周期内出现的的 匹配 到告警器.
¶示例
aggregation:
hours: 2
12点整有一个告警, 13点整又有一个, 第三个是在14点半, 一个告警将会在14点发出, 因为12点整出现了第一个 匹配, 需要等待2个小时, 将这2个小时之内的所有匹配在14点整聚合成一个告警发出. 因为14点整之后的第一个匹配是在14点半, 所以又要等2个小时, 在16点半的时候将这两个小时内的所有匹配整合成一个告警发出.
¶固定告警时间
如果你希望在一个递推的时间间隔中聚合所有告警再发送, 你可以使用schedule 字段. 举个例子, 如果你希望在每个周一和周五接收告警:
aggregation:
schedule: '2 4 * * mon,fri'
这里使用了 Cron 语法. 注意不可以同时设置 schedule 和标准时间字段(hours、minutes、days), 只能选择其一.
¶对匹配进行分组
默认情况下, 所有在一个聚合窗口中的事件(匹配)会分在一组内. 不过, 如果你的规则定义了 aggregation_key 字段, 然后所有该字段拥有同一个值的事件都会被分为一组. 每当在该 key 上遇到一个新值的时候就会创建一个隔离的聚合窗口.
举个例子, 如果你希望接收以触发匹配事件的用户为分组的告警, 你可以这样设置:
aggregation_key: 'my_data.username'
假设有一个 10 分钟的聚合窗口, 如果接收到以下数据:
{'my_data': {'username': 'alice', 'event_type': 'login'}, '@timestamp': '2016-09-20T00:00:00'}
{'my_data': {'username': 'bob', 'event_type': 'something'}, '@timestamp': '2016-09-20T00:05:00'}
{'my_data': {'username': 'alice', 'event_type': 'something else'}, '@timestamp': '2016-09-20T00:06:00'}
这将会生成 2 个告警: 一个包含 alice 的两个 匹配 事件, 在 2016-09-20T00:10:00 发送; 另一个包含 bob 的一个事件, 将会在 2016-09-20T00:16:00 发送.
¶概要信息
对于聚合告警来说, 有时候会在那些展示媒介（email, jira ticket等）上出现较大数量的文档(例如某个分组下出现了很多500错误). 如果你设置了 summary_table_fields 字段, ElastAlert 会从所有查询到的文档中针对该字段提供一个概要信息.
举个例子, 如果你希望对那些 匹配 了 规则 的文档的 username 和 event_type 做一个概述以便你可以很方便地得到最有相关/有价值的字段的信息, 你可以如下设置:
summary_table_fields:
- my_data.username
- my_data.event_type
基于上面的 alice 和 bob 的数据, ElastAlert 会在告警媒介中提供如下概要表格:
+------------------+--------------------+
| my_data.username | my_data.event_type |
+------------------+--------------------+
| alice | login |
| bob | something |
| alice | something else |
+------------------+--------------------+
¶注意
默认的聚合时间是基于当前的系统时间, 而不是匹配的时间（例如第一条匹配出现后, 取当前系统时间戳作为时间窗口的起始值, 而不是取查询中的时间戳）. This means that running elastalert over past events will result in different alerts than if elastalert had been running while those events occured. This behavior can be changed by setting aggregate_by_match_time.
¶aggregate_by_match_time
Setting this to true will cause aggregations to be created relative to the timestamp of the first event, rather than the current time. This is useful for querying over historic data or if using a very large buffer_time and you want multiple aggregations to occur from a single query.
¶max_query_size (int, default global max_query_size)
和全局 max_query_size 意义一样, 会覆盖全局的.
¶include (list of string, default [“*”] / all fields)
查询结果应该返回的字段. 设置之后, 只有设置的字段以及 ‘@timestamp’, query_key, compare_key, and top_count_keys 会返回.
¶description (string, default empty string)
对于 规则 的描述. 可以在自定义告警器中引用到这个值, 提供一个 规则 触发原因的上下文.
¶generate_kibana_link (boolean, default False)
这个选项只对 Kibana3 有效. 如果设置为 true, ElastAlert 将会在 告警 中生成一个临时的 Kibana 面板以及一个链接. 这个面板由一个基于时间变化的事件图标以及一个包含了 include 中字段的表格. 如果当前 规则 设置了 query_key, 这个面板也会包含一个关于该告警的该 query_key 的 filter. 该面板 schema 将会被上传到 kibana-int 的索引作为一个临时面板.
¶kibana_url (string, default from http://<es_host>:<es_port>/_plugin/kibana/)
访问 Kibana 的 url. 这在 generate_kibana_link 或者 use_kibana_dashboard 为 true 的时候使用. 如果没有定义, 将会使用 es_host 以及 es_port 拼接成一个 URL.
¶use_kibana_dashboard (string, no default)
Kibana3 面板的名称. 不像 generate_kibana_link 那样从一个模板生成一个面板, ElastAlert 可以复用一个已存在的面板. 它会在面板上根据匹配 的时间将该时间范围设置到面板, 将其上传为一个临时面板, 并添加一个 filter 到 告警 的 query_key 字段上（如果有的话）, 然后将 url 放到 告警里面.
¶use_kibana4_dashboard (string, no default)
一个 Kibana4 面板的链接. 例如, “https://kibana.example.com/#/dashboard/My-Dashboard”. This will set the time setting on the dashboard from the match time minus the timeframe, to 10 minutes after the match time. Note that this does not support filtering by query_key like Kibana 3. This value can use $VAR and ${VAR} references to expand environment variables.
¶kibana4_start_timedelta (time, default: 10 min)
¶kibana4_end_timedelta (time, default: 10 min)
¶use_local_time (boolean, default True)
¶match_enhancements (list of strs, no default)
¶top_count_keys (list of strings)
一个包含多个字段的集合. ElastAlert 会在这些字段上使用 term query 查询 X 个最常见的值, X 默认值是 5, 或者 top_count_number（如果该选项被存在）. For example, if num_events is 100, and top_count_keys is - "username", the alert will say how many of the 100 events have each username, for the top 5 usernames. When this is computed, the time range used is from timeframe before the most recent event to 10 minutes past the most recent event. Because ElastAlert uses an aggregation query to compute this, it will attempt to use the field name plus “.raw” to count unanalyzed terms. To turn this off, set raw_count_keys to false.
¶top_count_number (int, default 5)
如果 top_count_keys 设置, 该选项为 term query 中每个 terms 的数量.
¶raw_count_keys (boolean, default True)
如果设置为 true, 所有在 top_count_keys 中定义的字段都会拼接一个 .raw 后缀.（一个 keyword 类型的子字段, 高版本的 ES 后缀为 .keyword）
¶scan_entire_timeframe (bool, default False)
¶import (string no default) IGNORED IF use_count_query or use_terms_query is true
将所有设置导入到当前 yaml 文件中. 这允许通用配置选项被共享. 注意导入的文件如果不包含完整的规则配置就应该以.yml或者.yaml为后缀, 这样 ElastAlert 才不会加载它们并报错. 在被导入的文件中的 Filters 将会在当前规则中被合并成一个 Any Filters . 在一个规则配置文件中只能有一个 import, 不过被 import 的文件又可以 import 其它的文件. 导入的文件名称可以是绝对路径和相对于规则路径.
¶timestamp_type (string, default iso)
¶timestamp_format (string, default “%Y-%m-%dT%H:%M:%SZ”)
¶timestamp_format_expr (string, no default )
¶_source_enabled (boolean, default True)
¶alert_text_args (array of strs)
¶alert_text_kw (object)
¶alert_missing_value (string, default “”)
¶is_enabled (boolean, default True)
¶search_extra_index (boolean, default False)
If this is true, ElastAlert will add an extra index on the early side onto each search. For example, if it’s querying completely within 2018-06-28, it will actually use 2018-06-27,2018-06-28. This can be useful if your timestamp_field is not what’s being used to generate the index names. If that’s the case, sometimes a query would not have been using the right index.
| RULE TYPE | Any | Blacklist | Whitelist | Change | Frequency | Spike | Flatline | New_term | Cardinality |
|---|---|---|---|---|---|---|---|---|---|
compare_key (list of strs, no default) |
Req | Req | Req | ||||||
blacklist (list of strs, no default) |
Req | ||||||||
whitelist (list of strs, no default) |
Req | ||||||||
ignore_null (boolean, no default) |
Req | Req | |||||||
query_key (string, no default) |
Opt | Req | Opt | Opt | Opt | Req | Opt | ||
aggregation_key (string, no default) |
Opt | ||||||||
summary_table_fields (list, no default) |
Opt | ||||||||
timeframe (time, no default) |
Opt | Req | Req | Req | Req | ||||
num_events (int, no default) |
Req | ||||||||
attach_related (boolean, no default) |
Opt | ||||||||
use_count_query (boolean, no default)doc_type (string, no default) |
Opt | Opt | Opt | ||||||
use_terms_query (boolean, no default)doc_type (string, no default)query_key (string, no default)terms_size (int, default 50) |
Opt | Opt | Opt | ||||||
spike_height (int, no default) |
Req | ||||||||
spike_type ([up|down|both], no default) |
Req | ||||||||
alert_on_new_data (boolean, default False) |
Opt | ||||||||
threshold_ref (int, no default) |
Opt | ||||||||
threshold_cur (int, no default) |
Opt | ||||||||
threshold (int, no default) |
Req | ||||||||
fields (string or list, no default) |
Req | ||||||||
terms_window_size (time, default 30 days) |
Opt | ||||||||
window_step_size (time, default 1 day) |
Opt | ||||||||
alert_on_missing_fields (boolean, default False) |
Opt | ||||||||
cardinality_field (string, no default) |
Req | ||||||||
max_cardinality (boolean, no default) |
Opt | ||||||||
min_cardinality (boolean, no default) |
Opt |
