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. Event definitions can watch for search matches, event sequences, anomalies, asset risk thresholds, license usage, and imported Sigma rules.

This article explains what events and event definitions are, how they work, what each part of a definition does, and how you create, alert on, and manage definitions over time. For step-by-step instructions on how to create event definitions, 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, plus any event fields you defined. It is stored in the All Events stream and shown 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, read the event summary, follow any attached event procedures, replay the search that triggered the event, and add events to investigations.

Hint: Events, event definitions, alerts, and notifications are related but distinct:

Event definition: The logic that decides whether something noteworthy has occurred.
Event: The record Graylog creates each time an event definition's condition is met.
Notification: The delivery mechanism 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

You can create an event definition through the New Event Definition wizard, directly from search results, or by importing a Sigma rule. Each step of the wizard maps to components of the definition, and the sections that follow explain those components. See Create Event Definitions for the three creation routes, or Event Definitions Use Case for a worked example that builds one end to end.

Event Details

Every event definition includes a title, a description, and a priority. You can also add an event summary template and event procedures. Together, these make up the event details.

Priority

Event priority is a user-defined classification that indicates the relative importance of an event. Graylog uses five priority levels: Informational (1), Low (2), Medium (3), High (4), and Critical (5).

This classification helps prioritize and triage events during security investigations.

For example, a single failed login within 10 minutes might be a low-priority event. Two or three failed logins in the same time frame might be medium priority. More than 15 failed logins within 10 minutes might be high or critical, because this pattern can indicate a brute-force attack.

The priority is displayed on the Alerts & Events page and is included in the generated alerts.

Event Summary Template

The Event Summary Template is an optional field that allows you to customize how events appear on the Alerts & Events page. When populated, Graylog uses this field to generate event-specific data in the summary description details, giving you context-rich summaries built from dynamic values.

The Event Summary Template supports Java Minimal Template Engine (JMTE) syntax, letting you reference fields from the event and its associated data similar to how templates are used in email notifications. See JMTE Templating for the full set of supported expressions.

Example:

Event triggered for user ${fields.username} on host ${source.source}

This renders a descriptive summary using values from the event at runtime.

Condition

An event condition is the underlying logic that determines when an event definition triggers. For example, a search query that matches incoming log data, a sequence of other events that occur together, or an anomaly flagged by a built-in algorithm. Every event definition is built around a condition type.

Graylog offers the following condition types:

Filter & Aggregation: Define events from a search query against incoming log data, optionally aggregating the matches over a time window so that an event is created only when the result crosses a threshold you set. This is the default condition type. See Create Event Definitions to configure one.
Event Correlation: Define events based on the occurrence of multiple other defined events in a sequence. See Correlation Events 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 Rules Event Definition 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

An event definition can also carry optional metadata that makes its events easier to find, classify, and enrich:

Tags (optional): Labels attached to the event definition. Tags are copied onto every event the definition produces, making filtering and grouping easier on the Alerts & Events page. Graylog converts tags to lowercase and removes duplicates. Tags can contain only lowercase letters, digits, hyphens, underscores, and periods.
Tactics/Techniques (optional): MITRE ATT&CK® tactic, technique, or sub-technique IDs, for example, TA0002, T1059, or T1059.001. When you import a Sigma rule, Graylog automatically fills in this field from the rule's tags. See Tags and Tactics/Techniques for details.
Event Fields (optional): Custom fields that copy data from the original log message into the Graylog events index, so you don't need to run subsequent searches to get vital information. You can use event fields to limit the data sent to a notification target, include them in aggregations, reference them in alerts, 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

Notifications deliver information about an event to people or systems, for example by email, Slack, or HTTP request. Attach one or more notifications to an event 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 to learn how to set up an alert, and alert types for the available notification types.

Manage Event Definitions

Once an event definition exists, you can enable, disable, edit, or duplicate it, customize how its events are summarized, manage saved Sigma repositories, manage the event definitions that Graylog Illuminate provides, and replay the search that produced a given event. See Manage Event Definitions for details.

Scheduling

Every enabled event definition runs on a schedule. By default a definition executes at a fixed search interval, repeatedly evaluating a rolling window of recent data. You can instead schedule it with a cron expression to run at a precise time, date, or recurring interval. See Cron Scheduling for Event Definitions for details.

Dynamic List Filtering

A condition's search query does not have to be static. You can parameterize it with a dynamic list, such as a lookup table of watched user names or IP addresses, so that the definition's results update automatically as the contents of that list change. See Filter Event Definitions with Dynamic Lists for details.

Tuning Noisy Definitions

A definition that produces a high volume of low-value events contributes to alert fatigue and makes genuine detections harder to spot. The Event Definition Tuning Advisor reviews your noisiest definitions, identifies tuning candidates, and posts specific suggestions that you review and apply. See Event Definition Tuning Advisor Agent Workflow for details.