Change triggers and actionspermission
A scheduled search is a static query, set to run on a schedule. At a scheduled interval, the query will run and if its result is non-empty, the scheduled search will trigger its associated actions.
Scheduled searches are related to Alerts and they are able to trigger the same actions. However, scheduled searches are applicable in other use cases than alerts, such as when:
You need to automatically report some search result on a schedule. For instance, you have stakeholders that expect to get an email every Monday at 10:00 containing the top most important security events for the previous week.
You have an ingest delay on some logs, which results in them never appearing in searches made by alerts. For instance, if an alert looks back in time using a
1htime window, it won't trigger on logs ingested with a 12 hour delay. With a scheduled search, you can choose to run your search at a point in time, where you're fairly certain that every log of interest has been ingested.
You need to take delayed action on search results. For instance, if you trigger user bans using an alert, offending users will be banned immediately upon a transgression and can then easily figure out what triggered their ban. Using a scheduled search, you can choose to ban all offending users at the same time every day, as to obscure the conditions of a ban.
If your situation doesn't fall into one of these use cases, you should probably use an alert instead. Alerts run as live queries, rather than historic ones, and should thus generally be considered more performant.
Creating a Scheduled Search
Go to the Repository and Views page.
Select a Repository.
Click the Alerts tab on the top bar of the User Interface
Select Scheduled Searches appears. They can have labels attached to them which are displayed next to the scheduled search name. This can be a useful way to tag the scheduled searches with meaningful data and to help when trying to locate them with a certain tag.from the menu on the left: the full list of available
Figure 200. Creating Scheduled Search from Tab
In the New scheduled searchdialog popping up, enter a name for the search and choose how to create it:
Empty scheduled search to create a new empty scheduled search from scratch, then click
From template to browse for or drag and drop a template based on an existing scheduled search, then click See more details at Cron Schedule Templates.
From package to invoke scheduled search templates that are part of a LogScale package, then click .
In the New scheduled search page, fill in the required information as shown here:
Figure 201. Setting Scheduled Search Properties
When you're finished setting the properties for the new scheduled search, click.
Alternatively you can use the GraphQL API to view, create, update and delete scheduled searches using the associated queries and mutations.
Scheduled searches, per default, will not trigger any action(s), if a query result contains a warning. Scheduled searches have the same behavior as alerts in regards to warnings and errors, see Errors & Warnings page.
In the following we discuss some of the fields you set on a scheduled search.
Scheduled Search Permissions
You can run the scheduled search with the permissions of another user; click the Scheduled search permissionsfield to get a list of available names to pick from, or directly enter the name of the user you want to run the schedule search as.
You can see and edit this field if you have
permissions, and have enabled the feature.
This field 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
file found in many UNIX-like systems. Scheduled searches are not
allowed to run more than once an hour. Therefore the
minutes field in the cron
expression is restricted to only allow values in the range
[0-59]. 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.
Cron Schedule Templates
Instead of providing a fixed minute which a scheduled search should
run, a template can be provided by specifying the character
H in the UI, which will run the
scheduled search at a random, but fixed minute (based on the hash of
the ID) — see figure below:
Figure 202. Cron Schedule with Template
The template will pick a number in the range
[0-59] for when the search
should run, and all consecutive searches will run on the same minute.
The search will run at a fixed arbitrary minute past every hour,
meaning that if a search is made with the cron expression schedule
H * * * *, and the minute chosen
is 48, the search will run at 00:48, 01:48, 02:48 etc. This is only
supported for minutes and only a lone
H is supported, not constructs
This is useful for scheduled searches that are part of packages as they would be run by many customers on our cloud, and the template will spread out the load instead of all searches being ran at the same time.
The Coordinated Universal Time(UTC) offset defines the temporal offset
from UTC in which the search is scheduled. For instance, with a
0 6 * * * and an offset
UTC+01:00, the search will be
scheduled for 5AM at UTC.
As for all searches, a time interval must be specified. For scheduled
searches the time interval is given by a
end time relative to the
scheduled execution time. For instance, if a scheduled search is
executing at midnight Jan 2nd, with a time interval of
start = 24h and
end = now, the search will
consider all logs within the time interval:
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, which were missed previously.
The backfilling behavior depends on the value given to the backfill limit, which determines how many missed searches will be executed before any new searches are scheduled.
Let us say that we schedule a search every hour,
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 were 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
0, as per default, only the
search at 14:00 will be executed at startup.
If we increase the limit to
would start off by executing the search scheduled at 13:00, if we
increase the limit to
2 we start
with the search at 12:00 and if we increase the limit to
3 we 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. Note that the missed
searches are executed in sequence from oldest to newest.
The backfill limit may not exceed the global maximum backfill limit.
Spacing Out Searches
LogScale will always attempt 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. 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.
If you decide to run a search on another schedule, but wish to keep the
same search window, you need to update
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
end=now. But if you need to
reschedule this search run at 3AM instead, you would have to update the
interval parameters as
end=3h to search within the
same 24 hour time window.