An alert is triggered when a defined event is detected. An event is a condition that matches a log message to a time period or aggregation. The event may be used to group similar fields, change field content, or create new field content for use with alerting and correlation (an Operations feature.)

Alerts may also be triggered from a value in an aggregation widget. For more information, please see Alerts and Notifications.

Defining an Event

Click on Event Definitions then selectCreate Event Definition in the upper right corner. You will be presented with a set of dialogues that allow you to set the event's title, description, and priority.

Search queries can be used to create event definitions. In the event definition modal you can select which search query you want to link the notification to.

Creating an Event Definition Directly From Search Results

Alternatively, you may also click on any value in your search results to create an event definition. This event definition will generate tailored alerts that include only the specific part of the query that you want to be alerted on. To do so:

  1. Got to your search results.

  2. Click on any value in an aggregation widget, log view, or message widget.

  3. Select Create event definition from the drop down menu.

  4. Pick one of the Strategy by options in the modal that appears. Click on Show strategy details to select/deselect any parameters you would like to add to the event definition. The parameters you select here will populate in your event definition under Filter & Aggregation.

    You may select any of these options:

    • Exactly this value: This option displays parameters related to your current search. You may add or remove any of these.

    • Any in widget: This option displays parameters related to the selected value.

    • Custom : You may include any part of the search query by selecting the Custom option.

    Remember to click on Show strategy details to see a full list of clickable options.

    Hint: In addition to the three options displayed above, you may also be presented with other options depending on the value you select. For example, if you select an aggregation widget metric value, you will be presented with additional: Any in row and Any in column options.
  5. Click Continue Configuration. You will be redirected to the Event Definitions page. Start by giving your event definition a title and filling in other details in Event Details. The selections you made in step 4 will be populated in Filter & Aggregation. You may also add custom fields and notifications on this page.

  6. After reviewing the summary of your new event definition, click Create event definition. A new event definition will be created, and you will receive alerts for the given condition.

Managing Defined Events

All defined events are available on the Alerts & Events page.

You can find more details about each entity such as the priority, status, and scheduling by selecting the Event Definitions tab. Click on the information icon found in the scheduling column to find information about status, last execution, next execution, next time range, and queued notifications.

The Event Definitions page is bulk friendly and allows you to delete, edit, and disable multiple entities simultaneously. Under More Actions you will find the ability to edit, duplicate, disable, and delete definitions.

Assigned notifications are displayed by selecting the Notifications tab. This page is also bulk friendly and allows you to edit multiple entities. You can also test whether or not your notifications are active by clicking on the Test Notifications button under More Actions. You will then see a success or error message under the entity title.

Replay Search

Under Alerts & Events, select an entity to access the replay search option under Actions. This will take you to the specific search page that triggered the alert or event. You may review the search results and messages to gather important details in investigating the alert or event. Note that this page can also be bookmarked for future reference.

Priority

The priority of an event is a classification for user purpose. Events may be prioritized from 1 to 3 (1=low, 2=normal, and 3=high) according to their importance. This assessment can help you triage events, which is a necessary practice in security investigations. The priority of an event will be displayed as an icon in the overview and will be written into the notification.

Filter

By combining a filter and an aggregation, you can specifically describe the criteria of an event. Define a filter by using the search query in the same syntax as the search page. Select a stream in which the message can be found. Define the window of time that the filter will search backward to match messages. The search will be executed at the given interval. If the filter matches, an event can be created.

If the defined filter matches messages currently within the Graylog Server, they will be displayed in the Filter Preview panel on the right.

Filter with Dynamic Lists (Operations feature)

The following section exclusively pertains to a Graylog Operations feature. To learn more about obtaining an Operations license, please contact the Graylog Sales team.

Dynamic lists allow you to define a filter where some of the search arguments are parameterized. Every time an event definition is being checked, these parameters are replaced with the result of a configured lookup table. For example, you maintain a list of former employees in Active Directory or an HR system and want an alert if anyone on the list tries to log in. You can define a filter like login from username $former_employee$, where the parameter $former_employee$ is backed by a lookup table that returns a current list of your former employees. This ensures that all former employees (including those recently added) are a part of the search.

Aggregation

An aggregation is the combination of two or more entities. The new entity processes specific and meaningful results. Aggregations can run a mathematical operation on either a numeric field value or the raw count of messages generated that match the filter. Aggregations can group matches by a selected field before making the comparison. For instance, if the field username is defined, then it is possible to alert on five successive failed logins by a particular username. This use case is shown below.

Fields

Fields may be managed in the Fields menu, located in the sidebar. Users may create custom fields which allow the event to populate data from the original log into the Graylog Events index. This prevents the operator from having to run subsequent searches to get vital information. This can also be used to limit the amount of data sent to a notification target. The event will be recorded to the All Events stream and will contain the custom field as well as the result of the aggregation that triggered the event.