Searches power dashboards and forms
Splunk Enterprise searches power dashboards, forms, and the visualizations of data contained within them. This topic provides an overview of the types of searches available to you and how to include them in dashboards and panels using simple XML
Create searches to power dashboards
If you are new to the Splunk Enterprise search language, read the Search Manual section About search. Create searches to highlight the most relevant aspects of your data and support your user's goals. The Search Reference Manual provides additional information on searching, including a section on how to Write better searches, a Search command quick reference. and a complete Reference to Splunk search commands.
Searches saved as reports
You can save a search as a report and access the search in a dashboard by reference to the report. See Create and edit reports in the Reporting Manual for details.
Generate searches with Pivot
Use the Splunk Enterprise Pivot tool to generate searches as pivots that you can export to dashboards. For more information, see the Pivot Manual. The chapter Design pivot tables with the Pivot Editor provides details on building and exporting pivots as searches.
Use tokens with searches
Searches can access tokens, a type of variable that references search fields and their values. In the search command, surround a field with
$...$ characters to define a token. For the example below, a token has been defined with
index=_internal source=*metrics.log group="per_sourcetype_thruput" series=$series$ | table sourcetype eps, kb, kbps
You can then use the token in a form to accept user input and to display labels and titles in dashboards. The Basic form example shows how to use tokens within forms.
Simple XML elements for searches in dashboards
Splunk provides the following simple XML elements to specify a search in a dashboard or form.
This section provides a summary of how to use these elements to build dashboards and forms. For details on using these elements, refer to Search elements for dashboards, forms, and panels in the Simple XML Reference.
Search template element
You typically use the <searchTemplate> element to specify a global search for a form. You use tokens within the specified search to specify fields to be replaced with user input in the form.
- Note: You can only add a global <searchTemplate> element in simple XML code.
You can also use the <searchTemplate> element within a <dashboard> element and a visualization element, such as <chart>, <table>, and others.
An example of <searchTemplate> as a global search for a form:
<form> <searchTemplate> index=_internal source=*metrics.log group=per_sourcetype_thruput series="$src_type_tok$" | head 1000 </searchTemplate> . . . <fieldset> . . . <!-- user input for the form --> <input token="src_type_tok" /> </fieldset> <row> <panel> <chart> <!-- visualization for the search results --> </chart> </panel> </row> </form>
Using with dashboards
Use the <searchTemplate> element with the <dashboard> element to specify a global search for the dashboard. This is useful if you want to post process the search within individual panels of the dashboard.
Using with panels
You can use the <searchTemplate> element with panels to specify a panel-specific search. Within panels, <searchTemplate> is equivalent to <searchString>.
If you specify a <searchTemplate> for both the global search and the panel, Splunk recognizes only the <searchTemplate> element within the panel.
Search string element
Use the <searchString> element with panel elements to specify an inline search for the panel. You can use tokens with <searchString> elements.
<searchString> searches can power the following panel visualizations: <chart> <event> <list> <map> <single> <table>.
An example of a panel powered by a <searchString> element:
. . . <panel> <table> <title>High CPU processors</title> <searchString> index="_internal" source="*metrics.log" group="pipeline" | chart sum(cpu_seconds) over processor | sort -sum(cpu_seconds) | rename sum(cpu_seconds) as "Total CPU Seconds" </searchString> </table> </panel> . . .
Search name element
Use the <searchName> element with panel elements to specify a search saved as a report for the panel.
<searchName> searches can power the following panel visualizations: <chart> <event> <list> <map> <single> <table>.
An example of a panel powered by a <searchName> element:
. . . <panel> <table> <title>High CPU processors</title> <!-- High CPU Report is the name of a report with the saved search --> <searchName>High CPU Report</searchName> </table> </panel> . . .
Search post process element
Use the <searchPostProcess> element to further modify the results of a global search, specified by <searchTemplate>, within individual panels of a dashboard or form.
- Note: You can only add a <searchTemplate> in simple XML code.
Typically, the global search is a transforming search. A transforming search uses transforming commands to transform event data returned by a search into statistical data tables. Read more about transforming commands and searches in the Search Manual.
Post process is useful to minimize search resources while further processing search results to convey different information. However, be aware of the post process limitations listed below.
Example of a form using a post process search:
<form> <fieldset> <input type="dropdown" token="reportTypeToken"> <label>Select name</label> <default>Sourcetype</default> <choice value="index">Index</choice> <choice value="sourcetype">Sourcetype</choice> <choice value="source">Source</choice> <choice value="host">Host</choice> </input> <input type="time"> <default>Last 4 hours</default> </input> </fieldset> <!-- Search that returns the data processed by subsequent panels --> <searchTemplate> index=_internal source=*metrics.log group="per_$reportTypeToken$_thruput" | bin _time span=1m | stats count by series, eps, kb, kbps, _time </searchTemplate> <row> <panel> <table> <title>eps over time</title> <searchPostProcess>timechart avg(eps) by series</searchPostProcess> </table> </panel> <panel> <chart> <title>KB indexed over time</title> <searchPostProcess>timechart sum(kb) by series</searchPostProcess> <option name="height">300px</option> <option name="charting.chart">area</option> <option name="charting.chart.stackMode">stacked</option> </chart> </panel> </row> </form>
Post process limitations
Be aware of the following limitations when using post process.
- If the base search is a non-transforming search, the result set retains only the first 500,000 events matched. In this case, events in excess of this 500,000 limit are not processed by the post process search, resulting in incomplete data. Use a transforming search for the base search to avoid this problem.
- If the post-processing operation takes too long, it can exceed the Splunk Web non-configurable timeout value of 30 seconds. This can result in a timeout due to an unresponsive
splunkddaemon/service. This scenario typically happens when you use a non-transforming search as the base search. Use a transforming search for the base search to avoid this problem.
Avoid base searches that returns raw events
It might seem logical to have a non-transforming base search that returns raw events, and then use transforming commands in the post process search. However, in this scenario the base search could return in excess of the event limitation. Thus, it passes an incomplete data set to the post process searches, producing erroneous results in your dashboard.
It is better to use transforming commands in the base search to avoid the event limitation. Read more about transforming commands and searches in the Search Manual.
Avoid post process searches that reference fields not named in the base search
It might seem logical to reference a field only in the post process searches, but it is better to isolate the data for the field in the base search. Otherwise the field that you reference only in the post process search becomes null in all rows, thus returning zero results.
Use transforming commands in the base search to avoid this scenario.
Avoid returning large numbers of rows in the base search
Passing a large number of search results to a post process search can cause problems.
Server time out
If the post-processing operation takes too long, it can result in performance problems, and possibly a timeout due to an unresponsive splunkd daemon/service. In this scenario, consider the following:
- The number of results and fields returned from the base search.
- The complexity of the post process operations on these results.
If the base search returns in excess of the event limitation, an incomplete data set is passed to downstream panels (as described above). To avoid event limitation, use transforming commands in the base search to structure search results.
About editing simple XML
This documentation applies to the following versions of Splunk® Enterprise: 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13