Splunk® Enterprise

Reporting Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Schedule reports

A scheduled report is a report that runs on a scheduled interval, and which can be configured to trigger an alert action each time it is run. There are two actions available for scheduled reports: Send email and Run a script.

You can email the results of the report to a set of designated recipients on a schedule that you determine. For example, send results every day at noon or each Monday at midnight.

You can use the Run a script action to post the results of the report 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 the Alerting Manual.

Restrictions on report scheduling

You can only create scheduled reports 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.

You cannot schedule reports that run in real-time when you create or edit reports in Search. Only reports that run over a historical time range can be scheduled.

Caution: The Searches, Reports, and Dashboards page in Settings allows you to schedule reports that run in real-time. However, you should avoid doing this. A real-time scheduled report generates an overlarge dispatch directory when it is allowed to run too long. This ultimately causes serious performance issues on the search head. This is especially true of real-time (all-time) scheduled reports as they have no defined time window and therefore can accumulate matching events in an unbounded fashion.
You can also schedule real-time reports in savedsearches.conf. But the result is the same as if you scheduled them in Settings > Searches, Reports, and Dashboards. Avoid scheduling real-time reports to prevent performance problems.

Schedule a report via Splunk Web

Reports can be scheduled during their creation process, or at any time after they have been created.

You can schedule a new report when you first save a search or pivot as a report. For more information about saving searches or pivots as reports, see "Create and edit reports", in this manual.

You can schedule an existing report when you:

  • Navigate to the Reports listing page, locate the report in question, and either
    • Expand a report row, and click Edit on the Schedule line, or
    • Click Edit and select Edit Permissions.
  • Navigate to the report viewing page (by clicking the report name on the Reports listing page) and either:
    • Click Edit and select Edit Permissions
    • Click More info and click Edit for the acceleration status.
  • Navigate to Settings > Searches and Reports and click the name report in question to open its detail page.

If you schedule a report when you create it or edit its schedule settings via the Reports listing page, you'll be brought to the Edit Schedule dialog. See the section "Design a report schedule with the Edit Schedule dialog," below, for information about using this dialog to schedule a new or existing report.

If you schedule an existing report via the Searches and reports page in Settings, see the section Schedule reports in Settings," below.

Design a report schedule with the Edit Schedule dialog

In the Edit Schedule dialog, select Schedule Report to reveal the scheduling options for the report.

For the Schedule field, you can select one of the preset schedules--the preset selected in the example below, Run every day, ensures that the report will run each day at midnight--or you can select Run on Cron Schedule) to design a schedule using standard cron notation. If you select the cron notation option a field appears in which you can enter the cron schedule.

6.0 edit rpt schedule1.png

Note: Splunk Enterprise only uses 5 parameters for cron notation, not 6. The parameters (* * * * *) correspond to minute hour day month day-of-week. Splunk Enterprise 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 report should be run. This will default to the time range you selected for the report, but you can override it if you wish. In the example above, the report spans the 24 hour period previous to the report run time. So when it runs each day at midnight it covers the entire span of the previous day, starting from the last time the report was run.

Note: Real-time time ranges are not available for scheduled reports.

Set up scheduled report actions with the Edit Schedule dialog

After setting up a schedule for your report and clicking Next, you come to the Enable Actions step of the Edit Schedule dialog. Here you can set up the action that Splunk Enterprise performs each time it runs the report.

6.0 edit rpt schedule2.png

Splunk Enterprise provides two actions for scheduled reports. Each time the report runs, Splunk Enterprise can:

  • Send emails with the results to a set of recipients each time the report is run. These emails can provide the report results in text format, or they can include the report results as CSV or PDF attachments.
  • Run a script that does something with the report results.

Send emails to a set of stakeholders

If you want Splunk Enterprise to contact stakeholders when the alert is triggered, select Send Email.

For the Email 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 Enterprise will replace $name$ with the saved report name.

Splunk Enterprise provides additional variables that you can use in the Subject field. They include, but are not limited to, the following:

Variable Description
$search$ The search that triggered the alert.
$alert.severity$ The severity level of the alert.
$results.count$ The number of results returned by the search.
$results.url$ A Splunk Web URL where users can view the results.
$results.file$ The absolute path to the results file.
$search_id$ The search ID of the job that triggered the alert.

You can find a full list of available variables in the savedsearches.conf specification file in the Admin Manual. All attributes displayed in savedsearches.conf can be used as variables in the Subject field of an email.

Include results in scheduled report emails

If you're setting up a scheduled report 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 report. This works best when the report returns a single value, a truncated list (such as the result of a report that returns only the top 20 matching results), a table, or a chart visualization.

If this is so, click Include results and select either text, CSV, or PDF.

  • Inline - Have Splunk Enterprise deliiver the report results as text in the body of the alert email.
  • CSV - Have Splunk Enterprise convert the results to .CSV format and attach the file to the alert notification email.
  • PDF - Have Splunk Enterprise deliver the report results in the form of a PDF attachment. (You no longer need the PDF Report Server App to generate report result PDFs. The functionality is now built into Splunk Enterprise.)

The result inclusion method is controlled via alert_actions.conf (at a global level) or savedsearches.conf (at an individual report level). For more information see "Configure alerts in savedsearches.conf" in the Alerting Manual.

Note: For your email notifications to work correctly, you first need to have your email alert settings configured in Settings. See the "Configure email alert settings in Settings" subtopic, below.

For more information about using Splunk's integrated PDF generation functionality, see "Generate PDFs of your reports and dashboards" in this manual.

The following is an example of what a scheduled report email looks like when results are delivered as text in the body of the email:

Alert-email-example.png

Configure email alert settings in Settings

Scheduled report email delivery will not work if the email alert settings in Settings are not configured, or are configured incorrectly. You can define these settings at Settings > System settings > Email alert settings.

On the Email alert settings page, you can define the Mail Server Settings (the mail host, email security type, username, password, and so on) and the Email Format (link hostname, 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.

Splunk Enterprise's integrated PDF functionality no longer requires the PDF Report Server App to generate PDFs of report results. You can print report 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 "Generate PDFs of your reports and dashboards" in this 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 Settings, 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 Enterprise implementation in alert_actions.conf, and you can configure them at the individual report level in savedsearches.conf. For more information about .conf file management of saved reports and alert settings see "Configure alerts in savedsearches.conf" in this manual.

Run a script

If you want Splunk Enterprise to run a script when each time the report runs on its schedule, select Run a script under Enable actions and enter the file name of the script that you want it to execute.

For example, you could have a scheduled report that runs a script that calls an API, which in turn sends the results of the report to another system.

Note: For security reasons, all scripts must be placed in $SPLUNK_HOME/bin/scripts or $SPLUNK_HOME/etc/<AppName>/bin/scripts. This is where Splunk Enterprise will look for any script listed in a scheduled report definition.

For detailed instruction on scheduled report 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 report scripts, check out this excellent topic on troubleshooting alert scripts on the Splunk Community Wiki.

Schedule reports in Settings

In Settings you can arrange to have saved reports behave like reports that have been scheduled with the Edit Schedule dialog.

1. Navigate to Settings > Searches and reports, and select Schedule this search to open up the scheduling and alerting options for the report.

2. Set up the report 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 the report behave like a report that has been scheduled with the Edit Schedule dialog, set the alert Condition to Always. This ensures that the alert actions you define are performed each time Splunk Enterprise runs the report.

4. Make sure Alert mode is set to Once per search. There's no need to activate Throttling for scheduled reports, and the Expiration and Severity settings are unimportant for scheduled reports.

5. Set up the alert actions required for your scheduled report. For full details on all of the available alert action options, see "Set up alert actions", in this manual. Most scheduled reports only take advantage of the Send email and Run a script actions.

6. For the Summary Indexing setting, see the "Enable summary indexing" subtopic below. It is only required if you intend for this scheduled report 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 report via Settings > 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 reports on a regular basis.

With summary indexing, you base a scheduled report on a report that computes sufficient statistics (a summary) for events covering a slice of time. The report is set up so that each time it runs on its schedule, its results are saved into a summary index that you designate. You can then run reports 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 reports that already benefit from report acceleration. For more information and a distinction between these two methods of speeding up slow running reports, see "About report acceleration and summary indexing" in the Knowledge Manager manual.

To set up summary indexing for an a scheduled report, go to Setting > Searches and reports, open the detail page for the report 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 report 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 transforming 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.

Enable others to access a scheduled report

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 set or change the report permissions so it is available to other users of your Splunk Enterprise implementation, either at an app or global level.

You can set permissions when you first save a search or pivot as a report. You can edit an existing report's permissions when you:

  • Navigate to the Reports listing page, locate the report in question, and either:
    • Expand the report's row, and click Edit for its Permissions, or
    • Click Edit and select Edit Permissions.
  • Navigate to the reports viewing page and either:
    • Click Edit and select Edit Permissions.
    • Click More Info and click Edit for the permissions status.
  • Navigate to Settings > Searches and reports and click Permissions for the report in question.

For more information about managing permissions for Splunk Enterprise knowledge objects (such as reports) read "Manage knowledge object permissions" in the Knowledge Manager Manual.

Manage the priority of concurrently scheduled reports

Depending on how you have your Splunk Enterprise implementation set up, you may only be able to run one scheduled report at a time. Under this restriction, when you schedule multiple reports to run at approximately the same time,the Splunk Enterprise search scheduler works to ensure that all of your scheduled reports 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 reports 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 reports through edits to savedsearches.conf. For more information about this feature, see "Configure the priority of scheduled reports" in this manual.

PREVIOUS
Accelerate reports
  NEXT
Configure the priority of scheduled reports

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters