Splunk Enterprise 6.0.1 Reporting Manual
Generated: 12/24/2013 11:18 am
Copyright (c) 2013 Splunk Inc. All Rights Reserved
Table of Contents
Reporting Overview (1)
About reports (1)
Report Management (2)
Create and edit reports (2)
Accelerate reports (14)
Schedule reports (17)
Configure the priority of scheduled reports (26)
Generate PDFs of your reports and dashboards (30)
i
Reporting Overview
About reports
In Splunk, reports are created whenever you save a search or a pivot for later reuse. Once a report is created, there's a lot you can do with it.
Because reports can be created from either side of the Splunk Enterprise fence, we've created a manual to isolate all of the functionality related to reports and reporting in one place. In this manual, you'll find out how to:
?
Manually create and edit reports. Add reports to the Report listing page
from either Search or Pivot. Configure a report manually in
savedsearches.conf. Convert a dashboard panel to a report. Share your
report with others by changing its permissions.
?
Accelerate slow-completing reports, either during the report creation
process, or at a later point.
?
Set up scheduled reports--reports that run on a regular interval and which trigger an alert action (such as the sending of an email with search results) each time they run. Scheduled reports are also used for summary
indexing.
?
Configure the priority of scheduled reports. Learn how the Report
Scheduler manages multiple concurrent reports and learn how to
configure your Report Scheduler options.
?
Understand how Splunk Enterprise generates PDFs of reports,
dashboards, searches, and pivots. Enable non-latin fonts in PDFs.
Configure PDF generation via .conf files. Review the exceptions to this
functionality. Learn how to install the PDF Report Server App if you prefer that method of app generation.
1
Report Management
Create and edit reports
When you create a search or a pivot that you would like to run again or share with others, you can save it as a report. This means that you can create reports from both the Search and the Pivot sides of Splunk Enterprise.
Once you create a report you can:
?
Run the report on an ad-hoc basis to review the results it returns on the report viewing page. You can get to the viewing page for a report by
clicking the report's name on the Reports listing page.
Open the report and edit it so that it returns different data or displays its ?
data in a different manner. Your report will open in either Pivot or Search, depending on how it was created.
This topic explains how you can create and edit reports.
In addition, if your permissions enable you to do so, you can:
?
Change the report permissions to share it with other Splunk Enterprise users.
Schedule the report so that it runs on a regular interval. Scheduled ?
reports can be set up to perform actions each time they're run, such as
sending the results of each report run to a set of stakeholders.
?
Accelerate slow-completing reports built in Search.
?
Add the report to a dashboard as a dashboard panel.
For more information about scheduling reports, see "Schedule reports," in this manual.
For more information about accelerating reports, see "Accelerate reports," in this manual.
For more information about adding reports to dashboards as dashboard panels see "Add a search, report, or pivot to a dashboard" in the Splunk Data Visualizations Manual.
For more information about managing report permissions see "Manage knowledge object permissions," in the Knowledge Manager Manual.
2
Note: Permissions for reports built via Pivot must match those of the data model that was used to construct them. See "Save a search or report as a pivot," below, for more information.
Manually create a report
You can create reports via Splunk Web four ways:
?
From Search, by saving a search as a report.
?
From Pivot, by saving a pivot as a report.
By navigating to Settings > Searches and reports and clicking New to ?
add a new report.
?
From a dashboard, by converting an inline-search-powered dashboard
panel to a report.
See the following subsections for more information about these report creation methods.
At minimum, a report definition includes the search string and the time range associated with the search (expressed in terms of relative time modifiers). You also have to give the report a name so you can identify it in the Reports listing page and the Searches and reports page in Settings.
Save a search or pivot as a report
When you design a search or pivot that returns useful results, you can save it as a report. After you run a search or create a pivot, just click Save As and select Report to open the Save As Report dialog. The report will retain any formatting that you set up for the original search, including chart visualizations and event list display options.
Note: You can only save a search as a report when it is running, paused, finalized, or completed.
Here you can provide a unique title for the report and an optional description. You can also determine whether the report will include a time range picker.
3
Inclusion of a time range picker enables users who do not have write permissions for the report to rerun it over a different time range without actually editing the report.
If you do not provide a time range picker, the report will always run over the same time range, and the only way to change this will be for someone with edit permissions for the report to open the report in Search, change the time range, and save that edit.
Clicking Save opens the Your Report Has Been Created dialog. From here you can:
?
View (run) the report and see results it returns on the report viewing page ?
Continue editing the report
?
Add the report to a dashboard
?
Edit the report's permissions
?
Set up the report to run on a schedule
?
Accelerate the report
You can also just close the dialog box if you'd rather do none of these things and continue searching. Just click the "x" in the upper right-hand corner.
Note: Permissions for reports built via Pivot must match those of the data model that was used to construct them. For example, say your Splunk Enterprise instance has two apps: Search and Security. While in the context of the Security app, you use that app's External Threats data model to create a pivot-based report titled "Top Firewall Attacks by IP." The External Threats data model has permissions that are scoped to the Security app, nothing more.
When you first create the report, its permissions only allow you to see and update it. You want everyone who uses this Splunk Enterprise implementation to see the "Top Firewall Attacks by IP" report (regardless of app context), so you change its permissions to Global. Now, when you switch your app context to the Search app, you might expect to be able to access "Top Firewall Attacks by IP"
4
from the Search app.
But you won't be able to view it. This is because the report can't be built without the External Threats data model, and that data model's permissions are still scoped to the Security app. You need to share External Threats globally in order to access and run the "Top Firewall Threats by IP" report from the Search app.
Create a new report in Settings
When you want to create a report, in general the easiest thing to do is run the search or pivot and then save it as a report, as described above. This method enables you to test the search before you save it.
However, you can also manually create new reports in the Settings section of Splunk Web. To do this, navigate to Settings > Searches and reports and click New to define and add a new report. When you define a report in Settings, you'll set it up as a "saved search." But this search will appear as a report on the Reports listing page when you're done (or on the Alerts listing page, if you configure it as an alert).
At minimum you must provide a Destination app for the search (Splunk Enterprise will use your current app context by default), the Search name, and the actual search string (in the Search field). You should also provide a Start time and End time for the search, unless you want the search to run over all time, in which case it's fine to leave those fields blank. Use relative time modifiers to express the start and end times.
You can optionally enter a search description that explains what the search does and/or how it should be used.
5
The Acceleration controls can enable a search that is normally slow-completing to complete much faster on future runs. To set up report acceleration for a search you select Accelerate this search and then choose an appropriate Summary range. You can only select Accelerate this search if your permissions enable you to do so.
In addition, only specific kinds of searches qualify for report acceleration. If your search string does not qualify for report acceleration you will receive an error telling you that the search cannot be accelerated when you try to save it. For more information about report acceleration, see "Accelerate reports", in this manual. For detailed examples of the kinds of searches that qualify for report acceleration, see "Manage report acceleration" in the Knowledge Manager Manual.
You can optionally select Schedule this search if your permissions enable you to do so. This opens up a variety of fields that enable you to set up the search as a scheduled report, define triggering conditions for an alert based on the search, and set up alerting actions (what happens when the alert is triggered). In other words, you can use it to turn your search into an alert or a scheduled report.
For more information about creating alerts see "About alerts," in the Alerting Manual. This topic also has information about alerting options that are only
6
available through the Searches and reports detail page in Manager, such as the capability to set expiration times for alert records in the Alert Manager or the "add to RSS feed" alerting condition.
For more information about defining scheduled reports (reports that run on a schedule and which send search results via email or launch a script each time they run), see "Schedule reports" in this manual.
The Searches and reports detail page in Manager is also the only place in the Splunk Web UI where you can enable summary indexing for a saved search (you can also configure summary indexing for a search by modifying savedsearches.conf). For more information about summary indexing, see the topic "Enable summary indexing for a search," in the Knowledge Manager Manual.
You can edit and update searches listed on the Searches and reports page if you have "write" permissions for them. For more information about permissions, see "Manage knowledge object permissions" in the Knowledge Manager Manual.
Configure a report in savedsearches.conf
When you save a report via Splunk Web or Settings, Splunk Enterprise automatically adds a configuration stanza for that report to savedsearches.conf. The UI validates your changes, and you don't have to reboot the system to apply reports created via UI methods. But if you prefer to work with reports directly through configuration files, you certainly can.
For more information about configuring reports and alerts in savedsearches.conf, see the spec file for savedsearches.conf and the "Configure alerts in savedsearches.conf" topic in the Alerting Manual.
Convert a dashboard panel to a report
You may want to convert dashboard panels that are "powered by" inline searches to reports, so that they can have some of the advantages that
report-based panels have over inline-search-powered panels, such as faster loading times due to report acceleration.
When you save a new search or a pivot as a dashboard panel, Splunk Enterprise creates a dashboard panel that is "powered by" an inline search. This means that the search that drives the dashboard is "in" the dashboard; it is not connected a report or other external object. The benefit of this is that you can edit the search that powers the dashboard or change its visualization type without leaving the
7
dashboard.
On the other hand, when you open an existing report in Search or Pivot (see "Edit a report," below) and then save that search or pivot as a dashboard panel, you'll have a choice of basing the panel either on an inline search or on the report that you're editing. If you choose to base the panel on the report, the panel can take on the formatting of the report as well as its acceleration, scheduling, and permissions settings.
Note: Dashboard panels based on reports can have different formatting than the reports they're associated with. See the subsection "To have a dashboard panel take on the formatting of its affiliated report," below, for more information.
When you edit a dashboard panel that is powered by an inline search, you have the option of converting it to a report. Doing so creates a new report based on the dashboard. You can view and edit this report via the Reports listing page (or the Searches and Reports page in Settings). The dashboard panel will remain, but you will no longer be able to edit the search that powers it from within the dashboard. On the other hand, you'll now be able to define acceleration, scheduling, and permissions settings for the report that now powers the panel. Note: If the dashboard panel derives from a pivot, you'll also lose the ability to change the panel visualization type via the dashboard when you convert it to a report.
To convert a dashboard panel to a report
1. Click Edit for the dashboard in question. Icons will appear at the upper right corner of each panel in the dashboard.
2. Click the Panel Properties icon for a panel based on a search or pivot and select Convert to Report. The Panel Properties icon is the leftmost of the three panel editing icons mentioned in the previous step. Its icon indicates the panel's document type--a magnifying glass for a panel based on a search, pivoting arrows for a pivot, or a sheet of paper for a search- or pivot-based report.
8
3. The Save panel as report dialog appears. Here you have an opportunity to provide a different Title and Description for the report than the title and description associated with the panel.
4. Click Save when you're done. Splunk Enterprise will add the report to the Reports listing page.
To have a dashboard panel take on the formatting of its affiliated report
If you convert a dashboard panel to a report and then edit the report so it uses a different visualization or has different visualization formatting, your changes will not automatically be reflected in the affiliated panel. To sync up the dashboard panel with the updated report, follow these steps:
1. Click Edit for the dashboard that contains the panel you'd like to update.
2. Click the Panel Properties icon for the panel you'd like to update. In the dropdown list that appears, select the panel/report name (the name only appears for panels that have already been converted to a report). Doing this reveals a report info screen, where you can edit various aspects of the report (permissions, acceleration, scheduling, and so on) if your permissions enable you to do so.
3. Click Use Report Formatting on Visualization and then confirm that you want the panel to use the report's formatting. This causes the panel to use the visualization type and formatting that you have defined for the report. For example, if the panel displays a pie chart, but the report associated with the panel was edited to display its data as a column chart, clicking Use Report Formatting on Visualization will cause the panel to display the data in the same
9
manner as the report: a column chart.
Note: In a similar manner, you can cause the panel to use the data and formatting of an entirely different report. Follow the steps above but click Select New Report instead of Use Report Formatting on Visualization. This opens the Select a New Report dialog. Choose a different report, click save, and the panel will update to display data visualized according to the selected report.
Keep in mind that your permissions determine what reports you can choose and edit.
Share your report with others
By default, any report you save is initially private and only available to you. If your permissions allow it, you can change the permissions that belong to the report when you first save it by clicking Permissions on the Your Report Has Been Created dialog. This takes you to the Edit Permissions dialog.
10
Here, depending on your permissions, you have the ability to determine whether a report can be viewed by the users of just one app, or all users in all apps. You furthermore can set read and write permissions by role.
For example, you could make a report "globally" available to everyone that uses your Splunk Enterprise implementation. Or you could narrow the saved search permissions so that only specific roles within the current app can use it. You can also arrange for particular roles or users to have "write" access to the report, enabling them to change its underlying search or pivot, or to update its result display formatting.
You can also define or update permissions for a report by:
?
Going to the Reports listing page, clicking Edit, and selecting
Permissions.
Going to the report viewing page (click on the report name on the Report ?
listing page to do this), clicking Edit, and selecting Edit Permissions. (To get to the report viewing page, click on the report name on the Report
listing page).
?
Navigating to Settings > Searches and reports and clicking
Permissions for the report you'd like to edit.
Note: If you are sharing a pivot-based report, the data model referenced by that report must be shared as well. You will receive an error message if you try to share a pivot-based report that references a private data model. For more information about sharing data models, see "Manage data models" in the Knowledge Manager Manual.
11
Edit a report
You can easily edit an existing report. You can edit a report's definition (its search string, pivot setup, or result formatting). You can also edit its description, permissions, schedule, and acceleration settings.
To edit a report's definition
If you want to edit a report's definition, there are two ways to start, depending on whether you're on the Reports listing page or looking at the report itself.
?
If you're on the Reports listing page, locate the report you want to edit, go to the Actions column, and click Open in Search or Open in Pivot
(you'll see one or the other depending on which tool you used to create
the report).
If you've entered the report to review its results, click Edit and select ?
Open in Search or Open in Pivot (you'll see one or the other depending on which tool you used to create the report).
Edit the definition of a report opened in Search
After you open a report in search, you can change the search string, time range, or report formatting. After you rerun the report, a Save button will be enabled towards the upper right of the report. Click this to save the report. You also have the option of saving your edited search as a new report.
Edit the definition of a report opened in Pivot
After you open a report in Pivot, change the definition of the pivot as you would like. You can add, remove, or redefine filters, split rows, split columns, or column values. You can also change the way the pivot results are formatted (change the visualization type, or fix the way a chart displays). When you are done, click Save at the upper right of the page to save your report. You also have the option of saving your edited pivot as a new report.
To edit a report's description, permissions, schedule, and acceleration settings
You can do this from the Reports listing page, or from the report viewing page. Click Edit and choose:
?
Edit Description to change the name and description of the report.
12
Edit Permissions to change the report permissions. See "Share your
?
report with others" for more information about report permissions.
?
Edit Schedule to schedule the report or change the report schedule if it
already has one. For more information, see "Schedule reports," in this
manual.
?
Edit Acceleration to change the way the report is accelerated. Note: This option is only available for certain kinds of reports created in Search. For more information, see "Accelerate reports," in this manual.
Note: You can't perform these actions if you've opened the report in Search or Pivot. Save the report or return to the Reports listing page if you want to edit these aspects of the report.
Clone a report
Report cloning is a way to quickly create a report that is based on an existing report. You can then edit it so it returns different results. To clone a report either go to the Reports listing page or the report itself, click Edit and select Clone. Note: You can't perform this action if you've opened the report in Search or Pivot. Save the report or return to the Reports listing page if you want to edit these aspects of the report.
Delete a report
You can delete a report from the Reports listing page or the report viewing page. Just click Edit and select Delete. Most roles can only delete reports that they have created. For more information about granting roles the ability to delete reports that they do not own, see "Disable or delete knowledge objects," in the Knowledge Manager Manual.
Note: You can't perform this action if you've opened the report in Search or Pivot. Save the report or return to the Reports listing page if you want to edit these aspects of the report.
Answers
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has around reports.
13
Accelerate reports
If your report has a large number of events and is slow to complete when you run it, you may be able to accelerate it so it completes faster when you run it in the future.
Note: You can't accelerate a report if:
?
It was created via Pivot. Pivot reports are accelerated via data model
acceleration. For more information see "Manage data models" in the
Knowledge Manager Manual.
?
Your permissions do not enable you to accelerate searches. You cannot
accelerate searches if your role does not have the schedule_search
capability.
?
Write permissions for the report have not been granted to your role.
The search that the report is based upon is disqualified for acceleration.
?
For more information, see the subtopic "How reports qualify for report
acceleration," below.
?
The underlying search is using the verbose search mode. If you save the report in verbose mode and then try to accelerate it, you'll be able to do
so, but Splunk Enterprise will automatically change the search mode to
smart or fast. Similarly, you won't be allowed to change the search mode
of a report that has already been accelerated to verbose.
How does Splunk Enterprise accelerate the report? When you accelerate a report, Splunk Enterprise runs a background process that builds a data summary based on the results returned by the report. When you next run the search, Splunk Enterprise runs it against this summary rather than the full index. Because this summary is smaller than the full index and contains precomputed summary data relevant to the search, the search should complete much quicker than it did when you first ran it.
The Edit Acceleration dialog
If your permissions enable you to accelerate a specific report and the report also qualifies for acceleration, you can accelerate it when you create it, or at any point after it has been created.
?
When you save a search as a report, you'll be brought to a Your Report Has Been Created dialog, where you can choose from three optional
"Additional Settings" options. Click the Acceleration option to open the
Edit Acceleration dialog.
14
If you want to accelerate an existing report , navigate to the Reports listing page or the report viewing page.
On the Reports listing page, to accelerate a report (or change its
current acceleration configuration):
Expand the row for a report and click Edit for Acceleration.
? Or click Edit for a selected report and select Edit
Acceleration .
? ? On the report viewing page (which you access by clicking the
report's name on the Reports listing page), to accelerate a report:
Click Edit and select Edit acceleration .
? Or click More info and click Edit next to the acceleration
status.
? ? ? Note: If you try to accelerate a report that does not qualify for acceleration, you will receive an error message informing you that the report cannot be
accelerated.
On the Edit Acceleration dialog, select Accelerate Report to expose Summary Range .
When you accelerate a report, you must choose a Summary Range value such as 7 Days , 3 Months , or All Time . This range represents the approximate span of time that is always covered by the summary at any given moment, once it is built.When the summary is built and you run this report again, to get full acceleration benefits the report must have a time range that fits within this summary range.For more information, see the subtopic "How Summary Range works," below.Note: The data summaries discussed here operate on principles similar to those of traditional summary indexes , but that's where their resemblance ends. The data summaries that are created for report acceleration purposes are not
summary indexes. For more information about report acceleration and summary indexing, and information about why one might prefer one method over the other,see "About report acceleration and summary indexing" in the Knowledge
15
Manager Manual.
How Summary Range works
Summary Range sets the approximate range of time that a report's data summary will cover. When you run the report in the future only the portion of it that falls within that range will benefit from acceleration.
For example, if you choose a Summary Range of 7 Days, you're saying that going forward you want Splunk Enterprise to build and maintain a summary that always covers at least the last seven days. As time passes, Splunk Enterprise will delete data from this summary that is older than seven days while it continues to summarize incoming new data.
Once this summary is built, the report associated with it will complete relatively quickly as long as you run it over time ranges that fall within the past seven days. If you run the report over the past 10 days, it'll get acceleration benefits for the portion of the search that covers the last seven days, but the portion of the search that covers the remaining 3 days will have to run over raw data and will not be accelerated.
The same goes for the other Summary Range settings. Choose 1 Month if you plan to run the report over time ranges that are fall within the last 30 days. Choose 1 Year if you anticipate that you'll need to run the search over time ranges that fall within the past year. Keep in mind that larger summaries take longer for Splunk Enterprise to generate at first and will consume more storage resources.
Note: If you don't want there to be any restrictions over when you can run a search and still get acceleration benefits, choose All Time.
Search mode and report acceleration
Report acceleration only works for reports that have Search Mode set to Smart or Fast. If you select the Verbose search mode for a report that has been accelerated, it will run as slow as it would if it were not accelerated at all. For more information about the Search Mode settings, see "Set search mode to adjust your search experience" in the Search Manual.
How reports qualify for report acceleration
To qualify for acceleration, a report must have an underlying search that uses a transforming command (such as chart, timechart, stats, and top). In addition,
16
any search commands before the first transforming command in the search string need to be streaming commands. (Nonstreaming commands are allowed after the first transforming command.)
We provide examples of qualifying and non-qualifying searches in "Manage report acceleration," in the Knowledge Manager Manual.
Manage your report acceleration summaries
Splunk Enterprise provides a Manager page for this feature at Manager > Report Acceleration Summaries. On this page you can review the report summaries to which you have access. You can see the reports that apply to them, view their build progress, verify their consistency, rebuild them when they are damaged, delete summaries that are obsolete or which are taking up needed space, and more.
Note: You can only access the Report Acceleration Summaries page in Manager if your role enables you to accelerate reports (your role must have the
schedule_search capability).
It's important to note that as the number of summaries in use by your implementation stacks up, you may encounter storage and performance impacts. This is because search acceleration summaries require storage space, and to keep them updated Splunk Enterprise has to run backgrounded searches on new data every 10 minutes. The Report Acceleration Summaries page enables you to quickly identify summaries that are taking up more space than they are worth, given the frequency of their use.
For more information about report acceleration, including an explanation of what is happening behind the scenes, a discussion of summary storage and performance considerations, and more tips on summary management with the Report Acceleration Summaries page, see "Manage report acceleration," in the Knowledge Manager Manual.
Schedule reports
A scheduled report is a report that runs on a scheduled interval, and which optionally 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.
17
You can use scheduled reports to send the results of the report 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 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 cannot schedule reports that run in real-time. Only reports that run over a historical time range can be scheduled.
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.
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
18