Set sequence=true to require events to match in chronological order.

When matching events across each query within correlate() one or more constraints can be added to the selection, which control how matches across each event set are determined.

Using sequence set to true forces the constraint and correlation to require matching events to occur in sequence (by their @timestamp by default) as defined in the list of queries. To change the field to be used for the order, use the sequenceBy parameter.

For example, the query:

correlate(
  LoginA: { logon = "FAILURE" },
  LoginB: { logon = "FAILURE" | user.id <=> LoginA.UserID },
  LoginC: { logon = "SUCCESS" | user.email <=> LoginA.UserID },
  sequence=true
)

Forces correlation only to occur if there were two login failures, followed by a success for this specific user. Other combinations (for example: SUCCESS, FAILURE, SUCCESS, or FAILURE, SUCCESS, SUCCESS) would not correlate.

To visualize, the following event sequence would match:

While this sequence would not correlate, because the sequence is incorrect:

The identification of this sequence covers the overall query timespan. For example, if the query is searching over the last 24 hours, the sequence will be matched if that sequence occurs within that 24 hour timeframe. If the event occurred multiple times, it will match multiple times. To look for that specific sequence within a smaller timeframe, use the within parameter.

By default, individual events can appear in multiple correlation sets. To limit it so that each event can only appear once in each event set, set the includeMatchesOnceOnly parameter to true.

By default, correlate() will sequence by @timestamp and @timestamp.nanos or @ingesttimestamp based on the time field chosen when the query was submitted.

If sequenceBy is set, the first field in the array will be compared between two events, in the event they are equal, correlate() will try to compare by the next field and so on. The @id field will automatically be used in the end as the final tiebreaker.

For example, if the query has @ingesttimestamp, but you want to sequence by @timestamp and @timestamp.nanos:

sequenceBy=[@timestamp, @timestamp.nanos]

If the income events have an order, to sequence lexicographically by order:

sequenceBy=[order]

Because events can be registered with minor time differences, using correlated queries on event data with a specific sequence may not be identified correctly. Events occurring out of sequence due to small differences in the timestamps means that the events do not occur in the required sequence.

To account for this, correlate() supports a jitterTolerance parameter which adds a tolerance to the sequence correlation to allow for this difference. Use of this option is only valid if sequence is set to true. The tolerance allows for matches within the given relative time. For example, a jitterTolerance of 1m would allow for the sequence to match even if individual events were out of sequence within a minute of each other. Note that this does not change the value of the within parameter, which defines the timespan of the overall sequence, it only affects how individual events are matched sequentially, for example allowing a single event to occur up to a minute before, rather than after, an event.

For example, with the following query:

correlate(
  LoginA: { logon = "FAILURE" },
  LoginB: { logon = "FAILURE" | user.id <=> LoginA.UserID },
  LoginC: { logon = "SUCCESS" | user.email <=> LoginA.UserID },
  sequence=true,
  within=5m,
  jitterTolerance=2m
)

The corresponding event sequence is shown below, with events in red matching the correlation.

Event B and C (in red) will match the correlation (which is matching for Failure, Failure and Success, even though the sequence don't occur perfectly in sequence because the jitter tolerance means that the event overlap across the events still matches the required event sequence.

Use the within parameter and Relative Time Syntax to specify time windows for correlation matches.

For example, in the query:

correlate(
  LoginA: { logon = "FAILURE" },
  LoginB: { logon = "FAILURE" | user.id <=> LoginA.UserID },
  LoginC: { logon = "SUCCESS" | user.email <=> LoginA.UserID },
  within=5m
)

Each of the logon events across LoginA, LoginB, and LoginC must occur within 5 minutes of each to be considered a match. During this time, the correlation may match multiple times:

In the above sequence, the first two sets of events (Correlate A and B) match, because they both occur within 5 minutes of each other, but the third correlation (Correlate C) does not match because the span of the events is outside the timespan.

When looking for matching events, correlate() iterates over the events for the given timespan multiple times and looks for matching events across each defined query. By default, the query will match the event correlation only once per root query. The root query is by default the first query defined in the correlation. The root parameter can be used to select an alternative root query.

When iterating over the events, correlate() first looks for matches for Query A, then looks for matching events in Query B, and then determines whether the sequence or timeframe matches apply. With maxPerRoot set to 1, the function will return the first match, to return additional matches that originate from query A that should be matched. For example, consider the event sequence below:

There are 5 events, one with success (labelled A), and four with failures (B-E). With the query:

correlate(
  LoginA : { logon = "SUCCESS" | user.email <=> LoginB.user.id },
  LoginB : { logon = "FAILURE" | user.id <=> LoginA.user.email },
  LoginC : { logon = "FAILURE" | user.id <=> LoginA.user.email },
  globalConstraints=[user.id]
  within=10m
)

With maxPerRoot set to 1, only the first correlation (X) will be returned (matching events A, B and C). But within the given timespan, there is a second correlation, events A, D and E also match (Success, Failure, Failure). To return both correlations, maxPerRoot must be set to 2:

In this example, the correlate() function is used to match AWS GetFederationToken events with corresponding ConsoleLogin events for the same user within a 60-minute window, ensuring the events occur in sequence.

The correlate() function finds relationships between the events within the GetFederationToken and ConsoleLogin queries. sequence=true means that events in a constellation must occur in the order that the queries are defined within the time window

Example incoming data might look like this:

The query is used to track the complete authentication flow for federated users accessing the AWS Console, ensuring proper sequence and timing of authentication events. The correlate() function tracks authentication sequences by matching federation token generation events with subsequent console login attempts within a specified time window.

This query is useful, for example, to monitor federation token usage patterns, detect potential token sharing or misuse, and verify that console logins occur within expected timeframes after token generation.

Sample output from the incoming example data:

Note that the following events are excluded from the results because their ConsoleLogin occurred more than 60 minutes after the GetFederationToken:

This demonstrates how the within=60m parameter filters out login attempts that occur outside the expected federation token usage window.

Note that the output includes timestamps from each query. The TimeBetweenEvents field shows the seconds between token generation and console login, useful for identifying unusual login patterns.

In this example, the correlate() is used to match URLs from inbound emails with subsequent HTTP requests to those URLs within a one-hour window, indicating when recipients click on email link.

The correlate() matches URLs received in emails with subsequent access attempts detected in network traffic, helping identify potential phishing or malicious link interactions.

Example incoming data might look like this:

The query is used to identify when users click on URLs received in emails by correlating email security events with network traffic events. The correlate() matches URLs received in emails with subsequent access attempts detected in network traffic, helping identify potential phishing or malicious link interactions.

This query is useful, for example, to detect potential security incidents where users interact with phishing emails, track the effectiveness of security awareness training, or monitor for suspicious URL access patterns.

Sample output from the incoming example data:

In this example, the correlate() function is used to identify when scheduled tasks are registered and subsequently deleted by matching events based on the task identifier (aid field) and name (TaskName field) within a 5-minute window.

The correlate() function finds relationships between the events within the ScheduledTaskRegistered and ScheduledTaskDeleted queries. sequence=false means that events can occur in any order within the time window

Example incoming data might look like this:

The query is used to identify and correlate scheduled task registration and deletion events for the same task within a 5-minute window.

The output demonstrates successful correlation of scheduled task registration and deletion events, showing the complete lifecycle of tasks that were both created and deleted within the specified timeframe.

This query is useful, for example, to monitor task lifecycle patterns, detect unusual task deletion behavior, or audit scheduled task management activities.

Sample output from the incoming example data:

Note that the output includes timestamps from each query. In this case, this allows for analysis of the time between task creation and removal.