Document toolboxDocument toolbox

Each alert type

Overview

Each method triggers an alert for each event that reaches your query.

The threshold for this kind of alert is defined by the filters you have applied in the query. So, each time an event is written on the data table and meets the conditions of your query, an alert will be triggered.

This type of alert could be useful when monitoring key data and every single event needs to be considered individually.

What data do I need to create this alert?

To create an alert using this triggering method, you can apply filters and create new fields in your query as well as group and aggregate data. However, note that this type of alert only accepts time-based grouping (they cannot be defined with queries with non-time-based grouping).

Less than 60 events

Refine your query to show fewer than 60 events in the table. Otherwise, you won't be able to create the alert due to a potentially excessive number of alerts being generated.

2_Each alert type.png

Using subqueries

The each type is the only one that allows the use of subqueries, however, this feature comes with certain limitations:

  • Queries must not include nested subqueries.

  • Queries must not include a fixed time range in the subquery.

  • Queries must not include a temporal grouping in the subquery.

  • Tables such as my.lookuplist tables (more about them here) can be used with some limitations :

    • Only inner queries can contain them.

    • The specified period cannot be less 24 hours.

Query

Allowed?

Query

Allowed?

from T1  where x in (      from T2          where y in (              from T3          )  )

This query includes nested subqueries, so it is not allowed.

from T1  where x in (      from T2      where 100 <= eventdate < 200  )

This query includes a fixed time range in its subquery, so it is not allowed.

from T1  where x in (      from T2      group every 10m  )

This query includes a temporal grouping in its subquery, so it is not allowed.

This query has neither a group nor a time range in its subquery, so it is allowed.

This query has a temporal grouping, but it is not included in the subquery. Therefore, it is allowed.

Specific settings

Include all fields

5_Each alert type.png

After selecting this type of alert, you don't have to select any other setting to successfully configure it.

However, for queries that do not group data, you can decide whether you include inside the extraData all fields in the table or not. Checking the box will include all of them while leaving it unchecked will include only those explicitly specified in the query, as well as the eventdate.

As this option may imply an impact on performance, we recommend minimizing its use.

extraData

The extraData is the field that consolidates the content of the different event fields related to the triggered alert to provide the user with context about the triggering conditions. More info here.

Internal period, internal offset, and external offset (only with subqueries)

The Internal period is used to set the subquery time range. For example, for an internalPeriod of 10 days, the subquery time range would be [now() - 10d, now()].

The Internal offset is used to move the subquery time range backward in time. For example, if the subquery time range is [now()-10d, now()] with an internalOffset of 2 days, the time range would be [now() -12d, now() - 2d].

The External offset is used to move the main query time range backward in time. For example, if the main query time range is [now()-1h, now()] with an externalOffset of 2 days, the time range would be [now() -1h -2d, now() - 2d].

For all the parameters explained above, you can use preset periods or create custom periods:

  • Preset periods: click the dropdown and select the desired option (you can use the editable field to filter them).

  • Custom periods: click the dropdown, write the desired period in the editable field and then click the green field that appears below to confirm it. You have to introduce a valid format, otherwise, you will get an error message. The accepted format consists of a number followed by a duration code without space between them:

Duration

Format

Example

Duration

Format

Example

Days

(0-n)d

1 day → 1d

Hours

(0-24)h

15 hours → 15h

Minutes

(0-59)m

45 min → 45m

Compound: you can stack the different durations to create a compound

(0-n)d(0-24)h(0-59)m(0-59)s

15 hours, 45 minutes, 50 seconds → 15h45m50s

Min/max period

The periods must be at least 1 minute and up to 100 days to be accepted for alert creation.

Internal period/external period permitted ratio

When the external period (time grouping in the main query or 1 minute when not specified) is less than 1 day, the ratio between internal period/external period must not exceed 120. A ratio above 120 will prevent the alert from being created and will return an error message.

  • Valid ratio → external period 1m, internal period 2h(=120m) → 120/1 → 120

  • Valid ratio → external period 2h, internal period 5d(=120h) → 120/2 → 60

  • Invalid ratio → external period 1m, internal period 3h(=180m) → 180/1 → 180

Starting moment

The period will not start counting from the moment of the alert creation but from a fixed division that takes the Epoch reference date as the starting point (midnight Jan 1, 1970). This means that if you created an alert past the hour with a one-hour period, the first time it will be triggered (if the conditions are met) will be when the clock strikes the hour and not after 60 minutes. In other words, if you created it at 9:37, it will be triggered at 10 and not at 10:37.

The period will be adjusted according to the timezone specified in the alert definition window (more info here).

Using field values in Summary and Description

You can use the $fieldName command to display in the Summary and Description fields the field values of the event that triggered the alert. This command can be employed with the name of any field present in the query result.

In the following query, you could use:

 

 

$eventdate
$clientIpAddress
$timestamp
$method

$uri
$protocol
$statusCode
$bytesTransferred

$referralUri
$userAgent
$cookie
$timeTaken

Take into account that if your query groups events, this command will only work with the names of those fields resulting from the grouping operation. Using a different one will not activate the command and will be interpreted as plain text.

In the following query, you could use:

 

 

 

$eventdate
$method
$timeTaken

 

Query example

In the demo.ecommerce.data table, imagine that you want to receive an alert each time there's an event that comes from a private IP address.

First of all, you need to filter the query data using the Is Private IPv4 (isprivate) operation. Then, you need to open the alert definition window and select an each type alert.

To save time, you can copy the following query to reproduce the aforementioned example from the demo.ecommerce.data sample table and create an each type alert.

 

Related articles