Scheduled Searches

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.

Feature Status

Scheduled Searches is a BETA feature. You should test it before relying on it in production.

Use Feature on Cloud

The feature is enabled by default for Humio cloud users.

Use Feature On-Premise

For an on-premise deployment of Humio, you will need to enable the feature to be able to use it. This is done by setting the ScheduledSearches feature flag through GraphQL. This requires root permissions. The following mutations can be used to enable scheduled searches at different levels:

  • Enable for all users: mutation{ enableFeature(feature: ScheduledSearches) }

  • Enable for all users within an organization: mutation{ enableFeatureForOrg(feature: ScheduledSearches, orgId: "<ORG-ID>") }

  • Enable for a single user: mutation{ enableFeatureForUser(feature: ScheduledSearches, userId: "<USER-ID>") }

Note that for any scheduled searches to execute the ENABLE_SCHEDULED_SEARCHES configuration option has to be set to true. See the ENABLE_SCHEDULED_SEARCHES reference page.

Use Case

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 1h time 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 immediatly 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.

Spacing Out Searches

Humio 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 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.