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 trigger an action each time it runs. There are two actions available for scheduled reports: Send email and Run a script.

You can schedule reports and define their report actions two ways:

  • You can use the Edit Schedule dialog
  • You can open a report in Settings and define a schedule for it

Restrictions on report scheduling

You can only create scheduled reports if your role includes the schedule_search capability. See "About defining roles with capabilities," in the Securing Splunk Enterprise Manual.

Open the Edit Schedule dialog

There are three ways to open the Edit Schedule dialog.

The Edit Schedule dialog is divided into two parts. In the first part you schedule a report. In the second part, you define the scheduled report actions.

To create or update a scheduled report in Settings, navigate to Settings > Searches, reports, and alerts. See "Schedule reports in Settings", in this topic.

After saving a search as a report

Use this method to schedule a report right after you create it.

  1. Create a search and run it.
  2. Save the search as a report.

    Do not enable a time range picker. Scheduled reports cannot include time range pickers, because they always run on a set schedule.

    See Create and edit reports, in this manual.

  3. In the Your Report Has Been Created dialog, click Schedule.

From the Reports listing page

Use this method to schedule an existing report.

  1. Navigate to the reports listing page.
  2. Locate a report that you want to schedule, and expand it.
  3. On the Schedule line, click Edit.

Alternate method:

  1. Navigate to the reports listing page.
  2. Locate the report that you want to schedule
  3. Click Edit for that report and select Edit Schedule.

Schedule a report with the Edit Schedule dialog

This procedure shows you how to use the Edit Schedule dialog to define a report schedule for a new or existing report.

Note: When you schedule an existing report, be aware that:

  • Scheduled reports cannot include time range pickers. When you schedule a report that has a time range picker, Splunk software removes the picker from the report.
  • Scheduled reports can only run as owner. When you schedule a report that has been shared to run as user, Splunk software updates that setting so it runs as owner. See Determine whether to run reports as the report owner or report user in this manual.
  1. Open the Edit Schedule dialog for a new or existing report by following one of the procedures outlined in the preceding section.
  2. Select Schedule Report.
  3. Enter the Schedule and Time range.

    If you select Run on Cron Schedule, see "Specify a cron schedule for report delivery", in this topic.

    Time range is the time range for which the report collects data. It defaults to the time range that has been set for the report. Specify a new time range to override the default.

  4. (Optional) Select a Schedule Window for the report to run within.

    Em schedule window.png

    Only give the report a schedule window if:
    • The report does not always have to start at its scheduled run time.
    • You think the report may cause other reports to miss their scheduled runs. This can happen due to resource constraints such as the maximum concurrent report limit.


    The schedule window specifies how long the report scheduler can defer a report and cause it to yield to higher-priority reports during resource-constrained times.

    The schedule window opens when the report is scheduled to run. Initially it allows other reports with higher priority to run before it. As the schedule window approaches its close, the chance that the report will run increases. Reports that are slow to complete and which are run on an infrequent basis are often good candidates for a schedule window.

    The window width is defined in terms of minutes. It can be any number of minutes from 0 to 44,640 (the number of minutes in a 31 day month). The window width should not exceed the period of the report. For example, if you have a scheduled report that runs every hour, you would not want to define a schedule window for that report that is two hours wide, because this could cause the report to miss scheduled runs.

  5. Click Next to set up an action for a scheduled report.

    See Set up an action for a scheduled report," in this topic.

For more information about the Schedule Window setting, the methods that the report scheduler uses to reduce incidents of skipped scheduled report runs, and the maximum concurrent report limit, see "Configure the priority of scheduled reports" in this manual.

To create or update a report schedule in Settings, click Searches, reports, and alerts to go to the page with that name. Open the detail page for a new or existing report. See "Schedule reports in Settings", in this topic.

Specify a cron schedule for report delivery

You can use standard cron notation to define a custom delivery schedule. When you select the Cron option, a field appears in which you can enter the cron schedule.

Note: Splunk software uses five parameters for cron notation, not six. Splunk software does not use the sixth parameter for year, common in other forms of cron notation.

The following parameters:

(* * * * *)

correspond to:

minute hour day month day-of-week.

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.

Define actions for your scheduled report with the Edit Schedule dialog

A scheduled report can perform the following actions each time it runs:

  • Send emails with the results to a set of recipients. 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 accesses the report results. Your script can post the results of the report to a external system for further processing or archiving on a regular schedule.

Note: You can use these scheduled report actions to export search results. For a summary of other search result export methods, see "Export search results" in the Search Manual.

Define a Send Email action

This procedure shows you how to use the Edit Schedule dialog to set up a Send Email action for your scheduled report.

You cannot set up this kind of action without first configuring email notification for your Splunk deployment in Settings. See Email notification action in the Alerting Manual.

1. Enter the Edit Schedule dialog, define the report schedule if necessary, and click Next.

See "Schedule a report," in this topic.

2. Select Send Email to create an email action.

The Edit Email Options dialog opens.

Em edit report schedule-email action.png

3. Provide a comma-separated list of To email recipients.

4. (Optional) Provide a comma-separated list of CC, and BCC email recipients.

Click Show CC and BCC to see the CC and BCC fields.

5. Set the email Priority.

Enforcement of priority depends on your email client.

6. (Optional) Provide the email Subject and Message.

You can use tokens in email subject and message text to provide a wide variety of information to your users. See "Use tokens in scheduled report email subjects and bodies" in this topic.

7. (Optional) For Include, select options to include or attach information about the search and its results.

In the email, you can include:
  • A link to the related report.
  • A link to the results of the run of the report that the email represents.
  • The search string for the scheduled report.
  • The results of the report run, in the form of an inline table, CSV file, or raw event list.
You can also attach the results of the report run in the form of a CSV file or a PDF. See "Include results in scheduled report emails" in this topic.

8. (Optional) Change the email Type to Plain Text.

Type is set to HTML & Plain Text by default.

9. Click Save to save your email action settings.

See Run a script in this topic for details on configuring scripts.

If you have Splunk Enterprise, you can also configure report email actions in the alert_actions.conf or savedsearches.conf configuration files. Use alert_actions.conf to configure global properties. Use savedsearches.conf to configure individual reports. See "Configure alerts in savedsearches.conf" in the Alerting Manual.

For more information about generating and emailing PDF files of report results, see "Generate PDFs of your reports and dashboards" in this manual.

The following figure shows a scheduled report email with results delivered as text in the body of the email:

6.1 report schedule email.png

Define a Run a Script action

You can specify a script that runs each time a scheduled report runs. This procedure shows you how to use the Edit Schedule dialog to set up a Run a Script action for your scheduled report.

1. Enter the Edit Schedule dialog, define the report schedule if necessary, and click Next.

See "Schedule a report," in this topic.

2. Select Run a Script to create an email action.

The Filename field appears.

3. Provide the Filename of your script.

The script must be at the following location in your Splunk Enterprise instance: $SPLUNK_HOME/bin/scripts

4. Click Save to save your script action settings.

See "Run a Script action example," in this topic.

Use tokens in scheduled report email subjects and bodies

A token is a type of variable that represents data generated by a search job. Splunk Enterprise provides various tokens that you can use to include information generated by a search in the fields of an email. For scheduled report delivery, you can use tokens in the following fields of an email:

  • Subject
  • Message
  • Footer

Access the value of a token with the following syntax:

$<token-name>$

For example, place the following token in the subject field of a scheduled report delivery to reference the app containing the report.

Search results from $app$

Tokens available for email notifications

This section lists common tokens you can use in scheduled email delivery of reports. There are four categories of tokens that access data generated from a search. The context for using the tokens differ.

The following table lists all categories of tokens. Tokens from all categories are available for scheduling report delivery.

Category Description Context
Search metadata Information about the search. Scheduled PDF delivery of dashboards
Alert actions from search
Scheduled reports
Server information Information about the Splunk Enterprise server Scheduled PDF delivery of dashboards
Alert actions from search
Scheduled reports
Search results Access results of a search Alert actions from search
Scheduled reports
Job information Data specific to a search job Alert actions from search
Scheduled reports

In addition to the common tokens listed in this topic, the savedsearches.conf and alert_actions.conf files list attributes whose values are available from tokens. To access these additional attribute values, place the attribute between the $ token delimiters.

Tokens that access search metadata

Common tokens that access information about a search. These tokens are available from the following contexts:

  • Alert actions
  • Scheduled reports
  • Scheduled PDF delivery of dashboards

Here are some of the common tokens available.

Token Description
$action.email.hostname$ Hostname of the email server.
$action.email.priority$ Priority of the search.
$app$ Name of the app containing the search.
$cron_schedule$ Cron schedule for the app.
$description$ Description of the search.
$name$ Name of the search.
$next_scheduled_time$ The next time the search runs.
$owner$ Owner of the search.
$results_link$ (Alert actions and scheduled reports only) Link to the search results.
$search$ The actual search.
$trigger_date$ (Alert actions only) The date that triggers the alert.
$trigger_time$ (Alert actions only) The scheduled time the alert runs.
$type$ Indicates if the search is from an alert, report, view, or the search command.
$view_link$ Link to view the saved report.
$alert.severity$ Severity level of the alert.
$alert.expires$ Time the alert expires.

Tokens available from results

From results, you use the result.<fieldname> token to access the first value of a specified field in search results. This token is available from the following contexts:

  • Alert actions
  • Scheduled reports
Token Description
$result.fieldname$ Returns the first value for the specified field name from the first result in the search. The field name must be present in the search.

Tokens that access job information

Common tokens that access data specific to a search job, such as the search ID or messages generated by the search job. These tokens are available from the following contexts:

  • Alert actions
  • Scheduled reports
Token Description
$job.earliestTime$ Initial time a search job starts.
$job.eventSearch$ Subset of the search that contains the part of the search before any transforming commands.
$job.latestTime$ Latest time recorded for the search job.
$job.messages$ List of error and debug messages generated by the search job.
$job.resultCount$ Number of results returned by the search job.
$job.runDuration$ Time, in seconds, that the search took to complete.
$job.sid$ Search ID.
$job.label$ Name given to the search job.

Tokens available from server

Common tokens that provide details about your Splunk deployment. These tokens are available for the scheduled PDF delivery of dashboards.

The following table lists some of the common tokens that are available.

Token Description
$server.build$ Build number of the Splunk software.
$server.serverName$ Server name hosting the Splunk deployment.
$server.version$ Version number of the Splunk deployment.

Deprecated email notification tokens

The following tokens from prior releases of Splunk software are deprecated.

Token Description
$results.count$ (Deprecated) Use $job.resultCount$.
$results.url$ (Deprecated) Use $results_link$.
$results.file$ (Deprecated) No equivalent available.
$search_id$ (Deprecated) Use $job.id$.

Run a Script action example

You can set up a Run a Script action that sends results of the report to an external system each time it runs. It does this by running a script that calls an API that sends the report results to the external system.

For security reasons, place all scripts in either of the following locations of your Splunk Enterprise instance:

$SPLUNK_HOME/bin/scripts

$SPLUNK_HOME/etc/<AppName>/bin/scripts

You can also configure running a scheduled report script with a shell script or batch file. Make this configuration in the savedsearches.conf configuration file. 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.

For more information about the Run a script alert action, see "Set up alert actions" in the Alerting Manual.

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.

2. Open up the detail page for a report.

3. Select Schedule this search to open up the scheduling and alerting options for the report.

4. 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 "Specify a cron schedule for report delivery," in this topic.

5. (Optional) Provide a Schedule Window for reports that do not need to run at their scheduled run time, when there are many concurrently scheduled reports.

The report will run at some point within this window. In the meantime, other reports get run ahead of it. See "Schedule a report," in this topic.

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

7. Set Alert mode 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.

8. (Optional) Set up the alert actions required for your scheduled report.

See "Define actions for your scheduled report," in this topic.
Do not define alert actions for a scheduled real-time report. See "Create scheduled real-time reports for dashboards," in this topic.

9. (Optional) Enable summary indexing with the Summary Indexing setting.

This setting is only required if you intend for this scheduled report to populate a summary index. See "Enable summary indexing".

10. Click Save to save your changes.

Create scheduled real-time reports for dashboards

Use scheduled real-time reports when you want your dashboards to display incoming data in real time. You can create scheduled real-time reports in Settings.

When you use unscheduled real-time reports for dashboard panels, they relaunch each time the dashboard is loaded by a user. If several users load the same dashboard you can quickly reach the real-time concurrent search limit for your Splunk implementation. After you reach this limit, you cannot launch more real-time reports.

You can manage this by backing dashboard panels with scheduled real-time searches. Scheduled real-time reports begin running when you create them. When a user loads a dashboard with panels that use scheduled real-time searches, those panels just display the results of the real-time reports already in progress. New real-time reports are not launched.

See Add panels from a report in Dashboards and Visualizations.

Enable summary indexing

Summary indexing is an action that you can configure for any scheduled report via Settings > Searches, reports, and alerts. 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:

1. Navigate to Setting > Searches, reports, and alerts.

2. Open the detail page for the report that will populate the summary index.

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

4. Click Save to save your change.

Note: 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 Splunk users at an app or global level. See Set report permissions, in this manual.

For more information about managing permissions for Splunk knowledge objects, read "Manage knowledge object permissions" in the Knowledge Manager Manual.

Manage the priority of concurrently scheduled reports

Depending on how you configure your Splunk deployment, you might be able to run only one scheduled report at a time. Under this restriction, when you schedule multiple reports to run at approximately the same time, the Splunk 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
Embed scheduled reports

This documentation applies to the following versions of Splunk® Enterprise: 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.4.10, 6.4.11


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