Identify Events

An event is a specific occurrence in your environment that is considered noteworthy. For example, a change made to a firewall policy or a failed login attempt by a known malicious IP address. Each event confirms that something happened at a specific point in time.

An event definition is a saved configuration that tells Graylog which occurrences count as events, how to describe and rank them, and who or what to notify when one happens.

This article explains how an event definition works and what each of its components does. For step-by-step instructions, see Create Event Definitions.

How an Event Definition Works

An enabled event definition works in a repeating cycle. Following that cycle shows where each component of the definition comes into play:

Evaluate: Graylog evaluates the definition's condition on its schedule. Depending on the condition type, it looks at incoming log messages, other events, or signals such as anomaly results and asset risk scores.
Record: When the condition is met, Graylog creates an event. The event carries the definition's title, priority, and tags, along with any event fields you defined, and appears on the Alerts & Events page.
Notify: If the definition has notifications attached, Graylog sends them, and the event is treated as an alert.
Respond: Analysts triage events by priority, follow any attached event procedures, and add events to investigations.

Events, Alerts, and Notifications

Events, event definitions, alerts, and notifications are related but distinct. Keeping them apart tells you what you are configuring and what Graylog produces in response:

Event definition: The logic that decides whether something noteworthy has occurred. Every definition is built on a condition type that determines what Graylog watches for.
Event: The record Graylog creates each time an event definition's condition is met.
Notification: The delivery mechanism, such as email, Slack, or an HTTP request, that sends information about an event to a person or system.
Alert: An event produced by an event definition that has notifications attached.

Event Definition Components

An event definition brings together a condition that decides when it fires, the details that describe and rank the events it produces, optional metadata carried onto each event, and the notifications that deliver it. You configure all of these in the New Event Definition wizard.

Event Details

Event details describe and rank what a definition produces. Every definition has a title, a description, and a priority: a user-defined classification of an event's relative importance, chosen from five levels running from Informational (1) to Critical (5). Priority determines where an event lands when analysts triage during investigations, so set it to reflect how much attention the pattern deserves rather than the severity of any single occurrence.

Two optional additions change what responders see. An event summary template customizes how each event is summarized on the Alerts & Events page, building the description from values in the event itself; it is written in JMTE, the same templating used in email notifications. Attached event procedures give responders specific instructions for resolving the issue.

Condition

The condition is the logic that determines when a definition triggers: a search query that matches incoming log data, a sequence of other events occurring together, or an anomaly flagged by a built-in algorithm. Every event definition is built around one condition type, and that choice determines what Graylog watches.

Graylog offers the following condition types:

Filter & Aggregation: Define events based on search and filtering of log data.
Event Correlation: Define events based on the occurrence of multiple other defined events in a sequence. See Correlation Engine for details.
Anomaly Events: Detect anomalies using built-in algorithms. See Anomaly Events for details.
Asset Events: Define events based on asset events exceeding defined risk score thresholds. See Asset Events for details.
License Usage Monitoring: Define events for license usage based on either absolute thresholds or percentage of your billing period limit. See License Usage Monitoring Events for details.
Sigma Rules: Import a Sigma rule to create an event definition from its detection logic. Requires a Graylog Security license. See Sigma Rule Events for details.

Hint: Events generated by any condition type can also be used as input to an Event Correlation definition, so you can build layered, multi-stage detections.

Additional Details

A definition can also carry optional metadata that is copied onto every event it produces, making those events easier to find, classify, and enrich. Tags label the definition so you can filter and group its events on the Alerts & Events page. Tactics and techniques record MITRE ATT&CK® IDs, which Graylog fills in for you when you import a Sigma rule. Custom event fields copy values out of the original log message into the events index, so the information travels with the event instead of requiring another search; you can reference them in notifications and aggregations and use them with event correlation.

Hint: Every event is stored in the All Events stream with its custom event fields. Events created by Filter & Aggregation definitions also include the aggregation result that triggered them.

Notifications and Sharing

Notifications deliver information about an event to people or systems, by email, Slack, or HTTP request for example. Attach one or more to a definition and Graylog sends them every time the condition is met; an event from a definition that has notifications attached is treated as an alert. See Alerts for how to set one up and alert types for the available notification types.

Because Graylog's permissions model grants access to each entity separately, you can add individual users or teams as collaborators on an event definition and add the definition to existing collections. For complete details, see Share a New Entity.