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.

Use Send email to 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.

Use Run a script to run scripts that post the results of the report to a external system for further processing or archiving on a regular schedule.

You can use these scheduled report actions to export search results from Splunk Enterprise. For a summary of other search result export methods, see "Export search results" in the Search 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 Enterprise 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 alerts. 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, reports, and alerts 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.

Set up an action for a scheduled report

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

  • 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. Before you can send an email notification, configure the email notification settings in Settings. See Configure email notification settings in the Alerting Manual.
  • Run a script that accesses the report results. See Run a script in this manual. The script must be at the following location in your Splunk Enterprise instance:

$SPLUNK_HOME/bin/scripts

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

You configure actions for scheduled reports from the Reports Page or from a specific report. The following procedure shows how to schedule delivery of a report and run a script on the same schedule. This procedure is from the context of a specific report. However, the procedure is the same from the context of the Reports Page.

1. Select Edit > Edit schedule.

2. Click Schedule Report. The Schedule dialog opens. 6.0 edit rpt schedule1.png 3. Select a schedule.

4.The time range defaults to the time range for the report.

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

5. Click Next.

6. Select Send Email.

The Edit Email Options dialog opens.

6.1 edit rpt schedule2.png

7. Specify the following email options.

  • To, CC, and BCC email recipients: Provide a comma-separated list of email recipients.
  • Priority: Enforcement of priority depends on your email client.
  • Subject
  • Message
  • You can optionally include the following items:

    Information about the search
      Link to the report
      Search string
      Results as a CSV attachment

    Information about search results
      Link to results
      Inline table of results
      Results as a PDF attachment

8. Select Run a Script.

Enable this option and enter the name of the script to run on the specified schedule.

9. Click Save.

See "Use tokens in scheduled delivery of reports" in this topic to learn how to customize your scheduled report emails.

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

Use tokens in scheduled delivery of reports

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

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.

Include results in scheduled report emails

There are various ways you can include results in scheduled report emails.

  • Inline
    Deliver the report results as text in the body of the email.
  • CSV attachment
    Attach a results file in CSV format to the email. When you specify this option, Splunk Enterprise converts the results to CSV format for you.
  • PDF
    Attach a PDF file to the email. When you specify this option, Splunk Enterprise converts the results to PDF for you.

You can specify how to include results when configuring the scheduled report in Splunk Web, as described in Schedule a report for email delivery and to run a script in this manual.

You can also configure how to include results 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, 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

Run a script

You can configure Splunk Enterprise to run a script each time a scheduled report runs. For example, you can schedule report to runs a script that calls an API, which in turn sends the results of the report to an external system. Schedule a report for email delivery and to run a script in this manual describes how to configure a scheduled report to run a script.

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, 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. 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 the Alerting 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
Embed scheduled reports

This documentation applies to the following versions of Splunk® Enterprise: 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15


Comments

Re: "The Expiration and Severity settings are unimportant for scheduled reports."

I think this is not necessarily true any longer, right? In playing around with the Embed capability, which requires scheduling a report, it seems that the report becomes unavailable if the report has not been rerun in more days than is defined by the Expiration.

For example, if my report is set to run monthly and my expiration is set to 7 days, then the iFrame link to the embedded report will fail with the message "Report not available" from days 7 until day 29, 31, or 32 (depending on the month), when the report is run next.

Furthermore, if embedding is disabled to make a change to the scheduling of the report and then embedding is enabled again, the old link will continue to work only until the expiration has passed.

Kmcarrol
July 2, 2015

Hi there Tweaktubbie--

Splunk does not perform any white- or blacklisting of the recipient address or domain, either in our email address validation or in the sendemail command. This is something that you will need to configure on your email host.

Mness, Splunker
June 19, 2015

Where/how can you filter or blacklist/whitelist to which domain(s) mails can be send? It's nasty if due to a typo sensitive information gets out of your company?

Tweaktubbie
June 16, 2015

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