How Do I Create A New Elastalert Rule?

Provision your ElastAlert server

When you login your stacks are displayed on the dashboard. To enable alerts for a stack, choose the 'View Stack Settings' button.

Next, choose 'Alerting and Notifications' and then click 'Provision alerting for this stack'

Create your ElastAlert rule

Once your ElastAlert server has been provisioned and you have clicked 'ElastAlert is ready' you will see two sample yaml files that have default examples for alert rules.

You can click 'Edit' to see the configuration of the yaml files to give you an idea of how to properly configure your yaml files.

If you want to create a new alert rule click 'New Rule' where you will then enter your rule name for your yaml file, then click the 'Create' button.

This will configure and the rule will be added. Click the 'Go to rule' button which will then bring you to the yaml file for configuration. Here is a working example of an ElastAlert rule for a field change for a different 'country_name' compare against a 'user'.

# Alert when some field changes between documents
# This rule would alert on documents similar to the following:
# {'username': 'bob', 'country_name': 'USA', '@timestamp': '2014-10-15T00:00:00'}
# {'username': 'bob', 'country_name': 'Russia', '@timestamp': '2014-10-15T05:00:00'}
# Because the user (query_key) bob logged in from different countries (compare_key) in the same day (timeframe)

# (Required)
# Rule name, must be unique
name: New country login

# (Required)
# Type of alert.
# the change rule will alert when a certain field changes in two documents within a timeframe
type: change

# (Required)
# Index to search, wildcard supported
index: logstash-*

# (Required, change specific)
# The field to look for changes in
compare_key: country_name

# (Required, change specific)
# Ignore documents without the compare_key (country_name) field
ignore_null: true

# (Required, change specific)
# The change must occur in two documents with the same query_key
query_key: username

# (Required, change specific)
# The value of compare_key must change in two events that are less than timeframe apart to trigger an alert
timeframe:
  days: 1

# (Required)
# A list of Elasticsearch filters used for find events
# These filters are joined with AND and nested in a filtered query
# For more info: http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html
filter:
- query:
    query_string:
      query: "document_type: login"

# (Required)
# The alert is use when a match is found
alert:
- "email"

# (required, email specific)
# a list of email addresses to send alerts to
email:
- "[email protected]"

Once you are finished with your configuration you can then click 'Test only' to see if your yaml file has been configured correctly.

If there is incorrect spelling in your yaml it will be shown in the logs like below.

Tip!: If there is a spacing issue in your yaml the error will be shown like this:

Once you are happy with the rule click 'Update' to save your rule.

Once you have updated your rule, you will see that the job has been executed and the rule has been updated.

The rule will be then added to your list of rules once you go back to the 'Alerts' tab.

Several rule types that are common when creating your alert rule are:

• Frequency type: Match where there are X events in Y time
• Spike type: Match when the rate of events increases or decreases
• Flatline type: Match when there are less than X events in Y time
• Blacklist type: Match when a certain field matches a blacklist
• Whitelist type: Match when a certain field matches a whitelist
• Any type: Match on any event matching a given filter
• Change type: Match when a field has two different values within some time

ElastAlert supports alert types of Command, Email, JIRA, OpsGenie, SNS, HipChat, Slack, Telegram, GoogleChat, Debug, Stomp, theHive which you can use for your alerts.

If you enjoyed this post on how to create a new Elastalert rule then why not check out our guide on how to view Elasticsearch mappings or our guide to how many servers does it take to run Elasticsearch?