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.

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 Enterprise Manual.

Define a report schedule in Splunk Web

In Splunk Web, you can schedule reports:

  • By using the Edit Schedule dialog.
  • By editing the detail page for the report in Settings.

There are three ways to open the Edit Schedule dialog.

  • After you save a search as a report, you are brought to the Your Report Has Been Created dialog. Click Schedule.
  • Navigate to the Reports listing page, expand an existing report, and click Edit for the Schedule line.
  • Navigate to the Reports listing page, click Edit for an existing report, and select Edit Schedule.

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.

Schedule a report

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

1. Run a search.

2. Click Save As and select Report.

3. Enter a report Title and Description and save your report.

See "Create and edit reports", in this manual, for details on report creation.

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

This opens the Edit Schedule dialog.
If you want to edit the schedule for an existing report you can get to the Edit Schedule dialog from the Reports listing page. On the Reports listing page, expand a report that you want to schedule and click Edit next to the word "Schedule". Or locate the report that you want to schedule, click Edit and select Edit Schedule.
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.

5. Select Schedule Report.

The report scheduling controls appear.

6. Enter the Schedule and Time range.

If you select Run on Cron Schedule, see "Specify a cron schedule for report delivery", in this topic.
The time range defaults to the time range for the report. Specify a new time range to override the default. This is the time range for which the report collects data.

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

Only give the report a schedule window if the report does not have to start at its scheduled run time and if 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.

Em schedule window.png

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

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 Enterprise uses five parameters for cron notation, not six. Splunk Enterprise 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

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

  • 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 from the Splunk platform. 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 platform implementation 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 [[Documentation:Splunk:Report:Schedulereports#Include_results_in_scheduled_report_emails|"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.

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 using Splunk's integrated PDF generation functionality (for attached 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

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

You can configure Splunk Enterprise to run a script each time a scheduled report runs.

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 available from your Splunk Enterprise server. 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 Enterprise instance.
$server.serverName$ Server name hosting the Splunk Enterprise instance.
$server.version$ Version number of the Splunk Enterprise instance.

Deprecated email notification tokens

The following tokens from prior releases of Splunk Enterprise 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 real-time scheduled 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 real-time scheduled reports for dashboards

When you use non-scheduled real-time searches for dashboard panels, they relaunch each time a user loads the dashboard. This can lead to a situation where concurrent search limits for real-time searches hit their limit.

In Settings you can create real-time scheduled reports--real-time reports that are scheduled to alert "always"--that do not have alert actions. This type of scheduled report can be useful for backing saved search dashboard panels. This sets up a dashboard panel that is backed by a single real-time search that constantly runs, even when the dashboard is being simultaneously viewed by multiple users.

If you want to back a dashboard panel with a scheduled real-time report, the panel must reference the report by name.

If you add an alert action to a scheduled real-time report it becomes an alert. You may need to add throttling rules to the alert if its real-time search receives a lot of results in a short amount of time. See "Getting started with alerts" in the Alerting Manual.

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 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
Embed scheduled reports

This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14


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