00_elastalert概述

¶简介

ElastAlert 是一个用来监控 ES 中的异常、毛刺(spike) 或者其它规则的数据的简单的框架。如果想对一些近实时写入 ES 的数据进行某种规则的监控并做出告警的动作，可以用它来做。

¶特性

¶具备可靠性

ElastAlert 拥有以下特性使得它在重启和 ES 不可达的情况下更可靠

• ElastAlert 会将它的状态信息保存到 ES 中，当它启动的时候，将会恢复到停止之前的状态
• 如果 ES 不可响应，ElastAlert 将会等待 ES 恢复之后才会继续下一步
• 告警器 发生错误的时候会自动重试数次

¶高度模块化

ElastAlert 的三个主要组件都可以被当成一个模块进行导入或者进行定制开发

• 规则类型(Rule types)：规则类型 负责处理从 ES 返回的数据。它会根据规则配置被初始化，配置在规则文件中的 filter 查询从 ES 中查询数据返回，然后根据这份数据的匹配结果进行输出。
• 告警器(Alerts)：告警器 负责基于一个 匹配 进行一定的动作。一个 匹配 通常是一个包含了所有从 ES 中查询回来的 document 的字段，不过可能会包含一些被 规则类型 增加的任意数据。
• 增强器(Enhancements)：增强器 是一种拦截、修改、增强告警器的途径。在 匹配 字段发送到 告警器 之前，这些数据会先被发到 增强器。

¶易于配置

ElastAlert 拥有一个全局的配置文件，config.yaml，里面定义了它作为一个进程启动的时候的一些行为：

• buffer_time：每次轮询 ES 都是查询从当前时间往前推 buffer_time 时间段内的文档。基于这种方式，一定时间之前的日志仍然可以被 ElastAlert 查询到并处理。在单独的规则配置文件中可以重写这个选项。当规则配置文件中的 use_count_query 和 use_term_query 被设置为 true 的时候，对应的规则将会忽略这个选项。
• es_host：用于存储 ElastAlert 状态(metadata)的 ES 集群地址。环境变量 ES_HOST 会覆盖这个字段。
• es_port：用于存储 ElastAlert 状态(metadata)的 ES 集群端口。环境变量 ES_PORT 会覆盖这个字段。
• use_ssl：可选；是否使用 TLS 连接 es_host；值为 True 或者 False；环境变量 ES_USE_SSL 会覆盖这个字段。
• verify_certs: Optional; 是否验证 TLS 的证书; True or False. 默认为 True.
• client_cert: Optional; 客户端 PEM 验证文件路径.
• client_key: Optional; 客户端私钥.
• ca_certs: Optional; CA 证书路径
• es_username: Optional; 连接到 es_host 的用户名. 环境变量 ES_USERNAME 会覆盖这个字段.
• es_password: Optional; 连接到 es_host 的密码. 环境变量 ES_PASSWORD 会覆盖这个字段.
• es_url_prefix: Optional; ES 端点的 URL 拼接前缀. 环境变量 ES_URL_PREFIX 会覆盖这个字段.
• es_send_get_body_as: Optional; 查询 ES 的请求方法 - GET, POST or source. 默认是 GET
• es_conn_timeout: Optional; 设置连接和查询 es_host 的超时时间; 默认是 20.
• rules_loader: Optional; 设置加载规则文件的类. 默认是 FileRulesLoader .
• rules_folder: 当rules_loader 是默认值的时候生效。指的是包含所有规则配置文件的文件夹名。ElastAlert 会加载该文件夹及其所有子孙文件夹下以 .yaml 结束的文件。如果这个文件夹内的文件发生了变化，ElastAlert 会分别加载、重载、移除这些文件(自动监听且热加载？).
• scan_subdirectories: Optional; 当rules_loader 是默认值的时候生效。设置是否递归扫描 rules_folder - true or false. 默认是 true
• run_every: 定义 ElastAlert 轮询 ES 的间隔(ElastAlert记住它上次查询的时间，然后按照这个值定期查询) 。这个字段是一个嵌套对象字段, 这个对象的属性可以是各时间单位，例如 minutes: 5，这也是 ElastAlert 所有配置文件中定义时间的方式.
• writeback_index: es_host 中被用来存储 ES 元信息的索引名称.
• max_query_size: 每次查询 ES 的时候的限制查询文档的最大数量. 默认是 10,000, 如果你的需求接近了这个数值，考虑在 规则 定义中使用 use_count_query 选项. 如果查询文档数量达到这个限制，ElastAlert 将会使用使用 ES 的 scroll API 进行查询，将 max_query_size 作为每一次 scroll 的页数, 然后一直 scroll max_scrolling_count 次，如果 max_scrolling_count 没有设置，将会一直 scroll 完整个查询快照.
• max_scrolling_count: 允许 scroll 的最大页数. 默认是 0, 不限制 scroll 的页数. 例如如果这个值被设置为 5 且 max_query_size 设置为 10000 ，那么最多 50000 个文档会被查询出来.
• scroll_keepalive: scrolling 的上下文(快照)允许存在的最大时间 (格式为 Time Units) . 避免设置一个很大的值，因为这会滥用 ES 的资源, 但是同时要注意允许足够多的时间以获取查询结果并处理.
• max_aggregation: 最大的聚合告警数量. 如果一个规则设置了 aggregation , 所有在一个时间区间内(timeframe) 出现的告警将会被一起发生. 默认值是 10,000.
• old_query_limit: 当 ElastAlert 启动的时候，允许它从上次发出查询的日期继续查询的最大间隔. 当 ElastAlert 启动的时候，对于每一个 规则 ，它都会从 elastalert_metadata 中查询上次轮询的时间然后从该时间开始查询数据, 除非该时间比 old_query_limit 还要早, 此时它就会从当前时间开始查询. 默认是一个星期.
• disable_rules_on_error: 如果设置为 true, ElastAlert 将会禁用那些抛出未捕获异常(非 EAException)的 规则 . 它会上传一个异常追溯信息到 elastalert_metadata 并且如果 notify_email 如果设置了, 就会发送一个提醒邮件. 被禁用的规则将不再会运行直到 ElastAlert 重启或者规则配置文件被修改了. 默认是 True.
• show_disabled_rules: 如果是 true, ElastAlert 在完成执行之后会显示(打印)被禁用的规则列表. 默认是 True.
• notify_email: 一个或者一组被用来发送提醒邮件的邮件地址. 在当前，只有抛出未捕获异常的时候会发送提醒邮件. 发送地址, SMTP 服务器地址 以及邮件的 reply-to 头部可以通过 from_addr, smtp_host, and email_reply_to 选项进行分别设置. 默认情况下，不会发出任何邮件.
• from_addr: 提醒邮件中的 from 头部. 这个值也会被 邮件告警 中使用, 除非在 规则 配置中被重写. 默认值是 “ElastAlert”.
• smtp_host: 指定发送提醒邮件的 SMTP 服务地址. 这个值也会被 邮件告警 中使用，除非在 规则 配置中被重写. 默认值是 “localhost”.
• email_reply_to: 设置邮件的 Reply-To (回复地址)头部. 默认值就是收件地址(例如notify_email).
• aws_region: 这会使得 ElastAlert 在使用亚马逊 ES 服务的时候对 HTTP 请求进行签名. 它会使用实例角色(instance role keys)密钥对请求进行签名. 环境变量 AWS_DEFAULT_REGION 会覆盖这个字段.
• boto_profile: 已废弃! 用来对发向 Amazon Elasticsearch Service 请求的签名的 Boto profile, 如果你不使用 instance role keys.
• profile: 用来对 Amazon Elasticsearch Service 请求进行签名的 AWS profile , 如果你不使用 instance role keys. 环境变量 AWS_DEFAULT_PROFILE 会覆盖这个字段.
• replace_dots_in_field_names: 如果是 True, ElastAlert 会在将 documents 写入到 ES 之前将字段中的任何点替换成下划线. 默认值是 False. Elasticsearch 2.0 - 2.3 不支持在字段名称中存在点.
• string_multi_field_name: 作为 ES 中 string multi-fields 的 subfield. Elasticsearch 2 默认值 .raw 、Elasticsearch 5 默认值是 .keyword.
• add_metadata_alert: 设置告警是否包含在规则配置文件中包含的元信息 (category, description, owner and priority); 设置 True or False. 默认是 False.
• skip_invalid: 如果设置为 True, 跳过无效文件而不是退出.

默认情况下，ElastAlert 使用一个简单的基础日志配置来打印标准错误的日志信息。可以通过使用 --verbose 或者 --debug 命令行选项将日志级别改成 INFO. 如果你需要一个更复杂的日志配置，你可以在 config 文件提供一个完整的日志配置, 这会使得你可以配置日志输出到一个文件，或者 Logstash 或者调整日志格式。

¶主要原理

基于两个核心组件规则类型和告警器定期向 ES 发出请求，然后将 ES 的响应数据传递给 规则类型，由规则类型决定是否出现匹配。当出现匹配的时候，这些数据将会被投递给一个或者多个告警器，具体行为取决于匹配的结果。

以上提到的内容都被配置在一些规则文件中，每个文件中定义了一个查询、一个规则类型、和一组告警器。

¶支持的常见监控规则

以下是 ElastAlert 提供的一些基于常见的监控模型实现的规则类型：

• frequency：在指定时间 Y 内触发事件 X 次
• spike：当事件发生的速率增长或者下降的时候
• flatline：在指定时间 Y 内触发事件少于 X 次
• blacklist以及whitelist：当某个字段中的值匹配 blacklist 或者 whitelist
• any：当多个 filter 中的任一事件匹配的时候
• change：当一个字段在同一时间内拥有两个不同的值的时候

¶支持的告警类型

• Command
• Email
• JIRA
• OpsGenie
• SNS
• HipChat
• Slack
• Telegram
• GoogleChat
• Debug
• Stomp
• theHive

¶支持自定义

自定义额外的规则类型和告警器容易编写和集成。

¶除了监控外的用途

• 告警器可以链接到 Kibana 面板，显示触发告警的数据
• 基于任一字段做聚合统计
• 将告警和定期报告进行组合
• 使用一个唯一值字段对告警进行分离/隔离
• 对规则类型匹配的数据做拦截和增强

¶运行 ElastAlert 命令及参数

$ python elastalert/elastalert.py

在运行 ElastAlert 的时候有几个参数是可用的:

--config 声明要使用的配置文件. 默认是 config.yaml.

--debug 以 debug 模式. 这会使得 ElastAlert 日志变得冗长, 将所有的 告警器 修改为 DebugAlerter, 仅在控制台打印告警而不执行正常的告警行为, 并且不会将对 ES 的查询和告警元数据写入 ES. 和 –verbose 不能一起使用.

--verbose 也会使得 ElastAlert 日志变得冗长, 使得你可以看到关于查询 ES 的状态信息. 和 –debug 不能一起使用.

--start <timestamp> 将会强制 ElastAlert 从给定时间开始查询, 而不是默认的从当前时间开始查询. 时间戳格式应该是 ISO8601, 例如YYYY-MM-DDTHH:MM:SS (UTC) 或者携带时区 YYYY-MM-DDTHH:MM:SS-08:00 (PST). 请注意如果查询一个很大的时间区间，那么在该规则完成整个时间段查询之前将不会发出告警. 强制从当前时间开始查询, 使用 “NOW”.

--end <timestamp> 会导致 ElastAlert 在指定时间戳停止查询. 默认情况下, ElastAlert 将会无限定期查询 ES.

--rule <rule.yaml> 只会执行给定规则文件. 该值应该是一个完全文件路径或者一个文件名存在于 rules_folder 或者它的子孙文件夹.

--silence <unit>=<number> 会将给定规则中告警静默一段时间. 规则 必须通过 --rule 给出. <unit> 可以是 days, weeks, hours, minutes or seconds. <number> 是一个整型. 举个例子, --rule noisy_rule.yaml --silence hours=4 会禁止 noisy_rule 在 4 hours 内发出告警.

--es_debug 将会对所有对于 Elasticsearch 的查询进行日志记录.

--es_debug_trace <trace.log> 会将所有对于 ES 做参数的 curl 命令进行日志记录到指定文件. --es_debug_trace 会被传递到 elasticsearch.py , 它记录的是 localhost:9200 而不是实际的 es_host:es_port.

--end <timestamp> will force ElastAlert to stop querying after the given time, instead of the default, querying to the present time. This really only makes sense when running standalone. The timestamp is formatted as YYYY-MM-DDTHH:MM:SS (UTC) or with timezone YYYY-MM-DDTHH:MM:SS-XX:00 (UTC-XX).

--pin_rules 将会禁止 ElastAlert 在规则配置文件发生变化的时候对规则进行加载、重载、移除(热重载).