第一次运行ElastAlert
Requirements依赖项
- Elasticsearch
- ISO8601 或者 Unix timestamped data
- Python 2.7
- pip, 请查看 requirements.txt
下载以及配置
你可以使用 pip 安装 ElastAlert 的最新版本:
$ pip install elastalert
或者您可以克隆(clone) ElastAlert 存储库以获取最近的更改：
$ git clone https://github.com/Yelp/elastalert.git
安装(依赖)模块:
$ pip install -r requirements.txt
根据 Elasticsearch 版本的不同,你可以收同安装对应版本的elasticsearch-py库.
Elasticsearch 5.0+:
$ pip install "elasticsearch>=5.0.0"
Elasticsearch 2.X:
$ pip install "elasticsearch<3.0.0"
接下来,打开 config.yaml.example.在其中,你可以找到一些配置项.可以在不更改任何这些的情况下运行 ElastAlert .
rules_folder是 ElastAlert 加载规则配置文件的地方. 它将尝试加载文件夹中的每一个.yaml文件. 若没有任何有效的规则,ElastAlert将不会启动. ElastAlert 将会加载新的规则,停止运行缺少的规则,并且重新启动修改了的规则.在这篇教程当中,我们将使用example_rules这个文件夹(作为存放规则配置文件的路径).
run_every是 ElastAlert 会多久查询一次 Elasticsearch .
buffer_time是查询的区间, 从每个查询运行的时间向后延伸. 如果use_count_query或use_terms_query的值为true,这项配置将会被忽略.
es_host 是 ElastAlert 存储关于其状态,查询数,警报以及报错的 Elasticsearch 集群的地址.每一条规则可以使用不同的 Elasticsearch 主机进行查询.
es_port是对应es_host的端口.
use_ssl: 可选项; 控制当连接到es_host时是否使用TLS; 有True和Flase可供选择.
verify_certs: 可选项; 控制是否验证 TLS 证书,有True和False可供选择,默认是True.
es_username: 可选项; 用于连接到es_host最基本的用户名认证。
es_password: 可选项; 用于连接到es_host最基本的密码认证。
es_url_prefix: 可选项; Elasticsearch端点的网址前缀。
es_send_get_body_as: 可选项; 查询 Elasticsearch 的 http 方法 -GET,POST或者source. 默认的是GET
writeback_index是 ElastAlert 存储数据用到的index名称.后面我们将会创建这个index.
alert_time_limit是提供给失败警报的重试窗口.
保存到名为config.yaml的文件当中.
配置 Elasticsearch
ElastAlert 会保存一些与查询和报警相关的信息以及元数据到 Elasticsearch 当中.这对审查/调试有很大的作用,并且它允许 ElastAlert 重新启动并恢复到之前停止的位置.这个并非是运行 ElastAlert 的比选项, 但是强烈推荐使用.
首先, 我们需要通过运行elastalert-create-index创建一个 ElastAlert 的 index,如以下操作所示:
$ elastalert-create-index
New index name (Default elastalert_status)
Name of existing index to copy (Default None)
New index elastalert_status created
Done!
关于这里面会有什么数据,请参阅ElastAlert Metadata Index.
创建规则
每个规则中定义了要执行的查询,触发匹配的参数,以及每个匹配要触发的警报列表.下面我们将用exapmle_rules/example_frequency.yaml作为示例:
# From example_rules/example_frequency.yaml
es_host:elasticsearch.example.com
es_port:14900
name:Example
ruletype:frequency
index:logstash-*
num_events:50
timeframe:
hours:4
filter:
- term:
some_field:"some_value"
alert:
- "email"
email:
- "[email protected]"
es_host以及es_port必须指向我们想要查询的 Elasticsearch 集群.
name 是这条规则的唯一标识. 如果该字段同时使用在两条规则上,ElastAlert 将不会启动.
type: 各规则有不同的类型,可能会使用不同的参数.frequency类型代表 "当timeframe范围内超过num_events时,进行报警." 对于其他类型的信息,请参阅Rule types.
index: 需要查询的(es)index的名称. 如果你是使用 logstash 传输数据,默认的 indexes 为"index-*".
num_events: 这个参数是触发警报时的阀值,仅特定于frequency类型,
timeframe是发生num_events的时间段.
filter 是 Elasticsearch 用于过滤查询结果的过滤器列表.这个实例当中我们演示了一个简单的包含some_value的some_field的一个 term 查询.更多细节请查看如何为规则写过滤器.当没有需要过滤的内容时,应该特别的用一个空列:filter:[]进行查询.
alert是针对每个匹配结果的警报.想要了解更多关于警报的类型,查看Alerts.其中的 email 警报需要一个 SMTP 服务器发送邮件.默认的,它将会使用本地作为服务器.这个值可以用smpt_host选项进行配置.
email是一个用来发送警报的地址列表.
还有其他更多的配置选项,请见常见配置.
所有的文档必须要有一个timestamp值. ElastAlert默认的使用@timestamp,但是也可以通过timestamp_field这个选项进行修改.默认的来说,ElastAlert 使用 ISO8601 时间戳,通过配置timestamp_type也可以支持 unix 时间戳.
综上所述,这条规则意味着"当过去4个小时发生了超过五十个some_field==some_value时,发送一封邮件到[email protected]"
测试你的规则
运行elastalert-test-rule工具将会测试您的配置文件,它会在调试模式下运行过去24个小时的成功加载项(加载过去24小时的成功匹配项):
$ elastalert-test-rule example_rules/example_frequency.yaml
如果你希望测试特定的配置文件,也可以使用 config 选项.
$ elastalert-test-rule –config > < > path-to-config-file > > > example_rules/example_frequency.yaml.
配置首选项将会按如下方式进行加载:
- 配置由yaml文件指定.
- 配置文件中指定的配置(如果指定的话).
- 为工具运行的默认的配置.
更多细节请查看测试部分
运行 ElastAlert
有两种方式可以调用 ElastAlert. 可以通过Supervisor(http://supervisord.org/)作为守护进程运行,或者直接通过python运行.在这篇教程中,为了更好debugging的目的,我们将采用python直接调用的方式.
$ python -m elastalert.elastalert --verbose --rule example_frequency.yaml # or use the entry point: elastalert --verbose --rule ...
No handlers could be found for logger "Elasticsearch"
INFO:root:Queried rule Example rule from 1-15 14:22 PST to 1-15 15:07 PST: 5 hits
INFO:Elasticsearch:POST http://elasticsearch.example.com:14900/elastalert_status/elastalert_status?op_type=create [status:201 request:0.025s]
INFO:root:Ran Example rule from 1-15 14:22 PST to 1-15 15:07 PST: 5 query hits (0 already seen), 0 matches, 0 alerts sent
INFO:root:Sleeping for 297 seconds
(以上命令当中,)ElastAlert 使用了python的日志系统,--verbose将显示它的INFO级消息.--rule example_frequency.yaml专门指定运行的规则,如果没有这一条,ElastAlert将会加载example_rules文件夹中的所有规则.
让我们终端这个请求看看将会发生什么.
Queried rule Example rule from 1-15 14:22 PST to 1-15 15:07 PST:5 hits
ElastAlert定期查询了最近的buffer_time(默认为45分钟)以获取与过滤器匹配的数据.在这里我们可以看到它匹配了5个hits.
POST http://elasticsearch.example.com:14900/elastalert_status/elastalert_status?op_type=create[status:201 request:0.025s]
这一行表明 ElastAlert 上传了一个关于刚刚查询相关信息的文档到 elastalert_status 索引中.
Ran Example rule from1-15 14:22 PST to 1-15 15:07 PST:5 query hits(0 already seen),0 matches,0 alerts sent
这一行的意思是 ElastAlert 完成了规则处理.在一个大时间范围内,有时候会运行多个查询,但是他们的数据将会被一起处理.query hits是从 Elasticsearch 中下载下来的文档数量.already seen指的是我们在之前查询过程中重叠的文档,这些数量将会被忽略.matches是根据规则类型输出的匹配数,alertsent是已经发送警报的数量.这个会因为realert,aggregation或者错误警报的影响而和match的值不一致.
Sleeping for 297 seconds
run_every默认的值是5分钟,意味着ElastAlert将休眠，直到从上一个循环过去5分钟，再次运行每个规则的查询，时间范围向前移动5分钟。
如,接下来的297秒,46个以上匹配的文档被添加到了 Elasticsearch:
INFO:root:Querie rule Example
rule from 1-15 14:27 PST to 1-15 15:12 PST:51 hits...
INFO:root:Sent email to ['[email protected]']...
INFO:root:Ran Example rule from 1 - 15 14:27 PST to 1-15 15:12 PST:51 query hits,1 matches,1 alerts sent
email 的邮件体包含的内容如下所示:
Example rule At least 50 events occurred between 1-15 11:12 PST and 1-15 15:12 PST
@timestamp:2015-01-15 T15:12:00-08:00
如果发生了一个错误,类似不能到达 SMTP 服务器,你可能会看到如下的信息:
ERROR:root:Error while running alerte mail:Error connecting to SMTP host:[Err no 61] Connection refused
请注意,如果你停止了 ElasticAlert 一段时间后再运行,它将会查找elastalert_status并且开始查询最后一次查询的结束时间.这是为了防止重启 ElastAlert 时重复或者跳过报警.
如果使用--debug表示替代--verbose,email的邮件体将会被替换成日志,并且不再发送.此外,查询也不会存储到elastalert_status当中.