Create a scheduled search
A scheduled search is a search that runs on a scheduled interval, and which triggers an action each time it is run. There are two actions available for scheduled searches: Send email and Run a script.
You can use scheduled searches to send the results of the search to a set of designated recipients via email on a schedule that you determine, such as every day at noon or each Monday at midnight.
You might use the Run a script action to post the results of the search to a external system for further processing or archiving on a regular schedule.
For more information about the Send email and Run a script alert actions, see "Set up alert actions" in this manual.
Note: You can also schedule a report when you create a report using the Report Builder.
Important: You can only create scheduled searches if your role includes the
schedule_search capability. For more information about roles and capabilities, see "About defining roles with capabilities," in the Securing Splunk Manual.
Schedule the search
To create a scheduled search, run a new or saved search that you would like to schedule. Click Create and select Scheduled search... to open the Create Scheduled Search dialog.
On the Schedule step of the Create Scheduled Search dialog, you design a schedule for the search. For the Schedule field, you can select one of the preset schedules--the preset selected in the example above, Run every day, ensures that the search will run each day at midnight--or you can select Run on custom schedule (cron schedule) to design a schedule using standard cron notation. When you select the cron notation option a field appears in which you can enter the cron schedule.
Note: Splunk only uses 5 parameters for cron notation, not 6. The parameters (
* * * * *) correspond to
minute hour day month day-of-week. Splunk does not use the 6th parameter for
year, common in other forms of cron notation.
Here are some cron examples:
*/5 * * * * : Every 5 minutes */30 * * * * : Every 30 minutes 0 */12 * * * : Every 12 hours, on the hour */20 * * * 1-5 : Every 20 minutes, Monday through Friday 0 9 1-7 * 1 : First Monday of each month, at 9am.
Next, select the Time range over which the search should be run. This will default to the time range you selected for the search, but you can override it if you wish. In the example above, the search spans the 24 hour period previous to the search start time. So when it runs each day at midnight it covers the entire span of the previous day, starting from the last time the search was run.
Manage the priority of concurrently scheduled searches
Depending on how you have your Splunk implementation set up, you may only be able to run one scheduled search at a time. Under this restriction, when you schedule multiple searches to run at approximately the same time, Splunk's search scheduler works to ensure that all of your scheduled searches get run consecutively for the period of time over which they are supposed to gather data. However, there are cases where you may need to have certain searches run ahead of others in order to ensure that current data is obtained, or to ensure that gaps in data collection do not occur (depending on your needs).
You can configure the priority of scheduled searches through edits to
savedsearches.conf. For more information about this feature, see "Configure the priority of scheduled searches" in the Knowledge Manager manual.
Set up scheduled search actions
After setting up a schedule for your search and clicking Next, you come to the Actions step of the Create Scheduled Search dialog. Here you can set up the action that Splunk performs each time it runs the search.
Splunk provides two possible actions for scheduled searches:
- You can arrange to have Splunk send emails to a set of recipients each time the search is run. These emails can contain the search results, or they can include the search results as CSV or PDF attachments.
- You can arrange for Splunk to run a script that does something with the results of each run of the search.
Send emails to a set of stakeholders
If you want Splunk to contact stakeholders when the alert is triggered, select Send email.
For the Addresses field, enter a comma-separated list of email addresses to which the alert should be sent.
For the Subject field, supply a subject header for the email. By default it is set to be Splunk Alert: $name$. Splunk will replace $name$ with the saved search name.
Include results in scheduled search emails
If you're setting up a scheduled search so it sends an email to a set of recipients each time it is run, you'll probably want the email to contain the results of the search. This works best when the search returns a single value, a truncated list (such as the result of a search that returns only the top 20 matching results), a table, or a chart visualization.
If this is so, click Include results as and select either as CSV, inline, or as PDF.
- as CSV - Have Splunk convert the results to .CSV format and attach the file to the alert notification email.
- inline - Have Splunk deliiver the search results in the body of the alert email.
- as PDF - Have Splunk deliver the search results in the form of a PDF attachment. (You no longer need the PDF Report Server App to generate search result PDFs. The functionality is now built into core Splunk.)
The result inclusion method is controlled via
alert_actions.conf (at a global level) or
savedsearches.conf (at an individual search level). For more information see "Configure alerts in savedsearches.conf" in this manual.
Note: For your email notifications to work correctly, you first need to have your email alert settings configured in Manager. See the "Configure email alert settings in Manager" subtopic, below.
For more information about using Splunk's integrated PDF generation functionality, see "Upgrade PDF printing for Splunk Web" in the Installation Manual.
The following is an example of what a scheduled search email looks like when results are included inline (in the body of the email):
Configure email alert settings in Manager
Scheduled search email delivery will not work if the email alert settings in Manager are not configured, or are configured incorrectly. You can define these settings at Manager > System settings > Email alert settings.
On the Email alert settings Manager page, you can define the Mail server settings (the mail host, security type, username, password, and so on) and the Email format (link hostname, email sender name, email subject header, and inline results format).
Finally, if you are sending results as PDF attachments (see above) you can determine the paper size and orientation of the PDF report under PDF Report Settings.
As of release 5.0, Splunk's integrated PDF functionality no longer requires the PDF Report Server App to generate PDFs of search results. You can print search results and dashboards that have been constructed with simple XML just fine without it.
Note: This integrated PDF generation functionality is easier to use than the PDF Report Server App but it doesn't replace it completely. You'll still need the app if you intend to print or share PDFs of dashboards that have been constructed with advanced XML, dashboard panels that are rendered in Flash, and forms. If you install the PDF Report Server App, set the appropriate Remote PDF Report Server URL on the Email Alert Settings page.
For more information about integrated PDF generation see "Upgrade PDF printing for Splunk Web" in the Installation Manual.)
If you are planning to use the PDF Report Server App, the Link hostname field must be the search head hostname for the instance sending requests to a PDF Report Server. Set this option only if the hostname that is autodetected by default is not correct for your environment.
Specify your choices and click Save to have all alerts use these settings for email actions.
Note: If you don't see System settings or Email alert settings in Manager, you do not have permission to edit the settings. In this case, contact your Splunk Admin.
You can also use configuration files to set up email alert settings. You can configure them for your entire Splunk implementation in
alert_actions.conf, and you can configure them at the individual search level in
savedsearches.conf. For more information about
.conf file management of saved searches and alert settings see "Configure alerts in savedsearches.conf" in this manual.
Run a script
If you want Splunk to run a script when each time the search runs on its schedule, select Run a script under Enable actions and enter the file name of the script that you want Splunk to execute.
For example, you could have a scheduled search that runs a script that calls an API, which in turn sends the results of the search to another system.
Note: For security reasons, all scripts must be placed in
$SPLUNK_HOME/etc/<AppName>/bin/scripts. This is where Splunk will look for any script listed in a scheduled search definition.
For detailed instruction on scheduled search script configuration using
savedsearches.conf in conjunction with a shell script or batch file that you create, see "Configure scripted alerts" in the Admin Manual.
If you are having trouble with your scheduled search scripts, check out this excellent topic on troubleshooting alert scripts on the Splunk Community Wiki.
On the Sharing step of the Create Scheduled Search dialog you can determine how the scheduled search is shared with other users of your Splunk instance if you have a role that gives you Write access to the knowledge objects in your app (such as the Power or Admin roles).
You can opt to keep the scheduled search private, or you can share the scheduled search as read-only to all users of the app you're currently using. For the latter choice, "read-only" means that other users of your current app can see and use the scheduled search, but they can't update its definition via Manager > Searches and reports.
You can find additional permission settings in Manager > Searches and reports. For more information about managing permissions for Splunk knowledge objects (such as alert-enabled searches) read "Manage knowledge object permissions" in the Knowledge Manager Manual.
Create scheduled searches in Manager
In Manager you can arrange to have saved searches behave like scheduled searches that have been set up with the Create Scheduled Search dialog.
1. Navigate to Manager > Searches and Reports, and select Schedule this search to open up the scheduling and alerting options.
2. Set up the search schedule. You can choose a Schedule type of Basic (which enables you to choose from a range of preset options) and Cron (which enables you to set up a schedule using standard cron notation (see above for details).
3. To make this search behave like a scheduled search created with the Create Scheduled Search dialog, set the alert Condition to Always. This ensures that the alert actions you define are performed each time the search is run.
4. Make sure Alert mode is set to Once per search. There's no need to activate Throttling for scheduled searches, and the Expiration and Severity settings are unimportant for scheduled searches.
5. Set up the alert actions required for your scheduled search. For full details on all of the available alert action options, see "Set up alert actions", in this manual.
6. For the Summary Indexing setting, see the "Enable summary indexing" subtopic below. It is only required if you intend for this scheduled search to populate a summary index.
7. Click Save to save your changes.
Enable summary indexing
Summary indexing is an action that you can configure for any scheduled search via Manager > Searches and Reports. You use summary indexing when you need to perform analysis/reports on large amounts of data over long timespans, which typically can be quite time consuming, and a drain on performance if several users are running similar searches on a regular basis.
With summary indexing, you base a scheduled search on a search that computes sufficient statistics (a summary) for events covering a slice of time. The search is set up so that each time it runs on its schedule, the search results are saved into a summary index that you designate. You can then run searches against this smaller (and thus faster) summary index instead of working with the much larger dataset from which the summary index receives its events.
Note: You do not need to use summary indexing for searches that already benefit from report acceleration. For more information and a distinction between these two methods of speeding up slow running searches, see "About report acceleration and summary indexing" in the Knowledge Manager manual.
To set up summary indexing for an a scheduled search, go to Manager > Searches and Reports, open the detail page for the search that will populate the summary index, and click Enable under Summary Indexing. To enable the summary index to gather data on a regular interval, the search must have an Alert condition of always.
Note: There's more to summary indexing--you should take care to properly construct the search that populates the summary index. In most cases special reporting commands should be used. Do not attempt to set up a summary index until you have read and understood "Use summary indexing for increased reporting efficiency" in the Knowledge Manager manual.
Review triggered alerts
Configure alerts in savedsearches.conf
This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18