Trigger properties

Security Requirements and Controls

  • Create triggers permission

  • Update triggers permission

The following properties are available and configurable from the side panel when creating new triggers or editing existing triggers:

Property Scheduled Searches Aggregate Alert Filter Alert Legacy Alert
Name Required Required Required Required
Description Optional Optional Optional Optional
Labels Optional Optional Optional Optional
Trigger type Required Required Required Required
Time window Required Required - Required
Throttling - Required Optional Required
Actions Required to run Required to run Required to run Required to run
Timestamp @timestamp @ingesttimestamp is default; @timestamp can be used @ingesttimestamp @timestamp
Query model Required Required Required Required
Schedule Required to use either Use cron expression or Simple to set schedule. Fields in Schedule adjust according to this selection. - - -
Delay run Available - - -
Backfill Limit Available - - -
General properties

  • Change the Name and enter a Description of what causes the trigger to be fired to help identify its purpose.

  • Categorize triggers using Labels. Labels are a useful way to tag the triggers with meaningful data and to help when trying to differentiate them. Existing labels are presented as a list of checkboxes, or you can enter a new label and create and select it. Labels can be used within the Triggers overivew to filter triggers, see Manage triggers for more information.

  • Trigger Enabled indicates that the trigger is enabled (new triggers are automatically enabled). To disable the trigger, toggle this button. Disabled triggers do not execute the corresponding query or set off actions.

Actions

You can modify the list of suitable Actions for LogScale to take when the query matches. An alert will not be executed until there is at least one configured action.

When adding or removing actions, any actions being executed when the alert is updated will be completed, and the new list of configured actions will be triggered when the alert triggers again.

Actions Area in Properties Panel

Figure 200. Actions Area in Properties Panel


To remove an existing action from a trigger, click the X next to each action.

For more information about actions, see Actions.

Query

The content of the Query section depends on whether you are creating a new trigger or editing an existing trigger.

When creating a new trigger, in Query type select whether to run a live query (for alerts) or a scheduled search.

If Live is selected, choose the alert type in Alert type.

For information about each trigger type, see Triggers. For help choosing the trigger type, see What trigger type to choose.

Query area when creating a new trigger

Figure 201. Query area when creating a new trigger


When editing a trigger, Alert query contains the alert query as configured. Click Edit in search page to modify the query; this redirects to the Search page.

Query area when editing a trigger

Figure 202. Query area when editing a trigger


Important

It is not possible to change the Query type or Alert type when editing triggers. If you need to reuse other properties of the trigger, duplicate the trigger and change the query type or alert type. For more information, see Duplicate Trigger.

Time window

Time window is available for aggregate alerts, legacy alerts, and scheduled searches.

Time window allows you to set the time interval for the alert (in seconds, minutes, and so on). In Aggregate alerts, available options are Preset (choose from a predefined list) or Custom interval to set other preferred time intervals.

When using Custom interval in Aggregate alerts, please be aware that only the following inputs are valid:

  • 1-80 minutes in intervals of 1 minute (1, 2, 3, ..., 80)

  • 82-180 minutes in intervals of 2 minutes (82, 84, 86, ..., 180)

  • 1-24 hours in intervals of 1 hour (1, 2, 3, ..., 24)

Representing the values with a different unit is also possible. These are examples of valid options:

  • 82 minutes or 4,920 seconds

  • 24 hours or 86,400 seconds

  • 12 hours or 720 minutes

For scheduled searches, the maximum allowed time window is 10 years.

In case invalid inputs outside of the allowed ranges are entered, the UI displays a warning message:

Invalid Search Interval

Figure 203. Invalid Search Interval


Advanced settings

The options available in Advanced settings depend on the trigger type and alert type selected.

Throttling

Important

Throttling is optional for Filter alerts, and required for Aggregate alerts and Legacy alerts.

Throttling enables how often an alert can trigger, so that it will not trigger again until after the throttle period has passed. The throttle period can be set along with the other properties when creating a new alert. You can throttle all actions or specify a field to throttle on. For general information about throttling, see Throttling. For information about throttling for a specific type of alert, go to Triggers and select an alert type.

The following options are available:

  • Throttle period

    Set the period during which the alert can be triggered. The alert will be triggered at most once per period.

    Throttle period is optional for Filter Alerts, but it is mandatory for Aggregate alerts and Legacy alerts.

    The maximum allowed throttle period is 1 week for Legacy alerts and Filter alerts. For aggregate alerts, the maximum allowed throttle period is 24 hours.

    The unit used for the throttle period can go from seconds to weeks.

  • Throttle all actions

    Once the alert has triggered, it will not trigger again until after the throttle period has passed.

  • Field-based throttling

    Once the alert triggers for the field specified in Throttle field name, no further events with the same values for that field will be sent again until the throttle period has passed. See details at Field-Based Throttling.

Timestamps

Note

Timestamp selection is only available for Aggregate alerts.

Options are: @ingesttimestamp (when the event entered LogScale), or @timestamp (when the event actually happened in the producing system). For general information about timestamps for triggers, see Timestamps for triggers.

The timestamp selection is reflected in Properties panel and can be changed at any time from there. The alert timestamp selection is reflected in the footer of the Time Interval panel, see Change Time Interval for more details.

The selected timestamp appears as a new column in the Event List, identified by a tiny time icon: the column will show the time frame the page is actually running on, driven by the chosen timestamp:

Timestamp Selection in Event List

Figure 204. Timestamp Selection in Event List


Query model

Use the query model section to set the owner of the query. Note that you might not see all available options if you do not have the permissions necessary. For general information about the query model, see Query model.

  • Select Run on behalf of organization to have ownership belong to an organization. You can see and edit this field if you have Change persistent queries to run on behalf of organization" or root system permissions. See also Organization Owned Queries

  • Select Run on behalf of user to run the trigger on behalf of another user i.e. using their permissions; click this field to get a list of available users, or directly enter the name of the user to run the trigger as. You can see and edit this field if you have the ChangeTriggersToRunAsOtherUsers permission.

Scheduled search properties

The following sections describe some of the fields you can set or use specifically on a scheduled search.

Backfill Limit

If LogScale is down or an error prevents an action from being triggered, you will miss searches that would have otherwise been scheduled and executed. When it again becomes possible for schedule searches to run and have them trigger actions, LogScale will attempt to backfill searches that were missed previously.

The backfilling behavior is only available for scheduled searches and depends on the value given to the backfill limit, which determines how many missed searches will be executed before any new searches are scheduled.

For example, if you schedule a search every hour:

cron
0 * * * *

and LogScale is down between 10:30 and 14:15, this means that the searches at 11:00, 12:00, 13:00 and 14:00 would be missed.

Executing the most recent 'missed' search is not considered backfilling, as this can also occur under normal operation if there is a slight delay within LogScale. Thus, if the backfill limit is set to 0, as per default, only the search at 14:00 will be executed at startup.

If you increase the limit to 1 you would start off by executing the search scheduled at 13:00. If you increase the limit to 2 you start with the search at 12:00. And if you increase the limit to 3 you start with the search at 11:00. Increasing the value of the backfill limit beyond this point will not have any effect in this example. Missed searches are executed in sequence from oldest to newest.

The backfill limit may not exceed the global maximum backfill limit.

Delay run

Use Delay run to set a delay to make sure the search run does not miss late-arriving events.

When calculating the delay, this should be the sum of ingest delay outside of LogScale (before the events enter LogScale) and ingest delay inside of LogScale over all events relevant for the scheduled search. For more information, see General information about ingest delay.

Search Schedule

If you want to write a cron expression to control the search scheduled, select Use cron expression. This enables the Search Schedule.

Note

Alternatively, you can use the Frequency drop-down to set up a scheduled for your search. This creates a cron expression in the background. For more information, see Search Schedule.

Search schedule allows you to specify the schedule on which your scheduled search should be run. The schedule is defined using a UNIX cron expression, as known from the crontab file found in many UNIX-like systems. There are many online tools to help you generate UNIX cron expressions that you can use if you need help writing up an expression for your use case.

For more information, see Cron Schedule Templates

Note

Times in the cron search schedule are based on UTC by default. To change this, use the UTC Offset to change the time offset. For more information on cron settings, see Cron Schedule Templates.

Use the Frequency drop-down to select how frequently the scheduled search runs. If you choose weekly or monthly, you have the option to choose days of the week or days of the month on which the scheduled search runs.

In Time set the time at which the scheduled search starts and the timezone in relation to UTC time.

UTC Offset

The Coordinated Universal Time(UTC) offset defines the temporal offset from UTC in which the search is scheduled. For instance, with a schedule:

cron
0 6 * * *

With an offset UTC+01:00, the search will be scheduled for 5AM at UTC.

Space out searches

LogScale always attempts to run a search exactly according to schedule. This makes scheduled searches predictable, but also risks that many scheduled searches will be configured to run at the same time, which might cause delays. If there are multiple scheduled searches running, it is a good idea to spread them out over time, so that they are not running all at the same time.

For example, it is common to schedule many jobs for midnight, if they are to be run daily. But if you experience delays in search execution because of a sudden high search load, try to space the searches out over a larger span of time.

One way to automate this, rather than manually tracking individual requests, is to use the H notification. Using H for minutes in the cron expression, allows LogScale to automatically choose the number of minutes past each hour that a scheduled search will be run.

Using this notation can be an effective way spreading out the execution of scheduled searches without having to monitor and track each scheduled search manually. The notation also makes it easy to copy and duplicate scheduled searches.

This method is only appropriate if you do not need to explicitly control the search window. Because H automatically chooses a minute, the search window will be determined by the chosen figure. For example, if you use the H notation to run the search from 24 hours ago to now, and the search runs at 0:48, then the search window will be from 0:48 yesterday until 0:48 today.

If you decide to run a search on another schedule, but wish to keep the same search window, you need to update start and end on your scheduled search. For instance, if your search was running at midnight and searching through the previous day, you would have configured the interval parameters as start=24h and end=now. But if you need to reschedule this search run at 3AM instead, you would have to update the interval parameters as start=27h and end=3h to search within the same 24 hour time window.