Splunk® Enterprise

Dashboards and Visualizations 6.5.7

Generated: 8/17/2022 10:03 pm

Copyright (c) 2022 Splunk Inc. All Rights Reserved

 Table of Contents
Introduction...........................................................................................................................................................................1
Getting started...........................................................................................................................................................1

Get Started with Visualizations...........................................................................................................................................3

Visualization reference..............................................................................................................................................3
Data structure requirements for visualizations...........................................................................................................4

Events List.............................................................................................................................................................................6
Using events lists.......................................................................................................................................................6

Table Visualizations.............................................................................................................................................................8
Table visualization overview......................................................................................................................................8
Generate a table........................................................................................................................................................8
Format table visualizations........................................................................................................................................9
Table column Simple XML.......................................................................................................................................15

Charts..................................................................................................................................................................................23
Chart overview.........................................................................................................................................................23
Data for charts.........................................................................................................................................................24
Pie chart...................................................................................................................................................................25
Column and bar charts............................................................................................................................................26
Line and area charts................................................................................................................................................30
Scatter chart............................................................................................................................................................34
Bubble chart.............................................................................................................................................................35
Chart display issues.................................................................................................................................................36

Single Value........................................................................................................................................................................39
Overview..................................................................................................................................................................39
Generate a single value...........................................................................................................................................39
Customize a single value.........................................................................................................................................41

Gauges.................................................................................................................................................................................44
Using gauges...........................................................................................................................................................44

Maps.....................................................................................................................................................................................47
Mapping data...........................................................................................................................................................47
Generate a Choropleth map....................................................................................................................................47
Configure a Choropleth map....................................................................................................................................50
Cluster maps............................................................................................................................................................51

Get Started with Dashboards............................................................................................................................................54

Dashboard overview................................................................................................................................................54
About the dashboard editor.....................................................................................................................................56

Build and Edit Dashboards in Splunk Web......................................................................................................................57

Create a dashboard.................................................................................................................................................57
Working with dashboard panels...............................................................................................................................57

i
 Table of Contents
Build and Edit Dashboards in Splunk Web
Add panels to dashboards.......................................................................................................................................59
Edit dashboards.......................................................................................................................................................63
Edit visualizations....................................................................................................................................................65
Create and edit forms..............................................................................................................................................67
Convert a dashboard to HTML................................................................................................................................80

Create Dashboards with Simple XML...............................................................................................................................81

Editing Simple XML.................................................................................................................................................81
Searches power dashboards and forms..................................................................................................................82
Dashboards and forms............................................................................................................................................95
Dashboard examples...............................................................................................................................................97
Form examples......................................................................................................................................................107
Using a third party XML editor...............................................................................................................................114

Drilldown and Dashboard Interactivity...........................................................................................................................118

Drilldown behavior.................................................................................................................................................118
Dynamic drilldown in dashboards and forms.........................................................................................................128
Token usage in dashboards..................................................................................................................................137
Chart controls........................................................................................................................................................156

Manage and Share Dashboards......................................................................................................................................162

Configure dashboard permissions.........................................................................................................................162
Generate dashboard PDFs....................................................................................................................................163
Clone and manage dashboards.............................................................................................................................169

Simple XML Reference.....................................................................................................................................................171

Simple XML reference...........................................................................................................................................171
Chart configuration reference................................................................................................................................246
Event handler reference........................................................................................................................................259
Token reference.....................................................................................................................................................282
Customize Simple XML.........................................................................................................................................284

ii
Introduction

Getting started
Learn how to share insights with data visualizations and dashboards.

To view a PDF that offers you a short overview of the most common operations, definitions, and commands you will use
when you create dashboards and visualizations, see the Splunk Dashboards Quick Reference Guide.

The visualization and dashboard workflow

You might need to generate a new visualization or edit an existing dashboard. Working with dashboards and
visualizations includes one or more of the following tasks.

Select a visualization

• Select a visualization to show specific data insights.

• To find and compare visualization options, see the Visualization reference.

Generate and configure visualizations

• Write a search to generate a visualization. Make sure that the search returns results in the correct format for
rendering the visualization. See Data structure requirements for visualizations for an overview about data
formatting.
• Configure or update visualization appearance and behavior. Change color modes, add captions, or adjust other
visualization elements. See the Visualization reference for an overview of options and links to details on each
visualization type.

Build and edit dashboards

• Add visualizations to new or existing dashboards.

• Work with the editing user interface to adjust dashboard components.
• Convert a dashboard to a form by adding user inputs.
• To get started, see the Dashboard overview and Create dashboards.

Share and manage dashboards

• Export dashboards for sharing. To get started, see Generate dashboard PDFs.
• Manage permissions for viewing and editing dashboards. See Configure dashboard permissions for details.

1
 • Clone a dashboard or display a dashboard on the app home page. To learn more, see Clone and manage
dashboards.

Edit Simple XML

• Use Simple XML source code to customize dashboard content and behavior. See About editing Simple XML for
an overview and the Simple XML reference for more details.

2
Get Started with Visualizations

Visualization reference
Compare options and select a visualization to show the data insights that you need.

To quickly view the most fundamental overview of common visualizations and their use cases, note that you can access
the Splunk Dashboards Quick Reference guide by clicking the link in Getting started.

Visualization Usage To learn more see

Events list
Show the events that a search generates.

• Show events without additional processing.

Using events lists
• Show extracted fields and values directly in a dashboard.
• Users can click on event fields or timestamps to open a
more specific search.

Table

Compare and aggregate field values.

• Isolate one or more specific fields from search results. Table visualization overview
• Add formatting to highlight trends or patterns in specific
fields.

Charts Visualize one or more dimensions in a data set.

Use one of the following chart types depending on how many
dimensions, or fields, you are visualizing.
Chart overview
• Pie
• Area, line, column, bar
• Bubble and scatter

Single value
Show an aggregated metric in context.
Single value overview
• Track recent changes or trends in real time.
• Use colors to add context dynamically.

Gauges

• Show an aggregated metric against a range. Using gauges

• Track a metric as it approaches a specific target.

Maps Visualize data with geographic coordinates. Mapping data

• Use a Choropleth map to show and compare regional

trends or concentrations.
• Use a marker map to plot geographic data.

3
 Visualization Usage To learn more see

Analyze and represent unique data sets.

See Custom visualizations for
Custom visualizations
An admin must install custom visualization apps to make them more details.
available for Splunk users.

Data structure requirements for visualizations

Visualizations require search results in specific formats or data structures. Write queries to generate results in the correct
format for the visualization that you are building.

This topic provides an overview of data structures for visualizations. To learn about requirements for a specific
visualization and how to generate results in the correct format, see one of the following topics.

Events list
Using events lists

Table visualizations
Generate a table

Charts
Pie chart
Column and bar charts
Line and area charts
Scatter chart
Bubble chart

Single value
Generate a single value

Gauges
Using gauges

Maps
Mapping Data

For an overview of visualization options, see the Visualization Reference in this manual.

Data and formatting requirements

Depending on the visualization that you are creating, you can use specific search commands to generate results in the
correct format. For example, many visualizations require a search using transforming commands, such as stats, chart,
timechart, or geostats to render.

4
Charts visualize one or more data series, or related data points. Depending on the chart type or complexity, the number
and ordering of data series can vary.

Single value and gauge visualizations represent a single numerical value.

Maps combine a query and other data components, including data with coordinates or place information, lookup
definitions, and geographical markup files.

Using the statistics table

When creating a visualization, you can check the Statistics table after running a search to make sure that result fields are
generated correctly. The number and order of Statistics table columns show you the data structure that a search
generated.

Additional information

Review specific visualization topics to check data format requirements and query recommendations.

To learn more about search commands that can generate visualizations, see the following topics.

• Statistical and charting functions in the Search Reference

• About transforming commands in the Search Manual

5
Events List

Using events lists

Add an events list to a dashboard to give users access to the events, fields, and values generated by a search. An events
list does not abstract or process search results like a chart or other visualization does.

Generate an events list

The content in an events list depends on the search that you run. There are no additional data format requirements.

Prerequisites
Review Configuration options.

Steps

1. From the Search page, run a search.

2. Select the Events tab to view the events list.
3. (Optional) Select Save As > Dashboard panel to add the events list to a dashboard.
4. (Optional) Use the Format menu or Simple XML to configure the events list.

Configuration options

Use the Format menu to configure one or more of the following events list components. You can also adjust these
components and make additional configurations using Simple XML.

Display and format options

Use the following settings to adjust events list appearance.

• Choose an events display option.

♦ List (default): Show timestamps for each event separately.
♦ Raw: Show raw events.
♦ Table: Display events as a table. This format is different from the Statistics table visualization.
• Configure row numbers, wrapping, and maximum lines

Drilldown

When configuring drilldown on an events list in Simple XML, you can specify one of the following drilldown settings to
provide different segment selection options.

Drilldown
Segmenting option enabled for users Example
setting
Full Select a major segment or one or more contiguous minor
segments.

The first example shows a minor segment selection. The second

example shows a major segment selection.

6
 Drilldown
Segmenting option enabled for users Example
setting

Inner Select a single minor segment.

Outer Select a complete major segment.

None Disables drilldown (default)

Note: Event segmentation processing for events with long single lines of text can cause browser performance issues.

For more details, see Types of event segmentation in the Knowledge Manager Manual.

Use case scenario

An admin uses an events list to give users access to recent notable system events. To generate the events list, the admin
runs the following search.

error OR failed OR severe OR ( sourcetype=access_* ( 404 OR 500 OR 503 ) )

The admin adds the events list to a dashboard tracking system status. Dashboard users can click on event fields or a
timestamp in the list to open a search using the clicked content.

For example, clicking on the /opt/splunktest/var/log/splunk/metrics.log source value in an event opens the following
search in a new window.

index=_internal source="/opt/splunktest/var/log/splunk/metrics.log"

7
Table Visualizations

Table visualization overview

Tables can help you compare and aggregate field values. Use a table to visualize patterns for one or more metrics across
a data set. Start with a query to generate a table and use formatting to highlight values, add context, or create focus for
the visualization.

Create a table visualization

Learn how to generate and configure a table visualization. See the following topics for details.

• Generate a table
• Format table visualizations
• Table column Simple XML

Generate a table
To generate a table, write a search that includes a transforming command. From the Search page, run the search and
select the Statistics tab to view and format the table.

You can use the table command in a search to specify the fields that the table includes or to change table column order.

Search examples

• Transforming search
This search uses the chart transforming command.

index = _internal | chart avg(bytes) over sourcetype

8
 The search generates a table with two columns.

• Transforming search with the table command

This search generates a table with action, host, and count columns.

index = _internal | stats count by action, host

To change the columns that appear in the table or to change column order, add the table command to this
search. For example, add | table host count to generate a table with only the host and count columns.

index = _internal | stats count by action, host | table host count

Table sparklines

Sparklines show data patterns or trends in a results set. To generate a table sparkline, usestats or chart with the
sparkline function in a search.

Sparkline width is determined by default data binning. You can adjust data binning as a parameter of the sparkline
command.

For more information, see Add Sparklines to your search results in the Search Manual.

Format table visualizations

Use the Format menu to configure a table visualization.

Add summary statistics

Use the Format menu Summary tab to include column totals and percentages. For each statistic, a highlighted summary
row appears at the bottom of the table. Column totals and/or percentages appear at the bottom of each column that
contains numeric values.

9
Note: Values in a summary row reflect statistics for the complete search result set. For tables with more than one page of
results, summary row values do not apply only to the currently displayed page.

Summary and data row differences

There are some behavior and formatting differences between summary rows and data rows in a table.

Behavior or format Summary rows Data rows

Static highlight color Yes No

Values in the row can skew table color formatting or data overlay No Yes

Column number formatting applied to the row Yes Yes

Drilldown available for the row No Yes

Included in PDF or CSV export No Yes

Totals data row behavior

A static summary row fits most use cases. If you generate a totals data row using the addcoltotals SPL command in a
search, note the following table behavior impacts.

• An addcoltotals row is treated as a data row in the table.

• Because they are handled as data rows, addcoltotals rows are included in a PDF or CSV dashboard export.
• Color scales or data overlay can be skewed if a table includes an addcoltotals data row.
• Tables should not include an addcoltotals data row and a column totals summary row. If you opt to include a
totals summary row, adjust the search to remove the addcoltotals command.

Summary row examples

The following examples show use case scenarios for adding column totals and percentage rows to a table.

Totals summary row

An analyst for an online retailer is evaluating how customer actions, such as purchases or quantity changes, relate to
product types. The analyst is also comparing the relative frequency of different customer actions.

The following query generates a table showing product type counts for each customer action.

... | chart count(itemId) over categoryId by action

Using the Format menu, the analyst adds a totals summary row to the table.

10
The totals row shows relative totals for each customer action. For instance, there were 952 purchase events in the results
set, compared to 98 product removal events.

Percentage summary row

An analyst creates a table showing purchasing activity on a retail website. The following query generates results
comparing purchases for different product types.

... | chart count(itemId) over action by categoryId

The analyst uses the Format menu to include a percentage row in the table.

This row shows a percentage for each product type relative to all purchases. For example, arcade games make up 19.4
percent of all purchases.

Format table columns

You can format individual table columns to add context or focus to the visualization. Click on the paintbrush icon at the top
of each column to customize color and number formatting.

11
Note: Column formatting is not available for columns representing the _time field or for sparkline columns.

Column color

Select and configure one of the following color modes for the column.

Note: Column color formatting overrides existing heat map or high/low value data overlay settings.

Scale

Use a sequential or divergent color scale on column cells. You can choose a preset scale or a custom configuration to
manage how colors in the scale are applied to column cells.

Depending on search results and data distribution, column color gradation can vary. Columns with relatively similar values
will show the most color gradation. Outlying values can limit the gradation.

Color scale options

Scale
Description Example
type
This example column has sequential coloring. It is also sorted to show the highest
values at the top.

Use a sequential scale to show how

Sequential results approach a high value in the
column.

Divergent A divergent scale can show how results This example column has divergent coloring. It shows the lowest values at the top
approach high and low values. and the highest values at the bottom.

12
 Scale
Description Example
type

Configure a custom color scale

You can configure custom color handling by indicating minimum, midpoint, and maximum value colors. Use one of the
following options to configure the minimum, midpoint, and maximum value interpretation for the color scale.

Configuration options

Option Description Use case example

• Show which products had the most

Highest and This option highlights the highest and lowest values in the purchases in a sales data set.
lowest values column. • Show how recent customer satisfaction
survey results trended towards highest and
lowest scores.

Indicate numeric value thresholds. Cell color is determined • Show department course enrollment
Number
according to how values align with the three thresholds. according to small, medium, and large roster
size.

Percent Determine cell color using percentages of the results value range.
• Show student test scores on a final exam.

Determine cell color using percentiles of the results value

Percentile • Compare customer satisfaction survey
distribution.
results.
Ranges

Apply color to cells in this column according to value ranges.

Range configuration options include the following.

• Adjust the default range value and color settings.

• Add or remove ranges.

Use ranges to compare cell values categorically. For example, use red, yellow and green range colors to indicate low,
medium, and high sales results.

13
Values

Apply colors according to cell values.

Use automatic value coloring or define custom rules. Automatic coloring applies a color to every cell in the column. Cells
with the same value appear in the same color.

Custom rules can help highlight specific values that you are monitoring. For example, use custom rules to highlight three
new products in recent sales data.

Number format

Enable and adjust number formatting for each column. The number format settings panel includes the following options.

• Enable or disable number formatting.

• Set decimal precision.
• Opt to use thousand separators.
• Specify a measurement unit to add context to the values in this column. You can position the unit before or after
each value.

Configure table properties

After generating a table, use the Format menu to configure one or more of the following table components.

• The number of rows shown in each table page

• Wrapping
• Table row number display

14
Data overlay

The Format menu also includes the following data overlay options.

Heat map
Add different shades of a particular color to the table to show value variation over table rows.

High and low value

Add high and low value colors to the table to highlight the highest and lowest values.

Use data overlay if you are not adding column color formatting to the table. Column color formatting overrides data
overlay configurations.

Drilldown

You can choose one of these three options for table drilldown behavior.

Option Behavior on user selection

Cell Default. Opens a secondary search using the field and value in the selected cell.

Row Opens a secondary search using the field and values from cells in the selected row.

None Disables drilldown

Table column Simple XML

Use format rules to configure table columns in Simple XML.

Indicate color scale and color palette rules to manage column color formatting. You can also use a number format rule to
manage the appearance of numeric cell values.

Put all table formatting rules inside the <table> dashboard element.

<table>
[...]
</table>

Format rule syntax

To create a new format rule, indicate a format rule type and a column where you want to apply the rule. Use the following
syntax.

<format type= [ "color" | "number" ] field="<column_name>">

[...]
</format>

If you do not specify a field, the format rule is applied to the entire table.

15
Color format rules

To add column color, create a format rule with type "color" and the column name where you want to apply the rule.

Start configuring column color by specifying a color scale type. The color scale type indicates how color is applied to
values in the cell. After defining a color scale, you can add a color palette to indicate which colors to use for the column.

Use the following syntax to specify a color format rule.

<format type="color" field="<column_name>">

<scale type="<color_scale_type>" [color scale option configurations] </scale>
<colorPalette type="<color_palette_type>" [color palette option configurations] </colorPalette>
</format>

Color scale types and options

category
Apply colors to the column based on category. You can provide an optional category list to pre-populate the color scale.
Additional categories that occur in results are added after the specified categories.

Options and accepted values Example

<format type="color" field="server_status">

(Optional) list one or more category strings. <scale type="category">online, offline
</scale>
</format>

linear
Map numeric data on a linear scale.

Options and accepted values Example

<format type="color" field="purchases">

None
<scale type="linear"></scale>
</format>

log
Map numeric data on a logarithmic scale.

Options and accepted values Example

None
<format type="color" field="performance">
<scale type="log"></scale>
</format>

16
 Options and accepted values Example

minMidMax
Map numeric data according to a range with a minimum, midpoint, and maximum value.

Indicate a type and a value for each of the range segments.

minValue, midValue, maxValue options for this

minType, midType, maxType options
type
number
Any valid floating point number.
Interpret values as discrete numbers.
percent
Any number between 0 and 100.
Interpret values as a percentage of the value range of the data.
percentile
Any number between 0 and 100.
Interpret values as a percentage of the distribution of the data.

Type and value defaults

All segment types default to number.

All percent and percentile values default as follows.

• minValue: use the lowest value from the data.

• midValue: use a value halfway between the lowest and highest value in the range.
• maxValue: use the highest value in the data.

Example

<format type="color" field="field">

<scale type="minMidMax" minType="number" minValue="2" midType="number" maxType="percent"
maxValue="100"></scale>
</format>

sharedCategory
Use this scale type with the sharedList palette to apply automatic formatting to this column.

Options and accepted values Example

None. Use this scale with the sharedList palette as shown in the example.
<format type="color" field="sourcetype">
<scale type="sharedCategory">
</scale>
<colorPalette type="sharedList">

17
 Options and accepted values Example
</colorPalette>
</format>

threshold
Specify a set of finite value thresholds for binning data.

Options and accepted values Example

List values in ascending order. You can use any finite numbers,
including floating point values. <format type="color"
field="purchase_count">
<scale
All values less than the first threshold go into the first bin. All values type="threshold">0,30,70,100</scale>
equal to or greater than the last threshold go into the last bin. </format>
Color palette types and options

Once you define a color format rule and add a color scale to it, include a color palette type and options. The color palette
determines which colors the scale applies to column cells.

expression
Use a logical expression that returns a color for a particular value.

Color string formats

Use any of the following formats.

• #FFF
• #FFFFFF
• 0xFFF
• 0xFFFFFF
• rgb(255, 255, 255)
• rgba (255, 255, 255, 1)

Example
This example expression applies the color #65A637 to cells with the value splunkd. For cells with other values, the color
#0000CC is used.

<colorPalette type="expression">if (value == "splunkd", "#65A637", "#0000CC")

</colorPalette>

list
Specify a list of color strings for this palette.

Interpolate listed colors

Add the interpolate boolean value to indicate whether to interpolate colors adjacent to the ones in the list. Setting
interpolate to "true" creates a smoother color gradient.
interpolate defaults to false.

18
Color string formats
Use any of the following formats.

• #FFF
• #FFFFFF
• 0xFFF
• 0xFFFFFF
• rgb(255, 255, 255)
• rgba (255, 255, 255, 1)

Example

<colorPalette type="list" interpolate="true">[#65A637,#6DB7C6,#F7BC38,#F58F39,#D93F3C]

</colorPalette>

map
Specify a map of one or more cell value and color string pairs.

Use the following map format.

{ {<cell_value_string>} : {<color>}, {<cell_value_string>} : {<color>} }

Color string formats

Use any of the following formats.

• #FFF
• #FFFFFF
• 0xFFF
• 0xFFFFFF
• rgb(255, 255, 255)
• rgba (255, 255, 255, 1)

Example

<colorPalette type="map">{"online":#65A637, "offline":#6A5C9E}

</colorPalette>

minMidMax
Specify minimum and maximum or minimum, mid, and maximum colors to use in generating a color gradient. Gradient
values are interpolated between the specified colors.

Indicate colors for the following options.

• minColor (Required)
• midColor (Optional)

19
 • maxColor (Required)

Color string formats

Use any of the following formats.

• #FFF
• #FFFFFF
• 0xFFF
• 0xFFFFFF
• rgb(255, 255, 255)
• rgba (255, 255, 255, 1)

Example

<colorPalette type="minMidMax" minColor="#FFFFFF" maxColor="#65A637">

</colorPalette>

sharedList
Use this palette with the sharedCategory color scale to apply automatic formatting to this column.

Example

<format type="color" field="sourcetype">

<scale type="sharedCategory"></scale>
<colorPalette type="sharedList"></colorPalette>
</format>
Number format rules

Specify how numeric values appear.

Use this syntax to create a number format rule.

<format type="number" field="count">

<option name="<number_format_option_name>">[number_format_option_value]</option>
</format>

Number format options

Name Description Accepted values and defaults

Use a number between 0-20. Defaults
precision Specify the number of decimal precision places.
to 2.

Indicate whether to insert a comma or other symbol between every three

useThousandSeparators digits. Symbols are set according to the language and region for the Splunk Boolean. Defaults to true.
platform instance.

unit Indicate a unit label to place before or after the value.

20
 Name Description Accepted values and defaults
Use any String. For best results, use
an abbreviation or other brief label
text.

[before | after ]
unitPosition Indicate where to place the unit label.
Defaults to after.

Number format example

<table>
<search>
<query>index=_internal | head 10000 | stats count by sourcetype</query>
</search>
<format type="number" field="count">
<option name="precision">3</option>
<option name="useThousandSeparators">false</option>
<option name="unit">MB</option>
<option name="unitPosition">before</option>
</format>
</table>

Table format source code example

This example table visualizes recent sales performance.

Columns represent product categories and id codes, as well as item sales totals. Format rules help distinguish categories,
highlight particular items, and show relative sales metric density across all products.

21
The source code includes color scale, palette, and number format rules.

<dashboard>
<label>Sales performance</label>
<row>
<panel>
<title>Sales this month</title>
<table>
<title>Accessories and arcade game sales</title>
<search>
<query>source="tutorialdata (1).zip:*" | stats count by categoryId, itemId | table categoryId
itemId count</query>
<earliest>0</earliest>
<sampleRatio>1</sampleRatio>
</search>
<option name="count">20</option>
<option name="dataOverlayMode">none</option>
<option name="drilldown">cell</option>
<option name="rowNumbers">false</option>
<option name="wrap">true</option>
<format type="color" field="itemId">
<colorPalette type="map">{"EST-15":#D93F3C,"EST-7":#6DB7C6}</colorPalette>
</format>
<format type="color" field="categoryId">
<colorPalette
type="map">{"ACCESSORIES":#6DB7C6,"ARCADE":#F7BC38,"STRATEGY":#AFEEEE}</colorPalette>
</format>
<format type="color" field="count">
<colorPalette type="minMidMax" maxColor="#31A35F" midColor="#A2CC3E"
minColor="#FFFFFF"></colorPalette>
<scale type="minMidMax" maxType="percentile" maxValue="100" midType="percentile" midValue="50"
minType="percentile" minValue="0"></scale>
</format>
<format type="number" field="count">
<option name="precision">0</option>
<option name="unit">units</option>
</format>
</table>
</panel>
</row>
</dashboard>

22
Charts

Chart overview
Select a chart type to show one or more data dimensions in a results set. Learn how charts visualize data series.

For a quick glance at common charts and common chart use case commands, you can view the Splunk Dashboards
Quick Reference guide by clicking the link in Getting started.

Select a chart

You can select a chart depending on the number of data dimensions that you want to visualize. For example, use a pie
chart to show how values combine in a single field. A bubble chart can show relationships between multiple fields in a
data set.

Chart type Description

Pie

Shows a single dimension. Pie slice size represents the

density or frequency of values in a field.

Column and bar

Represent one or more dimensions in a results set.

These charts plot data on two axes. Each axis
represents a results field.

Column and bar charts can compare values and fields.

Line and area

Line charts can show value changes over time.

Area charts show changes in an aggregated value over

time.

Scatter and bubble

Represent multiple dimensions in a results set. These

charts plot data on two axes. Data point appearance,
size, and/or distribution show additional patterns or
relationships.

23
 Chart type Description

Get started

The following topics show you how to build and configure charts.

• Data for charts

• Pie chart
• Column and bar charts
• Line and area charts
• Scatter chart
• Bubble chart

Data for charts

To build any chart, start with a transforming search that generates one or more data series.

A series is a sequence of related data points. These points can be plotted on a chart. For example, each line in a line
chart shows one series.

When you run a transforming search, select the Statistics tab. Review the statistics table to see the series generated.
After the first column, each additional column represents a series. A single series search generates two columns. A
multiple series search generates three or more columns.

Different chart types are optimized to visualize one or more data series.

Optimized for single Optimized for multiple

Chart name Notes
series? series?
Pie Yes No Pie charts can only render a single series.

Bar Yes Yes

Column Yes Yes

Typically, line charts are used for multiple

Line Yes Yes
series.

Area No Yes Use an area chart to render multiple series.

Scatter No Yes Scatter charts work best with two data series.

Bubble No Yes Bubble charts work best with three data series.

24
Pie chart
Use a pie chart to show how different field values combine over an entire data set. Each slice of a pie chart represents the
relative importance or volume of a particular category.

Data formatting

Pie charts represent a single data series.

Use a transforming command in a search to generate the single series.

For example, count events in each source field category.

...| stats count by source

Check the Statistics table after running the search to make sure that a single series generated. The table should have
two columns.

The example search generates the following table.

The first table column contains labels for each pie slice. The second column contains the numerical values that
correspond to each label. The numerical values determine the relative size of each slice.

If the search generates a table with more than two columns, the extra columns are ignored.

Configuration options

You can use the Format menu to configure the following pie chart components.

Drilldown

Drilldown in a pie chart lets users click on a pie slice to open a secondary search using the clicked values. You can enable
or disable drilldown using the Format menu.

Minimum size

Set a minimum percentage size to apply when there are more than 10 slices. Data values below the minimum percentage
are combined into an other slice.

25
Create a pie chart

Prerequisites
Review the following details about building pie charts.

• Data formatting
• Configuration options

Steps

1. Write a search that uses a transforming command to aggregate values in a field.

2. Run the search.
3. Select the Statistics tab below the search bar. The statistics table here should have two columns.
4. Select the Visualization tab and use the Visualization Picker to select the pie chart visualization.
5. (Optional) Use the Format menu to configure the visualization.

Examples

This search portion aggregates events by Code field values.

... | stats count by Code

The search generates a single data series representing values in the Code field.

The chart is configured with a 5% minimum size. Field values that represent less than 5% of the total data set are
combined into an other slice.

This search uses the bytes and source fields to generate a single series.

index = _internal | chart avg(bytes) over source

Here, the source column provides pie slice labels. The avg(bytes) column provides the relative size of each slice, as
percentages of the sum of avg(bytes) returned by the search.

Column and bar charts

Use column and bar charts to compare field values across a data set.

26
Data formatting

Column and bar charts represent one or more data series. To make sure that a search generates one or more series,
check the Statistics tab. The table should have at least two columns.

Search results not structured as a table with valid x-axis or y-axis values cannot generate column or bar charts. For
example, using the eval or fields commands might change search result structure.

Statistics table order and chart axes

Column and bar charts handle Statistics table values differently.

Column charts get x-axis values from the first column in the table. The next table columns contain y-axis values.

Bar charts get y-axis values from the first column in the table. The next table columns contain x-axis values.

As an example, any search using the timechart reporting command generates a table where _time is the first column. A
column chart generated with this search has a _time x-axis. A bar chart using this search has a _time y-axis.

Single and multiple data series

Column and bar charts can visualize single or multiple data series. The following examples show you how to generate
these series.

Single series

A search compares the average number of bytes passed through each source. In this search, the over operator indicates
that source is the first table column.

...| chart avg(bytes) over source

The search produces the following table.

Column and bar charts represent this single series differently.

Column chart
source values are used for the x-axis. The y-axis in the column chart is avg(bytes).

Bar chart
avg(bytes) values are used for the x-axis. The bar chart y-axis would represent source field values.

Multiple data series

To generate multiple data series, introduce the timechart command to add a _time field to search results. You can also
change the query to introduce a split-by field.

For example, change the previous single series search by adding clientip as a split-by field.

27
...| chart avg(bytes) over source by clientip
The split-by field produces multiple data series. Each clientip is a data series with its own avg(bytes) values for each
source.

To show multiple series in a bar or column chart, use the Format menu to configure stacking and multi-series mode.

Configuration options

Use the Format menu to customize one or more of the following column and bar chart components.

• Chart titles
• Axis titles
• Minimum and maximum axis values
• Use a logarithmic unit scale. This option is helpful when there are very small and very large axis values.
• Chart legend placement and text truncation
• Label rotation
• Enable or disable drilldown. When drilldown is enabled, users can click on a column, bar, or chart legend to open
a search in a new window. The search uses values from the selected element.

Multiple series options

If the chart represents multiple data series, you can also configure the following options.

Multi-series mode

Compare trends across multiple series. Enable the mode to show independent axis ranges for each series.

Stacked charts

Use a stacked chart to see more details for values in a particular field. You can select unstacked, stacked, and 100%
stacked bar and column charts. See the following comparison.

Stack
Column or bar appearance Use case
option
An unstacked chart is useful for a lower number of series. As the
Columns or bars for different series appear next to each
Unstacked number of series increases, the chart can become more difficult to
other.
understand.

Data points within a series appear as segments of a column Use a stacked column or bar chart to highlight the relative volume,
Stacked or bar. The total column or bar value is the sum of all of the frequency, or importance of data points in a series. See the
segments. stacked chart example below.

Each bar or column is divided into segments representing

Stacked Use stacked 100% to show data distributions when there is
the distribution percentage for each data value in one
100% significant segment size variation in each column or bar.
series.

28
Create a column or bar chart

Prerequisites
Review the following details about building column and bar charts.

• Data formatting
• Configuration options

Steps

1. Write a search that generates one or more data series.

2. Run the search.
3. Select the Statistics tab below the search bar. The statistics table here should have two or more columns.
4. Select the Visualization tab and use the Visualization Picker to select the column or bar chart visualization.
5. (Optional) Use the Format menu to configure the visualization.

Examples

Bar chart

This search calculates a CPU seconds sum for each processor. The search also sorts the processors with the ten highest
sums in descending order.

index=_internal "group=pipeline" | stats sum(cpu_seconds) as totalCPUSeconds

by processor | sort 10 totalCPUSeconds desc
The search generates this bar chart.

Stacked column chart

This search portion aggregates events according to code values over time. The query specifies the _time field and Code
field values to include. This query generates a series for each Code field value.

...| timechart count by Code | fields _time L B N

The stacked columns show event counts for each code at different points in time. You can compare how many L, B, and N
flagged events there were at each point in time.

29
Line and area charts
Use line and area charts to track value trends over time. You can also use a line or area chart x-axis to represent a field
value other than time.

Data formatting

Line charts can represent one or more data series. Area charts represent multiple data series.

If a search generates multiple series, each line or area in the chart appears in a different color.

To make sure that a search generates data series correctly, check the Statistics tab below the search bar. The Statistics
table should have at least two columns for a single series, and three or more columns for multiple series.

Statistics table order and chart axes

Line and area charts get x-axis values from the first column in the Statistics table. The next table columns contain y-axis
values.

As an example, any search using the timechart reporting command generates a table where _time is the first column. A
line or area chart generated with this search has a _time x-axis.

Search results not structured as a table with valid x-axis or y-axis values cannot generate line or area charts. For
example, using the eval or fields commands might change search result structure.

Single and multiple data series

Typically, line or area charts represent multiple series. Line charts can also be used for a single data series, but area
charts cannot.

Single series

A search compares the average number of bytes passed through each source. In this search, the over operator indicates
that source is the first table column.

...| chart avg(bytes) over source

The search produces the following table.

30
In a line chart, source values are used for the x-axis. The y-axis represents avg(bytes) values.

Multiple data series

To generate multiple data series, introduce the timechart command to add a _time field to search results. You can also
change the query to introduce a split-by field.

For example, change the previous single series search by adding clientip as a split-by field.

...| chart avg(bytes) over source by clientip

The split-by field produces multiple data series. Each clientip is a data series with its own avg(bytes) values for each
source.

Configuration options

Use the Format menu to configure one or more of the following line and area chart components.

• Chart title
• Axis titles
• Null y-axis value handling. Choose one of the following options.
♦ Show null data points as a gap. The chart shows markers for any disconnected data points in this case.
♦ Connect null data points to zero data points.
♦ Connect to the next positive data point.
• Show minimum and maximum y-axis values.
• Use a logarithmic unit scale for y-axis values. This option is helpful when there is a wide range in y-axis values.
• Chart legend position and label truncation
• Enable or disable drilldown. When drilldown is enabled, users can click on a line, area, or chart legend to open a
search in a new window. The search uses values from the selected element.

Multiple series options

If the chart represents multiple data series, you can also configure the following options.

Multi-series mode

Compare trends across multiple series. Enable the mode to show independent axis ranges for each series.

31
Stacked area charts

Stacked area charts are available when a search generates multiple data series. Stacking is not available for line charts.

Use a stacked area chart to see more details about a series and how it relates to the entire data set. Review the
comparison table here to select a stacking option.

Stack
Column or bar appearance Use case
option
Areas for different series share the same space An unstacked chart is useful for a lower number of series. As the number of
Unstacked
on the chart. series increases, the chart can become more difficult to understand.

Use a stacked area chart to highlight the relative volume, frequency, or

Stacked Each series area is shown separately.
importance of a series. See the stacked chart example below.

Stacked The chart shows distribution percentage for

Use stacked 100% to focus on data distributions.
100% each series over the whole data set.

Create a line or area chart

Prerequisites
Review the following details about building column and bar charts.

• Data formatting
• Configuration options

Steps

1. Write a search that generates multiple data series. If you are building a line chart you can opt to generate a single
data series.
2. Run the search.
3. Select the Statistics tab below the search bar. The statistics table here should have two or more columns.
4. Select the Visualization tab and use the Visualization Picker to select the line or area chart visualization.
5. (Optional) Use the Format menu to configure the visualization.

Examples

Line chart

This search tracks sourcetype frequency over time.

index=_internal | timechart count by sourcetype

The search generates multiple data series. The line chart represents each series with a different line.

32
Area chart

Shading in an area chart emphasizes quantities. This example search tracks historical and real-time search volume over
time.

index=_internal source=*metrics.log group=search_concurrency "system total" NOT user=*

| timechart max(active_hist_searches) as "Historical Searches" max(active_realtime_searches) as "Real-time
Searches"

The search generates two data series. Each series appears as a different shaded area on the chart.

Stacked area chart

This search tracks throughput for different series over time.

index=_internal per_sourcetype_thruput | timechart sum(kb) by series useother=f

The search generates multiple series. Each series appears as a colored area of the stacked chart. The stacking lets you
compare the sums for different series.

33
Scatter chart
Use a scatter chart to show relationships between discrete data points. Data point distribution can show trends or
relationships across two dimensions.

Data formatting

Scatter charts work best with two data series. Use a transforming command to aggregate values. You can use the table
command with the following syntax to manage result field ordering.

... | table <marker_name_field> <x-axis_field> <y-axis_field>

Check the Statistics tab after running the search to make sure that there are three columns in the Statistics table. You
can use the table command to change the order of the columns if needed.

Configuration options

Use the Format menu to configure one or more of the following scatter chart components.

• Axis titles
• Legend placement and truncation
• Axis scale and interval values
• Axis minimum and maximum values
• Enable or disable drilldown. When drilldown is enabled, users can click on a data point or legend to open a search
in a new window. The search uses values from the selected element.

Create a scatter chart

Prerequisites
Review the following details about building column and bar charts.

• Data formatting
• Configuration options

Steps

1. Write a search that generates two data series.

2. Run the search.
3. Select the Statistics tab below the search bar. The statistics table here should have three columns.
4. Select the Visualization tab and use the Visualization Picker to select the scatter chart visualization.
5. (Optional) Use the Format menu to configure the visualization.

Example

An analyst creates a scatter chart to track recent earthquake locations, magnitude, and depth.

This search generates a Statistics table with three columns. The first column shows earthquake location values. The
second column represents earthquake magnitude values, plotted on the x-axis. The third column represents earthquake
depth values, plotted on the y-axis.

34
source="earthquake.csv" | table place mag depth

Use Simple XML to build more complex scatter charts. For more information see the Area, Bar, Column, line, and Scatter
Charts and Scatter chart specific properties entries in the Chart Configuration Reference.

Bubble chart
Use a bubble chart to visualize multiple series data in three dimensions. Bubble position represents two dimensions of the
data series. Bubble size represents the third dimension.

Data formatting

To create a bubble chart, start with a search that generates multiple data series. Use this syntax to generate the series.

... | <stats_command> <y-axis_field> <x-axis_field> <bubble_size_field>

A single group-by field in the query generates a visualization with all bubbles in the same color. To get series colors with
the stats command, use two group-by fields. This generates a bubble for each unique combination of those two fields.
The value of the second field determines the series color.

Configuration options

Bubble chart configurations include the following options. Use the Format menu to adjust these settings.

• Minimum and maximum bubble marker size

• Axis titles
• X-axis label rotation and truncation
• Axis scale, interval, minimum and maximum values
• Enable or disable drilldown. When drilldown is enabled, users can click on a bubble or legend to open a search in
a new window. The search uses values from the selected element.

Create a bubble chart

Prerequisites
Review the following details about building column and bar charts.

• Data formatting
• Configuration options

35
Steps

1. Write a search that generates three data series.

2. Run the search.
3. Select the Statistics tab below the search bar. The statistics table here should have four columns.
4. Select the Visualization tab and use the Visualization Picker to select the bubble chart visualization.
5. (Optional) Use the Format menu to configure the visualization.

Example

This search aggregates earthquake events by location. It generates data series representing the magnitude, depth, and
count for each earthquake location.

source="earthquake.csv" | stats count by place, mag, depth

The search generates a bubble chart where the x-axis and y-axis plot magnitude and depth. The bubble size indicates the
relative count value for a particular location.

Chart display issues

This topic covers display issues using chart visualizations.

Searches with non-transforming commands

You cannot render charts using searches that do not include transforming commands, such as the following options.

chart
timechart
stats
eval

For more information, see About Transforming commands and searches in the Search Manual.

Time charting

You can only plot time-based data using the timechart command. If you try to plot a time-based series using any other
transforming search command, the chart treats the timestamp data as a series of strings.

36
Data truncation

To avoid browser performance impacts, Splunk software limits the the amount of data rendered in an individual chart.
When search results exceed limits, a message appears with the chart indicating that data was truncated.

Depending on your Splunk instance type, you can change default rendering behavior using configuration settings and/or
Simple XML. You can adjust Simple XML options in individual charts. Splunk Enterprise administrators can also add or
edit settings for all charts in the $SPLUNK_HOME$/etc/system/local/web.conf file.

Use the following table to compare limit configuration options.

Rendering Where to
In Setting Default
limit type configure
Total data points One chart charting.chart.resultTruncationLimit 50000 Simple XML

Data points per

One chart charting.data.count 10000 Simple XML
series

All charts in all No default. Specify to override

Total data points jschart_truncation_limit web.conf
browsers individual browser settings.

One or more of the following settings.

Charts in an • jschart_truncation_limit.chrome
Total data points 50000 web.conf
individual browser • jschart_truncation_limit.safari
• jschart_truncation_limit.firefox
• jschart_truncation_limit.ie11

Data series All charts jschart_series_limit 100 web.conf

Data points per

All charts jschart_results_limit 10000 web.conf
series

Simple XML data truncation options

You can adjust data truncation in individual charts using Simple XML.

Data point limit for one chart

You can configure the maximum number of points that can be plotted in a specific chart by editing the Simple XML for the
chart. In the <chart> element, edit the charting.chart.resultTruncationLimit property as described in Area, bar,
column, line, and scatter charts in the Chart Configuration Reference.

Data point limit per series in one chart

You can limit the number of search result data points rendered per series in a chart. Edit the charting.data.count Simple
XML setting to override the default value of 10000 data series.

Configuration file data truncation settings

Splunk Enterprise users can add or edit settings in $SPLUNK_HOME$/etc/system/local/web.conf to change rendering
behavior in all charts.

For information about editing web.conf settings, see How to edit a configuration file and the web.conf spec file in the
Admin Manual.

37
Data point limit for all charts in one or more browsers

The web.conf configuration file specifies the maximum number of points that can be plotted for charts in various browsers.
All browser limits default to 50000 data points.

You can override individual browser settings or add a jschart_truncation_limit setting in

$SPLUNK_HOME$/etc/system/local/web.conf to define a limit for all browsers. The jschart_truncation_limit overrides
any individual browser settings.

Note: The charting.chart.resultTruncationLimit Simple XML option overrides this limit in an individual chart.

Data series limit for all charts

You can limit the number of data series that charts can render. Add or edit the jschart_series_limit setting in
$SPLUNK_HOME$/etc/system/local/web.conf to override the default value of 100 data series.

If search results exceed this limit, a chart displays only the number of series that this limit allows. A warning message
appears to indicate that the chart is showing truncated search results. For example, if the jschart_series_limit is 40 and
a search returns 50 data series, a chart renders only the first 40 series.

Data point limit per series for all charts

Limit the number of search result data points rendered per series in all charts. Edit the jschart_results_limit setting in
$SPLUNK_HOME$/etc/system/local/web.conf to override the default value of 10000 data series.

Data series and data point limit precedence

In the case of an individual chart, if the jschart_series_limit and the charting.data.count Simple XML options combine
to indicate a number greater than the jschart_truncation_limit in web.conf, then data points per series are reduced to
meet the jschart_truncation_limit setting.

For example, you might have a jschart_series_limit of 10 and a charting.data.count limit of 100 in a chart. When
multiplied, these two settings indicate a 1000 total data point limit for the chart. If the js_chart_truncation_limit is 800,
however, then data points per series are reduced to meet the 800 total point limit.

To override the js_chart_truncation limit on all charts, you can use charting.chart.resultTruncationLimit Simple
XML option to change the limit for an individual chart.

Category limit

When you are plotting data by category, Splunk software limits chart label display. This limit differs for the horizontal axis
(X-axis) and the vertical axis (Y-axis).

The X-axis must have at least 20 pixels available for each label. The Y-axis must have at least 15 pixels available. If the
requisite pixels are not available, the labels do not display.

You can zoom into the X-axis to view labels that are hidden by the category limit. See Pan and zoom chart controls for
details.

38
Single Value

Overview
Use a single value visualization to show a metric and its context. Single value visualizations display results and context for
searches returning a discrete number.

A single value can be a count or other aggregation of specific events. For instance, this visualization shows sales for a
popular lemonade stand.

A caption, unit notation, and range colors add emphasis. A trend indicator to the right of the value and a sparkline
underneath show how data has changed over time.

To start working with single value visualizations, see the following topics.

• Generate a single value

• Customize a single value

Generate a single value

Learn how to write a query to generate a single value visualization.

Single value visualizations work best for queries that create a time series chart using the timechart command or
aggregate data using the stats command.

Use timechart to generate a single value

This search and visualization use timechart to track daily errors for a Splunk deployment.

index=_internal source="*splunkd.log" log_level="error" | timechart count

To access sparklines and trend indicators, it is important that the search includes the timechart command. Using
timechart means that time series data becomes available to sparkline and trend indicator processing.

39
 If you use the stats command as part of a full timechart query, the visualization does not include a sparkline or trend
indicator.

Use stats to generate a single value

If you use the stats command to generate a single value, the visualization shows the aggregated value without a trend
indicator or sparkline. As an example, this query and visualization use stats to tally all errors in a given week.

index = _internal source = "*splunkd.log" log_level = "error" | stats count

Queries and time ranges for single values

It is important to set up the single value query that best drives the visualization that you expect.

• Search for a single value to avoid unexpected results in the visualization. In the Dashboard Editor, you can select
single value visualizations even if a search returns multiple values. In this case, the single value visualization uses
the value in the first cell of the results table.

• The time range picker and the query command work together to generate the results for a single value
visualization. A query using stats results in a visualization showing the aggregated total of results in the time
range. A query using timechart generates a visualization showing the most recent result within that range.

For details about the stats command, see stats in the Search Reference.

For details about the timechart command, see timechart in the Search Reference.

Queries to generate a sparkline and trend indicator

A sparkline appears by default below a single value generated with the timechart command. It shows increases and
decreases in a metric over the time range you specify in a search.

This visualization shows results for a search over the past week's data. Using the time range picker to select Week to
date means that the sparkline reflects the data changes over the last seven days.

This visualization shows results for the same search over the past day's data. Using the time range picker to select Today
means that the sparkline shows data changes over the past twenty-four hours.

40
A trend indicator appears to the right of a single value generated with the timechart command. It shows recent data
behavior over a customizable time range. The trend indicator is composed of a number and an arrow to represent what
happened most recently in the data.

Depending on data behavior, the trend arrow can point up, down, or directly to the side to show no change. By default, the
trend indicator value evaluates to the difference between the two most recent values in the results. You can change the
trend time window in the Format menu's General settings panel or by adjusting the span parameter for timechart. if you
use the Compared to field in the Format menu, it will override the span command you specified in the search string. For
example:

index=_internal source="*splunkd.log" log_level="error" | timechart count

Customize a single value

Learn how to configure single value visualization components.

Value ranges and colors

Colors can emphasize range values or trends in a single value visualization. In the Format menu, you can choose whether
to use colors. If you opt to use colors, you can select whether to color by value or trend.
Note: For queries using stats to aggregate results, only the color by value option is available.
You can also adjust the color mode to change whether colors appear in the foreground or background.

Depending on the color mode you choose, coloring a single value generated with timechart by value means that the
sparkline and trend indicator appear black (for foreground color) or white (for background color).

Color by value

Coloring by value is available for single value visualizations generated with either stats or timechart. Color by value
means that the single numeric value in the visualization changes color based on the value the search generates and the
range for that value. For example, if you map a value range from 30-50 to the color yellow, then a single value of 35
appears yellow.

41
You can adjust value ranges for the query to change how different results are visualized. By default, there are five ranges
and colors for coloring by value. You can add or remove ranges, modify the values for each range, and change the colors
associated with each range using the Format menu.

For example, this timechart generated single value visualization shows color by value and has the background color
mode selected.

Color by trend

Coloring by trend is available for single values generated with a query including the timechart command. Coloring by
trend means that the sparkline and trend indicator in this visualization change color to show changes in data. By default,
positive changes make the sparkline and trend indicator appear green, while negative changes make them red. When
results show no change, the trend color is black.

For example, this visualization shows color by trend and has the foreground color mode selected.

You can reverse the settings for trend colors in the Format menu. You can also specify a different trend time window for
the visualization.

Migration for rangemap settings in existing single value visualizations

Existing single value visualizations might use a query with the rangemap command to configure ranges and colors.

By default, a single value visualization has this color mapping configuration for ranges.

• low: green
• guarded: blue
• elevated: yellow
• high: orange
• severe: red

Caution: As support for the rangemap command is limited, it is not recommended for building new single value
visualizations. Queries using rangemap currently generate a single value, but UI configurations override the query-based
settings.

For existing single value visualizations, it is recommended to migrate rangemap command settings out of the query.
Replace query-based settings with equivalent range and color settings in the Format menu Color panel.

Captions and units

Use the Format menu's General options panel to add a caption for a single value visualization. You can specify a unit of
measurement and its position in the Number Format panel. For instance, you can add $ before a value reflecting sales in
the United States or MB after a value tracking data transfers.

42
Note: If you are migrating from earlier versions of Splunk software and your visualization includes Before and After labels,
the Format menu shows prompts to update label and unit text using the Unit and Caption fields.

Captions

Captions add descriptive context to a single value visualization. To add a caption, select the Format menu General panel.
Use the caption text field here to enter a description. Captions appear below the single value.

Units

Units can indicate standard measurements for single values. To add a unit to the visualization, select the Format menu
Number Format panel and edit the Unit field. You can choose whether a unit appears before or after the value. It is
recommended to keep unit text to five characters or fewer. Use a caption for longer text.

Number formatting

If you are working with a large single value or one that requires precision, you can change the number formatting for the
visualization. In the Format menu Number Format panel, you can choose thousand separators or different degrees of
decimal precision.

Drilldown

By default, drilldown is disabled for single value visualizations. You can enable drilldown functionality using Simple XML.
For more information about drilldown, see Drilldown behavior in this manual.

43
Gauges

Using gauges
Use a radial, filler, or marker gauge to map a value in relation to a range. A gauge visualization provides metric status and
range information that you can interpret quickly. You can use a real-time search to generate a gauge tracking value
fluctuations as they occur.

Data formatting

To generate a gauge, use a search that returns a single numerical value. For example, use a search that returns an event
count for events with a specific field value in a time period or real-time window. If you are using a real-time search, the
range marker moves to show the metric changing over time.

Gauge types

All gauge types visualize a single aggregated metric.

For example, this search aggregates error log events.

index=_internal source="*splunkd.log" log_level="error" | stats count as errors

The search can generate any of the available gauge types.

Radial gauge

A radial gauge includes a round value scale and a pointer to show the current value on the scale. The current value also
appears at the bottom of the gauge. You can configure a radial gauge to use specific colors for each value range in the
scale.

If the search generates a current value outside of the configured minimum or maximum range, the gauge pointer bounces
at the lower or upper end of the value scale.

Filler gauge

44
A filler gauge includes a value scale container that fills and empties as the current value changes. The fill level shows
where the current value is on the value scale.

The current value also appears inside the filled portion of the gauge. The container appears empty for a value lower than
the minimum and full for a value higher than the maximum.

Marker gauge

A marker gauge shows value ranges and colors with a marker that moves to indicate the current value.

If the search generates a current value outside of the configured minimum or maximum range, the marker bounces at the
lower or upper end of the value scale.

Configuration options

Use the Format menu to configure gauge style and color ranges.

Color ranges

Use the Format > Color Ranges panel to select manual or automatic color range configuration. By default the first three
ranges are green, yellow, and red.

Set the Color Ranges handling to Automatic if the query includes the gauge command for range configuration.

If the query includes gauge, Format menu range configurations override the gauge command settings in the query.

Create a gauge visualization

Prerequisites
Review the following details about building column and bar charts.

• Data formatting
• Gauge types

45
 • Configuration options

Steps

1. Write a search that generates a single aggregated value.

2. Run the search.
3. Select the Visualization tab and use the Visualization Picker to select a radial, filler, or marker gauge.
4. (Optional) Use the Format menu to configure the visualization.

46
Maps

Mapping data
There are several options for visualizing data that includes geographic information.

A Choropleth map uses shading to show relative metrics, such as population or election results, for predefined geographic
regions. For example, this image shows a map of the United States. States have lighter or darker shades of two different
colors. One color represents low values for a particular metric. The darkest shading in this color represents the lowest
values. The other color represents high values for the same metric. The darkest shading in this color represents the
highest values. Shading fades as the values approach the middle of this range.

You can also create other visualizations with geographic data, such as cluster maps or charts.

Getting started

Use the following topics to learn about creating Choropleth maps and other geographic visualizations.

• Generate a Choropleth map

• Configure a Choropleth map
• Cluster maps

See also

To learn about geospatial lookups, see Configure geospatial lookups in the Knowledge Manager Manual.

Generate a Choropleth map

Geographic visualizations aggregate events by location. Location names might already be included in events. You can
also use a search to generate locations from signed degree latitude and longitude coordinates in each event.

Choropleth maps have specific data and component requirements. A search uses the data and components to generate a
Choropleth map.

Data and component requirements

47
Use normalized data

Choropleth maps work best when data is normalized. Normalization adjusts data to more accurately reflect the metric that
you are visualizing. For example, a Choropleth map can compare sales performance in two cities with significantly
different populations. Using normalized data to generate this map means that the population difference alone does not
determine how the cities' sales compare on the map.

Components for building geographic visualizations

These components are required for creating geographic visualizations. Check the following table before running a search.

Component Description Available options

Either:
Geographic visualizations start with data that includes location
Data with geographic • Data with signed degree latitude and
information for each event. This data can come from several
coordinates longitude coordinates.
sources, including a sensor or forwarded data source.
• Data with location names that match the
location names in a lookup.

Either:
A lookup table file defines region boundaries, such as the
• Built-in files for the United States,
boundaries of each state in the United States.
geo_us_states, and countries of the
Lookup table file
world, geo_countries.
From the Search and Reporting home page, select Settings >
• Upload a KML or KMZ file for other
Lookups > Lookup table files to review available files.
places. Upload the file to the Lookup
table files manager page.

Either:
A geospatial lookup matches coordinates to region definitions in
• Built-in lookups for the United States and
the lookup table file.
for world countries.
Geospatial lookup
• Create a geospatial lookup. For more
From the home page, select Settings > Lookups > Lookup
information, see Configure geospatial
definitions for available lookup definitions.
lookups in the Knowledge Manager
Manual.

Create the search

A search coordinates data, a transforming search, and a geospatial lookup to build a Choropleth map or other geographic
visualization. The following steps show you how to create a Choropleth map search. Optionally, you can use the steps to
generate other visualizations for geographic data.

Prerequisites
Make sure that you have the correct data and components for building a geographic visualization. See Data and
component requirements.

Steps
Run each portion of the search as you build it to ensure that it is working correctly. Depending on the visualization you are
creating and the components that you have, some steps are optional.

48
1. Indicate an events data source.
source=my_data.csv |
Start with an events data source that has signed degree geographic coordinates or location name fields. For
example, here is one record in a .csv file listing retail locations for a business. This file includes latitude and
longitude coordinates for each record.
Store Number,Name,Facility ID,Products,Services,Country,Latitude,Longitude
12345,Buttermilk Tea Shop,54321,"Tea, Cake",Wi-Fi,US,43.031873,-71.073203

2. (Optional) Add a lookup.

lookup geo_us_states longitude as Longitude, latitude as Latitude |
If the events data already includes location name or featureId fields, you can skip this step.

The lookup uses the geographic coordinates to generate featureId and featureCollection fields for events. A
featureId is the name of a geographic feature that includes a particular set of geographic coordinates, such as a
state or city name. By default, the featureCollection is the lookup definition name.

After adding the lookup and running the search, check the available Selected Fields or Interesting Fields to
ensure that featureId is listed. If it is not, then the lookup did not generate the featureId from the geographic
coordinates. Fields are case-sensitive.

3. Use a transforming command.

stats count by featureId |
Aggregate the data using the lookup's geographic output field, featureId. If you did not need a lookup, aggregate
by the location name field already in the events data.

4. (Optional) Select and configure a visualization.

You can use the search to generate non-map visualizations for geographic data. If you are not building a
Choropleth map, the search is complete. Use the Visualization Picker to select a visualization type. Use the
Format menu to configure it.

5. (Optional) Use geom to complete the Choropleth map search.

If you are building a Choropleth map, add the geom command and pass in the lookup name for the
featureCollection parameter.

Depending on whether the events include a featureId field, select one of the following options.
Events have Next steps Example
1. Use the lookup to which those fields
featureId fields geom geo_us_states
belong.

1. Use a lookup that contains the location

names. For example, if events have US
Location names, no featureId field.
state names, use geo_us_states. geom geo_us_states
This might be the case if you skipped
featureIdField="State"
the lookup earlier.
2. Indicate which events field geom should
interpret as the featureIdfield.

49
For more information and advanced options for Choropleth map queries, see geom in the Search Reference.

Example search

The full search assembled in the previous steps looks like this.

source=my_data_source.csv
| lookup geo_us_states longitude as Longitude, latitude as Latitude
| stats count by featureId
| geom geo_us_states
Configure a Choropleth map
To review or change Choropleth map configuration, select the Format menu and one of the following settings panels.

General

Adjust general settings including drilldown, initial geographic coordinates, and zoom on scroll.

Colors

Color mode and data bin settings determine how a Choropleth map uses color to visualize data. Select a color mode and
configure data bins in the Colors panel.

Color modes

Color
Description and use cases Example
mode

Color regions by category value. For example, you can track top product purchases by state. If
Categorical
multiple states have the same top product, they share a color.

Color regions with light to dark shades of a single hue. This mode helps you find regions where a
Sequential
metric is particularly high.

Color regions in light to dark shades of two distinct hues. This mode shows regions where a
Divergent metric is particular high or low. Shading fades as regional metrics approach the middle of the
range.

50
Data bins

Aggregated data values are divided into a set of bins. Each bin corresponds to a specific value range and has a unique
color or shade. You can adjust the number of bins and bin color assignments for the selected color mode.

The Choropleth map legend to the right of the map shows bins with their colors and value ranges.

Shapes

A shape corresponds to an individual region on a Choropleth map. For example, each state in a Choropleth map of the
United States is a shape. You can adjust shape opacity and borders.

Tiles

Tiles represent map background features, such as oceans. Show or hide tiles.

Cluster maps
Use the cluster map visualization to plot aggregated values on a map.

51
Data formatting

To generate a cluster map, use the geostats command. The geostats command generates events that include latitude
and longitude coordinates for markers. It is similar to the stats command, but provides options for zoom levels and cells
for mapping.

For more information, see geostats in the Search Reference.

Configuration options

Use the Format menu to adjust the following cluster map components.

• Tile appearance and source

• Cluster marker appearance
• Zoom on scroll behavior

Drilldown

You can also enable or disable cluster map drilldown in the Format menu.

Cluster map drilldown lets users open a secondary search by clicking on a map cluster. The secondary search uses the
geographic boundaries of the selected cluster.

Example

The following search generates a map showing California earthquakes of magnitude greater than 3 for the past 30 days.

index=main mag>3 | geostats latfield=latitude longfield=longitude count

52
When a user clicks on a cluster indicating earthquake data, a search launches using the latitude and longitude boundaries
of that cluster.

index=main mag>3 | search latitude>=36.21094 latitude<36.56250 longitude>=-122.34375 longitude<-121.64062

53
Get Started with Dashboards

Dashboard overview
Create new dashboards or edit existing ones.

For a quick glance at the most common use cases and commands for creating dashboards, note that you can access the
Splunk Dashboards Quick Reference guide by clicking the link in Getting started.

The dashboard and form workflow

Working with dashboards includes one or more of the following tasks.

Build dashboards

• Create a new dashboard

• Add new visualizations to a dashboard

For more information on building dashboards, see Create a dashboard

Edit dashboards

• Add a panel to a dashboard

• Edit dashboard panels and panel visualizations
• Manage dashboard searches

For more information on editing dashboards, see Edit dashboards

Convert a dashboard to a form

• Add user inputs to a dashboard to convert it to a form

• Edit forms
• Work with user input settings

For more information on forms, see Create and edit forms

Customize Simple XML

• Edit Simple XML source code to customize a dashboard or form.

For more information on using Simple XML, see Editing Simple XML

Add interactive and dynamic behavior

• Use tokens to capture and transfer data.

• Add event handlers to implement dynamic behavior.

For more information on event handlers and tokens, see Use drilldown for dashboard interactivity and Token usage in
dashboards

54
Tools and frameworks

To build and edit dashboards, use one or more of the following tools and frameworks.

Dashboard editor user interface

Build and edit dashboards using the Splunk Web user interface.

Simple XML

Dashboards use Simple XML source code to define their content and behavior. You can use the dashboard editor in
Splunk Web to edit this source code.

To learn more, see Editing Simple XML.

Developer options

Splunk Enterprise users can implement additional dashboard customizations.

• Extend Simple XML using CSS and JavaScript.

• Convert a Simple XML dashboard to HTML and use JavaScript to implement customizations including inputs and
REST API access.

For more information, see the following Splunk developer portal resources.

• Convert Simple XML dashboards to HTML

• Modify dashboards using Simple XML
• About SplunkJS stack
• Web Framework overview

Dashboards converted to HTML have some editing limitations in Splunk Web. They also cannot be exported to PDF.

Examples

The Dashboard Examples app on Splunkbase provides many dashboard implementation examples, including source
code. Install the app to view and interact with the example dashboards.

Deprecated options

The following dashboard framework options are deprecated as of version 6.3.0.

Option For more information see

Advanced XML Advanced XML deprecation

Module System (Deprecated as part of Advanced XML). Advanced XML deprecation

Django Bindings Django Bindings Deprecation Notice

55
About the dashboard editor
Use the Splunk Web dashboard editor to create and edit dashboards. The dashboard editor provides access to an editing
user interface and Simple XML source code.

Editing user interface

You can create and update dashboards and panels in the editor user interface.

To learn more, see Create dashboards and Edit dashboards.

Source code editor

Use the dashboard editor to access and edit Simple XML source code.

The editor provides validation, error messaging, and warnings as you make changes.

Keyboard shortcuts
Keyboard shortcuts consistent with Ace code editor shortcuts are available in the dashboard editor.

You can format Simple XML source code by using Command + Shift + F on a Mac or CTRL + Shift + F on Windows.

56
Build and Edit Dashboards in Splunk Web

Create a dashboard
Dashboards are created in the context of a particular app. For example, if you are using the Search and Reporting app,
dashboards use this app context.

After you create a dashboard, you can modify its permissions to share or manage access for other users. You can also
modify the app context.

Steps

1. Use one of the following options.

From What to do
Dashboards page Click Create new dashboard

1. Select Save as > Dashboard panel

Saving a visualization 2. Click New to create a new dashboard using
this panel.
2. Provide a Title, ID, and Description for the dashboard.
3. Specify permissions.
4. Save the dashboard. Use one of the following options.
From Click
Dashboards page Click Create Dashboard

Saving a visualization Click Save

5. Add panels, convert the dashboard to a form, or edit dashboard content.

For more information, see the following topics.

• Add panels to dashboards

• Edit dashboards
• Create and edit forms
• Configure dashboard permissions

Working with dashboard panels

A dashboard contains one or more panels. Learn about the different panel types that you can use in a dashboard.

Inline panel

An inline panel contains a search. The search generates the results rendered in the panel visualization. You can edit an
inline search directly using the dashboard editor.

57
Panel from a report

Create a panel based on a report search and visualization.

You cannot modify the search string in the panel, but you can change and configure the visualization. If the report search
changes, the panel using that report updates accordingly.

Depending on your permissions, you can control whether the report is accelerated, scheduled, and embedded. You can
also change the report permissions.

Report user context

Reports in dashboard panels can run as the report owner or the report user. These settings can affect data visibility and
concurrent search limits.

Option Description Data visibility impact Concurrent search limit impact

If a dashboard containing a report-backed panel
Run the report using
loads multiple times simultaneously, it can impact the
the permissions of the A report run with owner permissions render
report owner's concurrent search limit. When the limit
user who created the search results that some users might not
Run as is reached, the report scheduler causes additional
report. otherwise have permission to see. In some
owner report search runs to be queued for later execution.
cases, you might want to provide this kind of
(default)
Scheduled reports access. In other cases, you might want to restrict
Dashboard users might see slower panel loading and
always run using report search result visbility.
the report owner might not be able to run searches
owner permissions.
and reports immediately.

Run the report with the

permissions of the user
viewing the dashboard. If the report accesses data that the current user When the report runs, it counts against the concurrent
Run as
does not have permission to see, the panel does search limit of the user loading the dashboard, not
user
Scheduled reports not render those results. the report owner.
cannot run with user
permissions.

Use scheduled reports for dashboard panels when possible

Back dashboard panels with scheduled reports whenever possible to reduce search processing load for your Splunk
deployment.

Benefits of scheduled reports

Not using scheduled reports can impact search processing loads and concurrent search limits. For example, If fifty users
access a particular dashboard, panels not backed by scheduled reports cause their reports to rerun fifty times.

Scheduled reports do not require the search to run each time a user loads the dashboard. Panels backed by scheduled
reports show results from the last scheduled run of the report.

Using real-time scheduled reports

To show dashboard users the most current results, back dashboard panels with real-time scheduled reports. This report
type runs in the background at all times. It does not launch a new report instance each time a user loads the dashboard.
Instead, it shows results for the currently running real-time scheduled report.

58
Prebuilt panel

Save and reuse Simple XML panels in multiple dashboards. You can display a prebuilt panel in a dashboard by using a
reference to the panel. Edit the panel directly to change the title, search, or visualizations in it.

Additional information

• To learn about using the dashboard editor to add or edit dashboard panels, see Add panels to dashboards.
• For more details on panel searches, see Searches power dashboards and forms.
• See Edit dashboards and Edit visualizations to learn more about editing panel visualizations.
• To learn about working with reports, see Create and edit reports and Schedule reports in the Reporting Manual.

Add panels to dashboards

Learn how to add and edit dashboard panels.

To learn about types of dashboard panels, see Working with dashboard panels.

Add panels using the Dashboard Editor

Add panels to a dashboard with the dashboard's Edit menu. Access the Edit menu directly from the dashboard or from
the list of dashboards on the Dashboards page.

1. Select Edit to open the dashboard editor.

2. Select Add Panel.
3. Expand one of the panel categories.
♦ New
♦ New from Report
♦ Clone from Dashboard
♦ Add Prebuilt Panel
4. (Optional) To search for specific panels, enter text in the Filter text box.
5. Select a panel and preview the selection.
6. Click Add to Dashboard.

Filter the search for available panels

Use filters in the search field to locate or create specific panels. The search looks for specified terms in existing
dashboards, panels, and reports. It provides results for new panels using the specified search terms, and links to existing
dashboards and panels containing the terms.

The following tips can help you with searching and filtering.

• Panel title or panel ID are useful items to search for.

• Use visualization element names, input types, chart types, and other keywords to filter a search. For example:

59
 ♦ Search for map to return results to dashboards implementing a map visualization or to create a new panel
with the map visualization.
♦ Search for multiselect for results with a multiselect form input.

• You can filter for multiple items, but all items must appear in the order that you specify in the search field.

Rearrange panels on a dashboard

Drag and drop panels to rearrange their position on a dashboard.

1. If you are not in edit mode for the dashboard, select Edit.
2. Select a panel and drag it to its new position.

Create an inline panel for a dashboard

When you create an inline panel, you select a visualization and specify a search for the panel.

1. Select Edit to open the dashboard editor.

2. Select Add Panel.
3. Expand the panel category New and select a visualization for the data.
4. (Optional) Enter a title for the panel.
5. Enter a search string that returns the data to display in the panel.
6. (Optional) Select Run Search to preview the search results.
7. Select a time range for the search.
8. Click Add to Dashboard.

Create a panel from a report

When you create a panel from a report, you select from a list of available reports.

1. Select Edit to open the dashboard editor.

2. Select Add Panel.
3. Expand the panel category New from Report to view available reports.
(Optional) Use the Filter option to search for specific reports. See Filter the search for available panels.
4. Select a report to view a preview of the report.
5. Click Add to Dashboard.

Clone a panel from another dashboard

You can clone a panel from another dashboard. The panel appears on your dashboard with the same editing capabilities
as the cloned panel.

1. Select Edit to open the dashboard editor.

2. Select Add Panel.
3. Expand the panel category Clone from Dashboard to view available reports.
(Optional) Use the Filter option to search for specific panels. See Filter the search for available panels.
4. Select and expand a dashboard. Select a panel to view a preview of the panel.
5. Click Add to Dashboard.

60
Create and add a panel by reference

You can create a panel that you can later add to dashboards by reference. This prebuilt panel is useful if you plan to
reuse it often in various dashboards.

There are two ways to create a panel that you can reference from other dashboards.

• Convert an existing panel to a prebuilt panel that you can reference.

• Create a panel in simple XML code from the Settings page.

Typically, you create the panel using the dashboard editor, and then convert it to a prebuilt panel. You can also create the
panel in simple XML code.

Convert an existing panel to a prebuilt panel

You can convert a panel to a prebuilt panel only if the panel does not contain a post-process search. A post-process
search is a search that uses the base attribute to reference another search.

1. In the dashboard containing the panel that you want to convert, select Edit > Edit Panels.
2. From the Options Menu for a panel, select Convert to Prebuilt Panel.
3. (Optional) In the dialog that opens, specify the following details.

♦ ID: The filename for the panel. Only alphanumeric characters, '-' character, and '_' are allowed.
♦ Panel Permissions: Select either Private or Shared in App.
Private: Only you have permissions to view and edit the panel.
Shared in App: The panel is available to view and edit by other users of the app.

Create a panel in Simple XML

If this is your first time working with Simple XML, see Editing simple XML. See also the Simple XML Reference for more
information on panel configurations.

1. From Splunk Web, go to Settings > User Interface > Prebuilt Panels.
2. In the Panels page, select New to open the Simple XML Editor.
3. In the Simple XML Editor, specify the following:

♦ Destination app: Select an app for the context of the panel.

♦ Prebuilt Panel ID: Enter a name for panel.
The name you enter is the filename on disk. Only alphanumeric characters, '-' character, and '_' are
allowed.
♦ Prebuilt Panel XML: Simple XML code to define a panel element.
The simple XML code for a reference panel contains only the <panel> element and its child elements.

Add a prebuilt panel to a dashboard

1. From the dashboard, select Edit > Edit Panels.

2. Select Add Panel.
3. Expand the panel category Add Prebuilt Panel to view the reference panels available.
(Optional) Use the Filter option to search for specific panels. See Filter the search for available panels.
4. Select a reference panel to view a preview of the panel.
5. Click Add to Dashboard.

61
Convert a prebuilt panel to an inline panel

You can convert a prebuilt panel to an inline panel. The prebuilt panel cannot contain a post-process search. A
post-process search is a search that uses the base attribute to reference another search.

The conversion of a prebuilt panel to an inline panel lets you customize the search and visualization.

1. From a dashboard, select Edit > Edit Panels.

2. From the prebuilt panel you want to convert, click the Options Menu and select Convert to Inline Panel.

Edit a panel title

Panels and visualizations have separate titles.

You can specify a title when creating a panel. You can also use the dashboard editor to change panel titles, with one
exception. Prebuilt panel titles cannot be edited in the dashboard editor. See Edit a prebuilt panel for more information.

Steps

1. Locate the panel that you want to edit in a dashboard.

2. Click Edit to open the dashboard editor.
3. Use one of the following options.

Option What to do
1. Next to Edit Dashboard at the top left of the page, make sure that the UI editor is selected.
Editing user interface
2. Click the panel title that you want to edit and change the text.

1. Next to Edit Dashboard at the top left of the page, make sure that the Source editor is
selected.
Edit Simple XML
2. Locate the <title> element inside the <panel> that you want to edit.
3. Change the panel title text.
4. Click Save.

Edit a prebuilt panel

Use the Prebuilt Panels page to access a panel source code editor.

Steps

1. From the home page, navigate to Settings > User Interface > Prebuilt Panels.
2. Locate the panel that you want to edit and select Edit.
3. Edit the Simple XML source code.
4. Click Save. The panel is updated in dashboards that include it by reference.

Delete a panel from a dashboard

You can delete a panel from a dashboard using the Dashboard Editor or by editing the simple XML code.:

• From the Dashboard Editor, in panel-editing mode, click the Options menu for a panel and select Delete.
Or you can click the Delete icon, X, which is in the upper right corner of the panel.

62
 • In simple XML source code, delete the <panel> element and its contents.

Edit dashboards
Use the dashboard editor to customize dashboard panels, layout, or add interactivity.

Open the dashboard editor

1. From the Dashboards listing page, open the dashboard that you want to convert.
2. Click Edit to open the dashboard editor.
3. Select UI or Source to change the editing mode.
4. (Optional) Preview dashboard edits as you make them and click Save to save changes. Click Cancel at any point
to discard changes.

Change dashboard panel layout

You can change dashboard layout to prioritize specific panels or make room for additional content.

1. From the Dashboards listing page, open the dashboard that you want to convert.
2. Click Edit to open the dashboard editor.
3. Drag and drop panels to reposition them.

Edit a panel search

Update the search driving a particular dashboard panel.

Depending on the panel search type, editing options vary.

All search
Reports Inline searches and inline pivots
types

• View and edit the report in a new window.

• Open the report search in a new window.
• Edit the search, specifying a new inline search or
• Edit the • Clone to an inline search or pivot.
pivot.
title. • Select a different report for the panel.
• Convert the inline search or pivot to a report.
• Delete the • Select the visualization specified in the report for
• Specify an automatic refresh interval delay and
search. this panel.
indicator option.
• Specify an automatic refresh interval delay and
indicator option.
Steps

1. From the Dashboards listing page, open the dashboard that you want to edit.
2. Click Edit to open the dashboard editor.
At the top right of each panel, editing icons appear. The first editing icon represents the search for the panel. The
search icon varies to represent the type of search being used.
3. Select the search icon to view configuration options for the search.
4. Select the search configuration that you want to change. Depending on the option you select, additional

63
 configuration dialogs or windows might open.
5. After editing the search, click Save to save changes to the dashboard.

Edit a panel visualization

Use the dashboard editor to edit a panel visualization for panels that are not generated with pivot or pivot report searches.

If you are working with visualizations generated from pivot or pivot report searches, you can use the Pivot Editor. See
Design pivot charts and visualizations with the Pivot Editor for details.

Prerequisites

• Review Data structure requirements for visualizations for details on generating search results in the correct format
for a visualization.
• See Properties available from the Visualization Editor to review visualization configurations.

Steps

1. From the Dashboards listing page, open the dashboard that you want to edit.
2. Click Edit to open the editing dashboard.
At the top right of each panel, editing icons appear. The second icon represents the Visualization Picker. The icon
varies to represent the visualization type. The third editing icon represents the visualization Format menu.
3. (Optional) Use the Visualization Picker to select a different visualization. Make sure that the panel search
generates results in the correct format for the new visualization. You can select any visualization, but the panel
search results might not render if they are not formatted for the selected visualization.
4. (Optional) Use the Format menu to configure the visualization.
5. Click Save to save changes to the dashboard.

Edit dashboard source code

Edit dashboard Simple XML source code to customize settings that are not accessible from the user interface. The
dashboard source code editor provides interactive validation as you make updates.

Prerequisites

• For information about editing Simple XML source code, see About editing Simple XML.

Steps

1. From the Dashboards listing page, open the dashboard that you want to edit.
2. Select Edit to open the dashboard editor.
3. Click Source to open the dashboard XML source code editor.
4. Edit the source code.
5. (Optional) Observe that the editor provides automatic tag closing and validation. The editor displays validation
warning or error messages as needed. Hover over a warning or error icon next to a line of source code to view

64
 the message for that line.
6. (Optional) Validation warnings and errors disable the Save button. If the button is disabled, correct any code with
validation warnings or errors.
7. If there are no warnings or errors, the Save button is enabled. Click Save to save the source code edits.

Edit a prebuilt panel

Prebuilt panels cannot be edited in the dashboard editor. Use the Prebuilt Panels page to access a panel source code
editor.

Steps

1. From the home page, navigate to Settings > User Interface > Prebuilt Panels.
2. Locate the panel that you want to edit and select Edit.
3. Edit the Simple XML source code.
4. Click Save. The panel is updated in dashboards that include it by reference.

Additional resources

• To learn about creating or editing visualizations in a dashboard, see Edit Visualizations.

• For details on converting a dashboard to a form and working with forms, see Create and edit forms.

Edit visualizations
Edit a visualization to configure its search, type, appearance, and behavior.

Visualization component editing

You can edit visualizations in the dashboard editor or on the Search page. In either location, you can adjust the following
visualization components.

Visualization
Description
components
Search string Use the dashboard search editor or the search bar to change the query driving the visualization.

Use the Visualization Picker to select a visualization type. Ensure that the query generates results in the proper
Type
structure for the selected visualization.

Format and behavior Use the Format menu to adjust appearance, drilldown, and other settings for the visualization's user interface.
Caution: Changing visualization settings in the dashboard editor can overwrite related token settings and behavior. If you
are using tokens to configure part of a dashboard or form, use caution when updating related elements in the dashboard
editor. For example, if a form input configures chart legend placement, selecting a legend placement in the Format menu
overwrites the dynamic token setting from the input. In this case, the input remains in the dashboard but no longer
configures legend placement.

65
Visualization editing workflow

The workflow for editing a visualization search, type, or format is slightly different depending on whether you are editing in
the dashboard editor or the Search page.

Dashboard editing permissions

Write permission is required for editing dashboard panels. By default, you have write permission for any dashboard that
you create. However, you might have read-only access to other dashboards. Users with the admin role can change editing
permissions.

Edit visualizations in the dashboard editor

1. In the Search and Reporting app, select the Dashboards tab.

2. Locate the dashboard to edit. Use one of the following options.
Option Additional steps for this option
Select Edit. None

Click on the dashboard name to view it. After the dashboard opens, select Edit.
3. In the panel you are editing, locate the icons for editing the search, visualization type, and format. Select the icon
for the component you are editing.
4. Edit the selected visualization component.

Edit visualizations on the Search page

1. In the Search and Reporting app, select the Search tab.

2. Enter a query.
3. When results are available, select the Visualization tab.
4. To edit the visualization, use one of the following tools.
Tool Description
Visualization Picker Change the visualization type.

Format menu Change the visualization format and behavior. Format options vary by visualization type.

Search bar Edit the query and rerun it to refresh the visualization.

Using the Format menu

Format menu configurations are applied immediately to visualizations.

• Each edit that you make is saved to the visualization. You can see each change in the visualization and make
adjustments as you go.
• Edits are reflected in the dashboard Simple XML source code as they are made.
• Click and drag the Format menu to move it anywhere on the screen.
• Close the Format menu or click anywhere outside of it to exit and save changes.

66
Additional resources

Formatting and other options vary by visualization type. To compare visualizations, see the Visualization reference. See
also Chart Configuration Reference.

For information on using Pivot to edit visualizations, see Design pivot charts and visualizations with the Pivot Editor.

Create and edit forms

Let users select or filter content by converting a dashboard to a form. A form is a dashboard that includes one or more
inputs, such as radio buttons or a checkbox.

Workflow for creating forms

The typical workflow for creating forms includes the following steps. Some steps are optional and you do not have to
complete them in this order.

• Create a dashboard and add one or more inputs to convert it to form.

• Configure the inputs by specifying options available to users, default behavior, and how to handle user selections.
• Work with tokens that capture selected values from the input. Modify searches and other content to use the token
values.
• Make any additional input configurations depending on the input type.
• Adjust input and panel layout.

Add inputs to convert a dashboard to a form

Forms are dashboards with interactive user inputs for selecting or filtering content. When you add an input to a
dashboard, the top-level source code element changes from <dashboard> to <form>.

Steps

1. From the Dashboards listing page, open the dashboard that you want to convert.
2. Click Edit to open the dashboard editor.
3. Select one or more inputs from the Add input list. As soon as you select an input, the dashboard is converted to
a form.
4. (Optional) Drag and drop inputs to rearrange them.
5. (Optional) Drag an input into a specific panel. Use tokens to make the input control only this panel.
6. Click Save to save changes to the form.

Tokens in form inputs

Use tokens to respond to user selections dynamically.

When you add an input to a form, a unique token is generated for the input. You can use this token to change panel
content based on what users select. For example, use a token in the panel search to modify the results that the panel
visualization shows. Or, change the panel label or drilldown behavior using the token.

The following examples show you typical options for using tokens in a form input.

67
Reference a token in a search

In this example, a dashboard has one panel. The panel search aggregates events for all sourcetypes.

index=_internal | timechart count by sourcetype

Add interactivity by converting the dashboard to a form. Add a text input to let users specify a sourcetype to filter the
events in the visualization.

1. From the dashboard, click Edit to open the dashboard editor.

2. Select Add input > Text to add a text input. The dashboard is converted to a form.
3. Observe that the input appears at the top of the form. A label and token are generated for the input.
4. Click the editing icon to open the input editor.
5. Change the label text to "Sourcetype".
6. Change the token name to sourcetype_token to make it more specific. Token names should be unique within the
form.
7. Update the panel search string to use the value that the token captures from user input. This search uses the
specified sourcetype to filter events.
index=_internal sourcetype=$sourcetype_token$ | timechart count
Observe the $[token name]$ syntax used to refer to the token in the search.
8. Click Apply and Save to save the updates to the form.

The form now contains a text input for users to specify a sourcetype to show in the visualization. Before users specify a
sourcetype, the visualization does not render because the token has not captured a value to use in the search. After a
sourcetype is entered in the text field, the search uses this value to generate results and the visualization renders.

Add a time input to a form

A time input lets users apply a time range to filter the events shown in one or more panels.

Add the time input and update panel searches to incorporate the user specified time range.

1. From the dashboard or form, click Edit to open the dashboard editor.
2. Select Add Input > Time.
3. (Optional) Select the input editing icon and update the input label and token name.
4. (Optional) Click Apply to save the input updates.
5. For each panel where you want the time input to apply, make the following changes.
1. Click the search editing icon.
2. Select Edit search.
3. For Time Range Scope select Shared Time Picker. If there is more than one time input in the form,
each shared time picker is listed with the unique token for its time input. Select the shared time picker that
includes the token for the input that you want to use.
6. Click Save to save the panel search updates.
7. Click Save to save the form updates and exit the dashboard editor.

Apply time inputs to panels

A form can have one or more time inputs. Depending on the behavior you want, a time input can be used globally for all
panels or only for specific panels.

68
Global time picker
When you create a time input using the dashboard editor, a token is generated automatically for the input. If you delete
this token, the time input becomes global. Each panel in the form that does not specify a time range or another time input
uses the global time picker.

When configuring a panel search time range, you can select Shared Time Picker (global) to apply this input.

Token-based time picker

When configuring a panel search time range, you can select a shared time picker that includes a specific token name.
Use the token name for the input that you want to apply to the panel search.

Panel searches that do not use time inputs

You can specify an explicit time range for a panel search or use other token values if you do not want to apply a time input
to a particular panel.

Configure input value handling

You can configure how input values populate a form.

Submit token values when the page loads

To submit token values when the page loads, enable autorun behavior.

1. From the dashboard, click Edit to open the dashboard editor.

2. Select the Autorun dashboard check box.
3. Click Save to save the form update.

Submit token values when an input changes

By default, inputs are configured to submit token values whenever users make a new selection. To change this behavior,
follow these steps.

1. From the dashboard, click Edit to open the dashboard editor.

2. Select the input to edit.
3. Clear the Search on change check box to disable this behavior, or select the check box to enable it.
4. Save input and form changes.

Add a Submit button input

Add a Submit button to a form to let users control when input selections are submitted. This can be helpful for managing
how often panels or forms with multiple inputs update. Typically, Search on change is disabled for inputs if you use a
"Submit" button in the form.

You cannot change the position of the form Submit button.

1. From the dashboard, click Edit to open the dashboard editor.

2. Select Add Input > Submit.
3. Disable Search on change behavior for inputs as needed and save input updates.
4. Click Save to save form updates.

69
Specify initial and default input values

Handle cases where user input values are not available.

Default
Use a default value for an input when users do not make a selection.

Initial
Use an initial value for text inputs only. The initial value appears only when the form page loads. If a user clears
the text field, the initial value does not reappear and the token value is set to an empty string.

If you specify both an initial and default value for a text input, only the default value applies.

Specify multiple options for inputs

Several form input types can include multiple static or dynamically populated options.

• check box
• dropdown
• link list
• radio
• multiselect

All of these inputs display multiple options, while multiselect and check box inputs let users choose multiple values. The
following tasks show you how to configure options for each of these inputs.

Specify static options

The following example shows you how to specify multiple static options. The example uses a dropdown input but it applies
to any multi-option input.

1. From a dashboard, select Add Input > Dropdown.

2. Select the edit icon for the input. Select Static Options.
3. Specify a name and value for the first option.
4. For each additional option, Click Add Option and specify the name and value for the option.
5. (Optional) Scroll to the Default field and specify a default value.
6. (Optional) Drag and drop the options to rearrange them.
7. Click Apply to save input changes.
8. Click Save to save dashboard changes.

Specify dynamic options

Use a search to generate option labels and values dynamically.

70
These steps show you how to configure a dynamically populated dropdown. They do not include steps for updating the
search to use the token value from the input.

1. From the dashboard or form, add a line chart panel that uses the following search.
index=_internal | timechart count

2. Add an input to let users filter the panel visualization for a particular sourcetype.
♦ Click Edit to open the dashboard editor.
♦ Select Add Input > Dropdown.
3. Configure the input.
♦ Select the input editing icon.
♦ Select Dynamic options.
♦ Add the following search to generate input labels and values.
index=_internal | stats count by sourcetype | eval label=sourcetype." (".count.")"
♦ Observe that the search aggregates events by sourcetype and generates a label field that combines
sourcetype names and event counts.
♦ Use the search result fields for input labels and values. Specify the following fields. Field for Label: label
Field for Value: sourcetype
4. Click Apply to save input updates.
5. Click Save to save form changes.

Users can now view sourcetype names and event counts in the dropdown.

Handle multiple value selections

Multiselect and check box form inputs let users select multiple values.

This example panel includes a check box for users to specify sourcetypes to render in the chart.

71
Search to generate multiple selected values

To handle one or more user selected values in a multiselect or check box, use a search that generates results for one or
more values.

To specify the source type values in the above form, build a search string indicating the values to return. For this example,
the following search string allows the selection of multiple values for source types:

(sourcetype="splunkd" OR sourcetype="splunk_web_access" OR sourcetype="splunkd_access")

The search driving the panel accesses the token value of check box and multiselect differently than the other form inputs.
Use the submitted modifier to the token.

index=_internal $src_type_tok$ | chart count by sourcetype

The Input Editor provides editing fields to specify multiple values for selection in a check box or multiselect. The table
below describes these fields and provides example values that build the following search string:

(sourcetype="selected value" OR sourcetype="selected value" OR ... )

Editor Example
Description
Field Values
String prefixed to the value of the input element.
Token Prefix (
For multiple selections, this is typically an open parenthesis to enclose the string
selecting the values.

String appended to the value of the input element.

Token Suffix )
For multiple selections, this is typically a close parenthesis to enclose the string
selecting the values.

String prefixed to the value of the input element. Can be a regular expression.
Token Value Default value is an opening double quote (").
sourcetype="
Prefix
Typically, this is the opening part of a sub-string that selects the multiple values.

"

72
 Editor Example
Description
Field Values
Token Value String appended to the value of the input element. Can be a regular expression.
Suffix Default value is an closing double quote (").

Typically, this is the closing part of a sub-string that selects the multiple values.

A string placed between each selected value. Typically, you specify " OR " or "
AND " using upper case. Do not specify the quote marks, but specify a space
character before and after the string.
Delimiter OR
Default value: " "

Default value does not include quote marks. The quote marks show that the
default value is a space character.
The following procedure shows how to enable multiple selections for a check box or multiselect input.

1. From the dashboard, click Edit to open the dashboard editor.

2. Select Add Input. Select either Checkbox or Multiselect.
3. Specify Label, Search on Change, and Token.
4. Specify choices as described in Specify choices with static options and Specify choices with dynamic options.
5. Build the multiselect search string using the editing fields in the above table.
(Recommended) Use the preview feature to verify the multiselect search string.
6. (Optional) Specify a default value.
7. Click Apply. Click Done.

Form input examples

This section provides an example of each form input, with a list of the key fields for implementing the example.

Check box

This example uses the check box input to indicate which source types to display in a timechart. A populating search
specifies the available options to select. Three source types are selected by default:

splunk_web_access
splunk_web_service
splunkd

This example enables Search on Change. The form loads when a selection is made.

The panel displays results in the default column chart, using the following base search. The visualization references the
input values using the value specified for Token. In this example, the token name is src_type_tok.

index=_internal $src_type_tok$ | timechart count by sourcetype

73
General settings

Specify the Label for the input and the Search on Change behavior. This example enables search on change.

Token options

Use the Token Options to specify the value returned by the check box input.

For the Token field, specify a name for the token that returns the value. The base search for the visualization references
this token. In this example, specify src_type_tok.

Use the following fields to build the search for the returned value. The Preview field in the Input Editor updates as you edit
these fields.

• Token Prefix
• Token Suffix
• Token Value Prefix
• Token Value Suffix
• Delimiter

The example values listed in the table below build the following search string:

(sourcetype="splunkd" OR sourcetype="splunk_web_access" OR ...)

After you dynamically create the check boxes, from the Default field, select the check boxes that are enabled by default.

Static options

Use the static options to explicitly define the Name and Value of the check boxes for the input.

This example leaves the static options blank. It uses a populating search to define the check boxes for the input.

Dynamic Options

Reference a report or define an inline populating search to define the check boxes for the input.

This example uses the following inline search:

| metadata type=sourcetypes index=_internal

74
The example runs the search against all time.

Use field names to specify a name/value pair for the check boxes. This example specifies the sourcetype field for both
Field for Label and Field for Value.

Example values for check box input

This table lists the example values for the check box input example.

Editor Field Example Values

General

Label Source Types (Check Box)

Search on Change Enabled

Token Options

Token src_type_tok

splunk_web_access
Default splunk_web_service
splunkd

Token Prefix* (

Token Suffix* )

Token Value Prefix* sourcetype="

Token Value Suffix* "

Delimiter* OR

Dynamic Options

Content Type Inline Search

Search String | metadata type=sourcetypes index=_internal

Time Range All time

Field for Label sourcetype

Field for Value sourcetype

*These fields build the search string that dynamically create the check boxes. For the Delimiter field, be sure to
specify an opening and closing space.
Dropdown input

This example uses a dropdown input to indicate which source types to display as a time chart. The panel displays results
as a bar chart, using the following base search.

index=_internal sourcetype=$src_type_tok$ | timechart count by sourcetype

The token $src_type_tok$ references the values specified by the dropdown.

75
The example uses static options to define choices for the dropdown.

The example specifies splunk for Token Prefix. Each selected value prefixes the token prefix to the value.

There is a default value for the dropdown.

The example relies on a Submit button to run the search. Changes to the selection do not apply until you click the Submit
button.

Editor Field Example Values

General

Label Source Types (Dropdown)

Search on Change Not specified

Token Options

Token src_type_tok

Default Daemon

Token Prefix splunk

Static Options

Name : Value Daemon : d

Name : Value Web Service : _web_service

Name : Value Web Access : _web_access

Name : Value Daemon Access : d_access

Multiselect

This example uses a multiselect input to indicate which source types to display in a timechart. The panel displays results
in the default column chart, using the following base search.

index=_internal $src_type_tok$ | timechart count by sourcetype

76
The example uses static options to define choices for the dropdown.

Two source types are selected by default:

Daemon
Web Access

This example enables Search on Change. The form loads when a selection is made.

For a multiselect input, you define multiple values to select by building the following search string.

(sourcetype="splunkd" OR sourcetype="splunk_web_access" OR ...)

The token $src_type_tok$ references this search string in the search that drives the panel contents. The fields that build
the search string are indicated in the table below.

Editor Field Example Values

General

Label Source Types (Multiselect)

Search on Change Enabled

Token Options

Token src_type_tok

Daemon
Default
Web Access

Token Prefix* (

Token Suffix* )

Token Value Prefix* sourcetype="

Token Value Suffix* "

Delimiter* OR

Static Options

Name : Value Daemon : splunkd

Name : Value Web Service : splunk_web_service

77
 Editor Field Example Values
Name : Value Web Access : splunk_web_access

Name : Value Daemon Access : splunkd_access

Name : Value Version : splunk_version

Name : Value Error : splunkd_stderr

*These fields build the search string that supplies the token value. For the Delimiter field, be sure to specify an
opening and closing space.
Radio input

This example uses a radio input to indicate which source types to display as a time chart. The panel displays results as an
area chart, using the following base search.

index=_internal sourcetype=$src_type_tok$ | timechart count by sourcetype

The token $src_type_tok$ references the values specified by the dropdown.

The example uses static options to define choices for the dropdown.

There is a default value for the radio input.

This example enables Search on Change. The form loads when a selection is made.

Editor Field Example Values

General

Label Source Types (Radio)

Search on Change Enabled

Token Options

Token src_type_tok

Default Web Service

Static Options

Name : Value Daemon : splunkd

Name : Value Web Service : splunk_web_service

Name : Value Web Access : splunk_web_access

Name : Value Daemon Access : splunkd_access

78
Text input

This example uses a text input to indicate which source types to display as a time chart. The panel displays results as a
pie graph, using the following base search.

index=_internal sourcetype=$src_type_tok$ | timechart count by sourcetype

The token $src_type_tok$ references the values specified in the text input.

This example specifies an initial value of splunkd* without specifying a default value. Upon initial load, the seed value is
applied. The form reloads when you specify a new value.

Because there is no default value, an empty text input does not return any results.

Editor Field Example Values

General

Label Source Types (Text input)

Search on Change Enabled

Token Options

Token src_type_tok

Default Not specified

Initial splunkd*
Time input

This example shows how to use a time input to specify time ranges for a panel in a form. The form contains a radio input
to indicate which source types to display as a time chart. The panel displays results as a column chart, using the following
base search.

index=_internal sourcetype=$src_type_tok$ | timechart count by sourcetype

79
The examples specifies time_input_tok to reference the time input in a panel.

In the Panel Editor, select Edit Search String. From the Time Range Scope dropdown, select Shared Time Picker
(time_input_tok).

The default value for the time input is Last 7 days.

The example enables Search on Change for the time input. The form loads when a new time range is selected.

Editor Field Example Values

General

Label Time Input

Search on Change Enabled

Token Options

Token time_input_tok

Default Last 7 days

Convert a dashboard to HTML

Splunk Enterprise users can implement additional behavior and appearance customizations by converting a dashboard to
HTML.

Learn about creating and editing HTML dashboards on the Splunk developer portal.

• See Convert Simple XML dashboards to HTML for information and procedures.
• See About file precedence and caching to learn about caching and refreshing Splunk assets, including HTML
files.

Limitations to HTML dashboards

There are some limitations on dashboards converted to HTML.

• HTML dashboards cannot be exported to PDF.

• The Splunk Web dashboard editor cannot be used to edit HTML source code for converted dashboards.

80
Create Dashboards with Simple XML

Editing Simple XML

You can use interactive editors to create and edit dashboards without having to edit Simple XML source code. However,
some advanced dashboard features are not available from interactive editors. You can access these features by editing
the underlying simple XML code.

Edit dashboard source code

Edit dashboard Simple XML source code to customize settings that are not accessible from the user interface. The
dashboard source code editor provides interactive validation as you make updates.

Prerequisites
If you are unfamiliar with Simple XML, review the following information before you edit source code.

• Dashboard and form structure and elements in Dashboards and forms

• Available options and elements in the Simple XML Reference

Steps

1. From the Dashboards listing page, open the dashboard that you want to edit.
2. Select Edit to open the dashboard editor.
3. Click Source to open the source code editor.
4. Edit the source code.
The editor provides automatic tag closing and validation. It also displays warnings or error messages as needed.
Hover over a warning or error icon next to a line of source code to view details.
5. If the Save button is disabled, correct any code with validation warnings or errors. Otherwise, click Save to save
your edits.

Special characters in XML files

Some characters have special meaning in Simple XML files. To prevent the source code parser from treating them as
special characters, wrap them in <![CDATA[]]> tags.

<![CDATA[
<content_with_special_characters>
]]>
You can also escape these characters using HTML entities.

HTML
Character Description
Entity
' apostrophe &apos;

? question mark &quest;

' plus sign &plus;

" quote &quot;

81
 HTML
Character Description
Entity
< left angle bracket &lt;

> right angle bracket &gt;

& ampersand &amp;

Read-only access to dashboard Simple XML code

Access a read-only version of dashboard source code by appending the showsource query parameter to the dashboard
URL. See the following example.

https://host:port/en-US/app/my_app/my_dashboard?showsource

Note: Read-only source code access is available only for Simple XML dashboards. Read-only HTML or Advanced XML
source code is not accessible using the URL.

Additional information

Before you edit Simple XML, review the following resources.

• Simple XML dashboard and form structure in Anatomy of dashboards and forms.

• The Simple XML Reference and the Chart Configuration Reference provide details on Simple XML elements and
options.

Splunk Enterprise users can edit Simple XML using a third-party editor. This option is not available in Splunk Cloud
Platform. See Using a third party XML editor.

Searches power dashboards and forms

Splunk searches power dashboards, forms, and the visualizations of data that they contain. 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.

Overview of searches in dashboards

There are several ways to access searches that drive the content of a dashboard.

Inline searches

An inline search is a search you create within a dashboard or visualization.

You can provide inline searches that are global to a dashboard or provide inline searches for each visualization in a
dashboard. Searches that are global to a dashboard require post-process searches in visualizations. The post-process
searches further modify the data returned from the global search.

See Inline search example.

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

See the example, Reference a search from a report.

Generate searches with Pivot

Use Pivot 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.

Searches to populate form inputs

You can use searches to dynamically populate choices for form inputs such as radio buttons, drop-down lists, and check
boxes.

See the example, Populate choices for form inputs.

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. In the code snippet below, a token had been previously defined
with $series_tok$.

index=_internal source=*metrics.log group="per_sourcetype_thruput" series=$series_tok$ | table sourcetype

eps, kb, kbps

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. See also Token usage in dashboards.

Simple XML elements for searches in dashboards

Use the <search> element and its child elements to define searches in simple XML. The <query> element provides the
actual search string. The <earliest> and <latest> elements provide the bounds of the search.

Use the search element in the following contexts:

• A search that drives the data for a visualization.

• Global search for a dashboard or form.

Use a post-process search in visualizations to reference the global search.

• Post-process search for a visualization.

The post-process search modifies the data returned from a global search.

• A search that provides the labels and value for inputs such as a radio input or dropdown input.

See the Search element in the Simple XML Reference for details on writing searches in simple XML code.

83
Search examples in simple XML

This topic provides examples of using the <search> element in the following contexts:

• Inline search.
• Reference to a search from a report.
• Populate choices for an input.
• Post-process searches that access a global search.

Inline search example

The search in this example drives the data in the visualization.

• <query>
Provides the search string.
• <earliest> <latest>
Define the bounds for the search.

84
<dashboard>
<label>Visualization with inline search</label>
<description></description>
<row>
<panel>
<chart>
<title>Radial gauge</title>

<search>
<!-- Inline search query -->
<query>
index=_internal source="*splunkd.log"
( log_level=ERROR OR log_level=WARN*
OR log_level=FATAL OR log_level=CRITICAL )
| stats count as log_events
| rangemap field=log_events low=1-100 elevated=101-300 default=severe
</query>

<!-- search bounds -->

<earliest>-7d@h</earliest>
<latest>now</latest>
</search>

<option name="charting.chart">radialGauge</option>
<option name="charting.chart.rangeValues">[0,300,600,900]</option>
</chart>
</panel>
</row>
</dashboard>
Reference a search from a report

The searches in this example reference a report.

You cannot modify the search from the dashboard, but you can modify the time bounds and the visualization for the
search results. If the search in the report changes, the visualization based on that report updates to include the changes.

You can also reference a scheduled report in a dashboard panel. When the dashboard loads, panels backed by
scheduled reports load instantly with the results from the last scheduled run of the report. This practice can improve the
dashboard user experience in cases where you have searches that ordinarily take a long time to run. It can also reduce
the search processing load on your system if you have dashboards that are loaded frequently by large numbers of users.
See "Add panels to dashboards" in this manual.

The report in this example uses a bar chart for the visualization and displays results for the last seven days. The panel on
the left displays the search from the report. The panel on the right uses the same search from the report, but modifies the
time bounds and visualization.

<search> element code:

• <search ref ="[name]">

References the report.
• <earliest> <latest>
Modify the time bounds.

85
<dashboard>
<label>Search from report</label>
<row>
<panel>
<title>Original report</title>
<chart>
<title>Source types time chart</title>

<search ref="Source types time chart" />

</chart>
</panel>
<panel>
<title>Modified time bounds and visualization</title>
<chart>
<title>Source types time chart</title>

<search ref="Source types time chart">

<!-- Modify time bounds -->

<earliest>-30d@d</earliest>
<latest>now</latest>

</search>

<!-- Change visualization -->

<option name="charting.chart">column</option>

</chart>
</panel>
</row>
</dashboard>
Populate choices for form inputs

Use the search element to dynamically populate the choices for the following form inputs:

• Check boxes
• Drop-down list
• Multiselect input
• Radio buttons

Caution: Do not use a real-time search for a populating search. The input choices do not update correctly when
using a real-time search.

86
The search in this example compares static and dynamic definition for choices. The drop-down list uses a populating
search to define the choices.

• Populating <search>
Returns fields to use for the label and value of the choices.

• <fieldForLabel> <fieldForValue>
Child elements to the <input> element. These elements specify the fields to use to populate choices for the
dropdown.

<form>
<label>Populate an input with a search</label>
<description>Events Filtered by User and Sourcetype</description>
<!-- Do not need a Search Button. Inputs search when changed -->

<fieldset autoRun="true" submitButton="false">

<!-- Static definition of choices -->

<input type="radio" token="username_tok" searchWhenChanged="true">
<label>Select a User:</label>

<!-- Define the default value -->

<default>All</default>

<!-- Hard-code the choices -->

<choice value="*">All</choice>
<choice value="-">-</choice>
<choice value="admin">Admin</choice>
<choice value="nobody">Nobody</choice>
<choice value="splunk-system-user">Splunk System User</choice>
</input>

<!-- Dynamic definition of choices -->

<input type="dropdown" token="sourcetype_tok" searchWhenChanged="true">
<label>Select a Sourcetype:</label>
<prefix>sourcetype="</prefix>

87
 <suffix>"</suffix>

<!-- Define the default value -->

<default>splunkd</default>

<!-- Hard-code the choice for "All" -->

<choice value="*">All</choice>

<!-- Define the other choices with a populating search -->

<search>
<query>
index=_internal | stats count by sourcetype
</query>
</search>
<fieldForLabel>sourcetype</fieldForLabel>
<fieldForValue>sourcetype</fieldForValue>
</input>

</fieldset>
<row>
<panel>
<!-- Use tokens from the <input> elements in the panel title -->
<title>
Input selections: (radio) "$username_tok$", (dropdown) $sourcetype_tok$
</title>

<chart>

<!-- search for the visualization, references the input tokens-->

<search>
<query>
index=_internal user=$username_tok$ $sourcetype_tok$ | timechart count
</query>
<earliest>-24h@h</earliest>
<latest>now</latest>
</search>
</chart>

</panel>
</row>
</form>
Post-process searches

Sometimes you end up with a dashboard running searches that are similar. You can save search resources by creating a
base search for the dashboard. Panels in the dashboard use a post-process search to further modify the results of a base
search. The base search can be a global search for the dashboard or any other search within the dashboard.

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. See transforming commands and searches in the
Search Manual.

Be aware of the limitations for post-process searches that arise from the following causes:

• Base searches returning more than 500,000 events.

• Splunk Web time-out from search operations that exceed 30 seconds to complete.

See Post process limitations for details on these limitations and other cautions about using post-process searches. The
topic Post-process examples provides guidance on constructing post-process searches.

88
Post-process limitations

Post-process searches have limitations. If you do not use a transforming base search, these limitations can cause data
truncation or performance issues.

Search result count limit

In non-transforming base searches, the Splunk platform retains only the first 500,000 events returned. A post-process
search does not process events in excess of this 500,000 event limit, silently ignoring them. This results in incomplete
data for the post-process search. A transforming base search helps avoid this limitation.

Note: This search result retention limit matches the max_count setting in limits.conf. This setting defaults to
500,000.

Timeout
If the post-processing operation takes too long, it can exceed Splunk Web client's non-configurable timeout value of 30
seconds. This can result in a timeout due to an unresponsive splunkd daemon/service. This scenario typically happens
when you use a non-transforming search as the base search.

Avoid base searches that return raw events

Avoid using a base search without transforming commands. If a base search returns raw events in excess of event
limitation, incomplete data might be passed to post-process searches. Use transforming commands in the base search to
avoid the event limitation. See 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 is referenced only in the post-process search becomes null in all rows, thus
returning zero results.

Avoid this problem by using transforming commands in the base search.

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

Incomplete data

If the base search is a non-transforming search that 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 results.

89
Post-process examples

Post-process works best when you reformat results from a base search that uses transforming commands.

This lets you create tables and charts according to specific criteria. For example, you can create different visualizations
and reports from the same data set. You can also do further aggregation on the original report.

Basic post-process example

This example uses transforming commands for the base search, post-processing the results differently:

Base search
index=_internal source=*splunkd.log | stats count by component, log_level

Post process 1 (event count by log_level)

| stats sum(count) AS count by log_level

Post process 2 (error count by component)

| search log_level=error | stats sum(count) AS count by component

<dashboard>
<label>Dashboard with post-process search</label>

<!-- Example uses stats transforming command -->

<!-- This limits events passed to post-process search -->
<search id="baseSearch">
<query>
index=_internal source=*splunkd.log | stats count by component, log_level
</query>
</search>

<row>
<panel>
<chart>
<title>Event count by log level</title>

<!-- post-process search -->

<search base="baseSearch">
<query>
stats sum(count) AS count by log_level
</query>
</search>

90
 </chart>
</panel>
<panel>
<chart>
<title>Error count by component</title>

<!-- post-process search -->

<search base="baseSearch">
<query>
search log_level=error | stats sum(count) AS count by component
</query>
</search>

<option name="charting.chart">bar</option>
</chart>
</panel>
</row>
</dashboard>
Chained post-process example

Chain two or more post-process searches together. The following example shows how to link one post-process search to
another one.

<search id="baseSearch">
<query>index=_internal</query>
<earliest>-60m@m</earliest>
<latest>now</latest>
</search>

<search base="baseSearch" id="post_process_1">

<query>sourcetype=splunkd</query>
</search>

<search base="post_process_1" id="post_process_2">

<query>stats count</query>
</search>
Complex post-process example

For more complex base searches that include statistical aggregations such as percentiles, standard deviations, and even
averages, it is better to use summary indexing commands in the base search. This facilitates building the post-process
searches. Some examples of summary indexing search commands include:

◊ sistats
◊ sitimechart
◊ sitop
◊ sichart
◊ sirare

The summary index equivalents provide more flexibility for post-process searches. See Use summary indexing for
increased reporting efficiency and About transforming commands and searches.

Base search
index=_internal | eval event_size=len(_raw)
| sistats count min(event_size) avg(event_size) max(event_size)
by source sourcetype

91
Post process 1
| stats count

Post process 2
| stats avg(event_size) by sourcetype

Post process 3
| stats count by sourcetype

The base search reports event size (min, avg, max) by source and sourcetype for the _internal index. Use the sistats
count with the various group-by clauses. You lose the benefits of map-reduce in distributed search if you do not include
these.

<dashboard>
<label>Dashboard with post process using summary indexing</label>

<!-- Use summary indexing transforming command -->

<search id="baseSearch">
<query>
index=_internal | eval event_size=len(_raw)
| sistats count min(event_size) avg(event_size) max(event_size)
by source sourcetype
</query>
</search>

<row>
<panel>
<single>
<title>Total event count</title>

<!-- post-process search -->

<search base="baseSearch">
<query>stats count</query>
</search>

<option name="beforeLabel">Total events: </option>

</single>
</panel>
<panel>
<chart>
<title>Average event size by source type</title>

92
 <!-- post-process search -->
<search base="baseSearch">
<query>stats avg(event_size) by sourcetype</query>
</search>

<option name="charting.axisY.scale">log</option>
</chart>
</panel>
<panel>
<chart>
<title>Event count by source type</title>

<!-- post-process search -->

<search base="baseSearch">
<query>stats count by sourcetype</query>
</search>

<option name="charting.axisY.scale">log</option>
</chart>
</panel>
</row>
</dashboard>
Form with post-process search for inputs

You can use a post-process search to dynamically populate inputs to a form. The following example shows a form with
two inputs. The drop-down list, which selects an index to search, defines the choices statically. The drop-down list to
select a source type statically defines the default choice but uses a post-process search to dynamically define the other
choices.

93
Base search for populating the source type dropdown
index=_internal | stats count by sourcetype

Post process for dropdown input

| search sourcetype=splunkd*

<form>
<label>Post Process in Form Inputs</label>

<!-- Global search for post process by dropdown input -->

<!-- Search uses stats command to limit results -->
<search id="searchInput">
<query>index=_internal | stats count by sourcetype</query>
<earliest>-60min</earliest>
<latest>now</latest>
</search>

<fieldset submitButton="false">

<!-- Select an index from two static choices -->

<input type="dropdown" token="index_tok" searchWhenChanged="true">
<label>Select an index to search</label>
<choice value="_internal">Internal</choice>
<choice value="*">All public indexes</choice>
<default>_internal</default>
</input>

<!-- Dynamically populate choices -->

<input type="dropdown" token="sourcetype_tok" searchWhenChanged="true">
<label>Select a source type</label>

<!-- default choice is all sourcetypes -->

<choice value="*">All sourcetypes</choice>
<default>*</default>

<!-- Post-process search to dynamically populate choices -->

<search base="searchInput">
<query>search sourcetype=splunkd*</query>
</search>
<fieldForLabel>sourcetype</fieldForLabel>
<fieldForValue>sourcetype</fieldForValue>

</input>
<input type="time" token="time_tok" searchWhenChanged="true">
<label></label>
<default>
<earliest>-24h@h</earliest>
<latest>now</latest>
</default>
</input>
</fieldset>
<row>
<panel>
<chart>
<title>Chart</title>
<search>
<query>
index=$index_tok$ sourcetype=$sourcetype_tok$ | timechart count
</query>

94
 <earliest>$time_tok.earliest$</earliest>
<latest>$time_tok.latest$</latest>
</search>
</chart>
</panel>
</row>
</form>

Troubleshoot referenced real-time searches in search head clusters

In a search head clustering (SHC) deployment, if you are referencing a real-time saved search in a dashboard on a
search head, the real-time search might not continue to stream data after initial results are returned.

There are two workarounds for this issue.

Option Example dashboard source code Performance considerations

<search>
This type of search runs only when users view the
Use an inline real-time search <query>index=_internal | stats count
dashboard. However, a new real-time search
in the dashboard panel </query>
spawns for each user that accesses the dashboard
instead. <earliest>rt-5m</earliest>
from the search head or another member.
<latest>rtnow</latest>
</search>

Create a scheduled saved

search.
<search>
Only one instance of the saved search runs at the
<query> | loadjob
Use the loadjob command scheduled time regardless of the number of users
savedsearch="admin:search:SavedSearch"
in an inline panel search to accessing the dashboard.
</query>
update the dashboard with
</search>
the saved search results.

Additional search resources

If you are new to the Splunk platform and the search processing language (SPL), start with the Search Tutorial. This
tutorial introduces you to the Search and Reporting application. The tutorial guides you through adding data to your
Splunk deployment, searching your data, and building simple reports and dashboards.

The Search Manual includes detailed information about creating and optimizing searches, retrieving events, specifying
time ranges, and using subsearches.

The Search Reference is a reference guide for the Search Processing Language (SPL). The Search Reference contains a
catalog of the search commands with syntax, descriptions, and examples.

Dashboards and forms

Use dashboards and forms to visualize, organize, and share data insights.

Dashboards and forms have one or more rows of panels. Each panel contains a visualization, such as chart, table, or
map. In each panel, a search generates data for the visualization.

Forms are different from dashboards because they include <input> elements, such as text boxes or radio buttons, for
user interactions. You can configure elements in a form, such as a panel, to respond to user input by customizing the

95
searches that drive visualizations or changing other behavior.

For more details on building a <dashboard> or <form>, see the Simple XML Reference.

Anatomy of dashboards and forms

See the Simple XML Reference for complete information on dashboard and form element hierarchy.

Element Description
top-level element <dashboard> or <form>

Title <label> (Optional)

Description <description> (Optional)

Global search is for use with post-process searches. Post-process searches have limitations. See Post-process
limitations.
Global search

<search id="[identifier]">
<fieldset>
<input>
<text>

Form inputs (Forms <checkbox>

only) <dropdown>
<multiselect>
<radio>

<search> (to populate input choices)

Each row contains one or more panels.
Rows
<row>
Each panel contains an optional title, optional inputs, and one or more visualizations. See Dashboard panels for the
types of panels available.
Panels

<panel>
A visualization displays data returned from a search.
Visualizations
<chart> <event> <map> <single> <table>
A search for a visualization.

<search id="[identifier]"> Base search for post-process searches.

Search
<search base="[id]"> Post-process search referencing a base search.

<search ref="[report] [ app="[app name]" ]> Reference a search from a report. Reference to app is
optional.
Options Properties specific to a visualization.

96
 Element Description
<option name="[option name]">

Dashboard examples
This topic shows the source simple XML code behind dashboards. After you become familiar with the simple XML source
code, you can further customize the dashboard.

Basic dashboard

This example uses a few simple XML elements to create a basic dashboard.

<dashboard>
<!-- A title for the dashboard -->
<label>Basic Dashboard</label>

<!-- Provide a description -->

<description>Illustrate the basic structures of a dashboard</description>

<!-- Place panels within rows -->

<row>

<!-- This basic dashboard has only a single panel -->

<panel>

<table>
<title>Top Sourcetypes (Last 24 hours)</title>

<!-- A search powers the panel -->

<searchString>
index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)
</searchString>

<!-- Specify a time range for the search -->

<earliestTime>-24h@h</earliestTime>
<latestTime>now</latestTime>

<!-- Use options to further define how to display result data -->
<option name="wrap">true</option>
<option name="rowNumbers">true</option>

97
 </table>
</panel>
</row>

</dashboard>
Searches power panels

This dashboard illustrates the following searches:

• Inline search
• Search saved as a report
• Search from a prebuilt panel
• Inline search derived from a pivot

98
<dashboard>
<label>Searches power dashboards</label>
<description>Show the various searches to power a panel.</description>
<!-- This row contains three panels -->
<row>
<panel>
<table>
<title>(Inline Search) Top Source Types</title>
<!-- Inline Search -->
<search>
<query>
index=_internal | top limit=100 sourcetype
| eval percent = round(percent,2)
</query>
<earliest>-24h@h</earliest>
<latest>now</latest>
</search>
<option name="rowNumbers">true</option>
</table>
</panel>
<panel>
<chart>
<title>(Report) Top Source Types</title>
<!-- Reference to a search saved as a report -->
<search ref="Top Source Types Report" />
</chart>
</panel>
</row>
<row>
<panel ref="top_source_types_in_the_last_hour" app="search" />

<panel>
<chart>
<title>(Pivot) Game Purchases</title>

<!-- Inline search derived from a pivot -->

<search>
<query>
| pivot Buttercup_Games Successful_purchases count(Successful_purchases)
AS "Count of Successful purchases" SPLITROW product_name
AS "product name" SORT 100 product_name
</query>
</search>
<option name="charting.chart">pie</option>
</chart>
</panel>
</row>
</dashboard>
Use panels to visualize search results

You can display search results in a table or event listing, but also specify various charts. Use the <chart> element,
specifying the chart type with the <option> child element.

99
<dashboard>
<label>Use charts to visualize results</label>
<description>Show a selection of visualizations from the same search</description>
<row>
<panel>
<!-- Display results as a table. Uses an -->
<!-- inline search, equivalent to the <searchName> -->
<!-- specified for the other panels -->
<table>
<title>Top Source Types (Table)</title>
<search>
<query>
index=_internal | top limit=10 sourcetype
</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
</table>
</panel>
<panel>
<!-- display same search as various charts -->
<chart>
<title>Top Source Types (Bar)</title>
<search>
<query>
index=_internal | top limit=10 sourcetype
</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<!-- specify the chart type with this <option> to <chart> -->
<option name="charting.chart">bar</option>
<option name="charting.axisY.scale">log</option>
</chart>
</panel>
<panel>

100
 <chart>
<title>Top Source Types (Column)</title>
<search>
<query>
index=_internal | top limit=10 sourcetype
</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">column</option>
<option name="charting.axisY.scale">log</option>
</chart>
</panel>
</row>
<row>
<panel>
<chart>
<title>Top Source Types (Pie)</title>
<search>
<query>
index=_internal | top limit=10 sourcetype
</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">pie</option>
</chart>
</panel>
<panel>
<chart>
<title>Top Source Types (Line)</title>
<search>
<query>
index=_internal | top limit=10 sourcetype
</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">line</option>
<option name="charting.axisY.scale">log</option>
</chart>
</panel>
<panel>
<chart>
<title>Top Source Types (Area)</title>
<search>
<query>
index=_internal | top limit=10 sourcetype
</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">area</option>
<option name="charting.axisY.scale">log</option>
</chart>
</panel>
</row>
</dashboard>

101
Dashboard with real time search

You can build a real-time dashboard using the Splunk Dashboard Editor or coding the dashboard using simple XML. This
example shows how to code the simple XML.

To enable real-time searching, use the <earliest> and <latest> child elements to the <search> element. For example, if
you want to enable real-time searching and display the data in a table, specify the following:

<table>
<title>Look here for errors</title>
<search>
<query>
error OR failed OR severe
OR ( sourcetype=access_* ( 404 OR 500 OR 503 ) )
</query>
'''<earliest>rt</earliest>'''
'''<latest>rt</latest>'''
</search>
<fields>host, source, errorNumber</fields>
</table>
You can also set a window for the real-time dashboard. For example, if you want to show real-time events but only from
the last 5 minutes.

<table>
<title>Look here for errors during the last 5 minutes</title>
<search>
<query>
error OR failed OR severe OR ( sourcetype=access_* ( 404 OR 500 OR 503 ) )
</query>
'''<earliest>rt-5m</earliest>'''
'''<latest>rt</latest>'''
</search>
<fields>host, source, errorNumber</fields>
</table>
For more information on setting a search window, see Specify real-time time range windows in your search in the Search
Manual.

Specify custom colors for fields in charts

Use the charting.fieldColors Simple XML property to customize field colors in a chart. The colors you select are the
same each time the chart displays, regardless of other charts or color specifications in the dashboard.

For more details about this property, see charting.fieldColors in the Chart Configuration Reference.

Example

The following example shows how to specify colors for a chart showing error counts per sourcetype. The example uses
this search.

index = _internal log_level=* | stats count(eval(log_level="ERROR")) as ERROR count(eval(log_level="WARN"))

as WARN count(eval(log_level="INFO")) as INFO by sourcetype

Without charting.fieldColors, the visualization uses default field color mapping based on the order of values returned.
Here, ERROR appears blue.

102
To change the field color mapping, add the charting.fieldColors property to the dashboard's Simple XML source code.
For example, the charting.fieldColors configuration below defines these colors for each log level.

• INFO: green
• WARN: orange
• ERROR: red

<option name="charting.fieldColors">
{"ERROR": 0xFF0000, "WARN": 0xFF9900, "INFO":0x009900, "NULL":0xC4C4C0}
</option>

After adding charting.fieldColors, the chart now looks like this.

103
The following code implements a similar chart with custom field colors.

<panel>
<html>
Use <tt>eval</tt> function in the search to transpose
the value of the log_level field into individual fields
for <tt>charting.fieldcolors</tt>.
</html>
<chart>
<title>Field colors example</title>
<search>
<query>
index = _internal log_level=* | stats
count(eval(log_level="ERROR")) as ERROR
count(eval(log_level="WARN")) as WARN
count(eval(log_level="INFO")) as INFO
by sourcetype
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<option name="charting.axisY.scale">log</option>
<option name="charting.chart">column</option>
<option name="charting.fieldColors">
{"ERROR": 0xFF0000, "WARN": 0xFF9900, "INFO":0x009900, "NULL":0xC4C4C0}
</option>
<option name="charting.legend.placement">right</option>
</chart>
</panel>
Specify properties for visualizations

Simple XML provides a set of simple XML elements that define properties that can be applied to all visualizations. For
properties specific to certain types of visualizations, such as <chart> or <map>, use the <option> element to specify a
property.

The use of a specific element or the <option> element varies. Consult the Simple XML Reference and Chart Configuration
Reference for details on specifying panel properties.

The following table summarizes some of the elements available for all visualizations.

Tag Description
String

<title>
Add a title to your panel, such as Failed logins. The title displays at the top of the
panel.
Splunk time format
<earliest>
<latest> Restrict search results to a specific time window, starting with the earliest time and
ending with the latest time. Specify "rt" to enable real-time searches.

The following example of a panel with a <chart> element shows how to specify a title and an inline search. It restricts
search results to a 5 hour window and to three fields:

104
<dashboard>
<label>My dashboard</label>
<row>
<panel>

<table>
<title>Top users, five hours ago</title>
<search>
<query>
host=production | top users
</query>
<earliest>-10h</earliest>
<latest>-5h</latest>
</search>
<fields>host,ip,username</fields>
</table>

</panel>
</row>
</dashboard>

The following example specifies various properties with the <option> element for a <table>.

<dashboard>
<label>My dashboard</label>
<row>
<panel>

<table>
<title>Errors in the last 24 hours</title>
<search>
<query>
Errors in the last 24 hours
</query>
</search>
<option name="count">15</option>
<option name="displayRowNumbers">true</option>
<option name="maxLines">10</option>
<option name="segmentation">outer</option>
<option name="softWrap">true</option>
</table>

</panel>
</row>
</dashboard>

The following example specifies a column chart visualization, with display names for the X and Y axes.

<dashboard>
<label>My dashboard</label>
<row>
<panel>
<chart>
<search>
<query>
sourcetype=access_* method=GET | timechart count by categoryId
| fields _time BOUQUETS FLOWERS
</query>

105
 <earliest>-7d</earliest>
<latest>now</latest>
</search>
<title>Views by product category, past week (Stacked)</title>
<option name="charting.axisTitleX.text">Views</option>
<option name="charting.axisTitleY.text">Date</option>
<option name="charting.chart">column</option>
</chart>
</panel>
</row>
</dashboard>
Use the HTML panel to display static text

The HTML panel displays inline HTML. Use the HTML panel to add documentation, links, images, and other Web content
to a dashboard.

Content between the HTML tags is displayed according to the specified HTML formatting. Relative link references are
relative to the current view location. The HTML panel does not use any of the other general panel options and there are
no specific options to set for HTML.

For details on using HTML panels, refer to the <html> element entry in the Simple XML Reference.

In the example, the anchor tag accesses system reports using the special Splunk locator: @go?s=

. . .
<row>
<panel>
<html>
<p>This is an <i><b>HTML panel</b></i> providing links to system reports.</p>
<ul>
<li>
<p><a href="@go?s=Errors in the last hour">Errors in the last hour</a></p>
</li>
<li>
<p><a href="@go?s=Indexing workload">Indexing workload</a></p>
</li>
<li>
<p><a href="@go?s=License Usage Data Cube">License Usage</a></p>
</li>

106
 </ul>
</html>
</panel>
. . .
</row>
Configure a dashboard with dynamic drilldown

Dynamic drilldown allows you to specify another Splunk view or a web page to link to from a field in the search results. To
implement dynamic drilldown in a dashboard, do the following:

• Add a <drilldown> tag to the visualization listing search results.

• Within the <drilldown> tag, add one or more <link> tags

• Within each <link> tag, specify either a Splunk view or web site to link to.

• Specify the value of the results to use for the drilldown action. For example:
♦ Specify a field name that can be used as a sourcetype for a Splunk view.
♦ Specify a value that can be passed to a website.

See Dynamic drilldown in dashboards and forms for detailed examples.

Form examples
A form is similar to a dashboard, but provides an interface for users to supply values to one or more search terms,
typically using text boxes, dropdown menus, or radio buttons. A form shields users from the details of the underlying
search – it allows users to focus only on the terms for which they are searching and the results. The results can be
displayed in tables, event listings, or any of the visualizations available to dashboards.

This topic contains basic examples that show how to create forms. Refer to the Splunk Dashboard Examples app for
additional examples that use more robust source data. The examples show how to use tokens to pass values in forms.
See Token usage in dashboards for details on token implementation.

Basic form example

The user input to a form defines tokens for the selected values of the input. A search in the form uses the tokens to
specify the values to use in the search. The search accesses the value for the token using the '$...$' as a delimiter for the
token value.

For example, the following code snippet defines a dropdown that uses the sourcetype_tok token to represent the
selection by the user. It also defines the choices for the dropdown.

<input type="dropdown" token="sourcetype_tok">

<label>Select a source type</label>
<default>splunkd</default>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd_ui_access">splunkd_ui_access</choice>
</input>
The search in the form references the token. In the following code snippet, $sourcetype_tok$ represents the value from
the dropdown choice.

107
 <search>
<query>
index = _internal sourcetype=$sourcetype_tok$
| timechart count by sourcetype
</query>
<earliest>-7d</earliest>
<latest>-0d</latest>
</search>

Here is the simple XML implementing the form.

<form>
<label>Form example: source type time chart</label>

<!--autoRun means the search runs as soon as it is loaded. -->

<!-- Do not need a submit button -->
<fieldset autoRun="true" submitButton="false">
<input type="dropdown" token="sourcetype_tok">
<label>Select a source type</label>
<default>splunkd</default>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd_ui_access">splunkd_ui_access</choice>
</input>
</fieldset>

<row>
<panel>
<chart>
<search>
<query>
index = _internal sourcetype=$sourcetype_tok$
| timechart count by sourcetype
</query>
<earliest>-7d</earliest>
<latest>-0d</latest>
</search>
</chart>
</panel>
</row>
</form>

108
Form with time inputs example

You can add one or more time inputs to a form. If you add a single time input, a token for the time input is not necessary.
The time input drives the data for all searches in the form.

However if you add additional time inputs to a form, specify a token for each time input. The searches in the form
reference the tokens to indicate which time input to use.

The following code snippet creates a time input that defines a token for local use.

<input type="time" token="time_tok" searchWhenChanged="true">

<label></label>
<default>
<earliest>-24h@h</earliest>
<latest>now</latest>
</default>
</input>
Use the earliest and latest modifiers to the time input token when accessing the local time input.

<search>
<query>
index=_internal sourcetype=$sourcetype_tok$
| stats count as sourcetype</query>
<earliest>$time_tok.earliest$</earliest>
<latest>$time_tok.latest$</latest>
</search>
The following example uses a global timer that drives the Source Type Timechart panel. The Source Type Event Counter
panel contains a local time for that panel only.

109
<form>
<label>Form example: add time pickers</label>
<fieldset autoRun="true" submitButton="false">
<input type="dropdown" token="sourcetype_tok">
<label>Select a source type</label>
<default>splunkd</default>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd_ui_access">splunkd_ui_access</choice>
</input>

<!-- Global timer. Not token is necessary -->

<input type="time" searchWhenChanged="true">
<label>Select time range</label>
<default>
<earliest>-7d@h</earliest>
<latest>now</latest>
</default>
</input>

</fieldset>
<row>
<panel>
<title>Source type time chart</title>
<chart>
<search>
<query>index = _internal sourcetype=$sourcetype_tok$
| timechart count by sourcetype</query>
</search>
</chart>
</panel>
<panel>
<title>Source type event counter</title>

<!-- Local timer. Use tokens to access selected time. -->

<input type="time" token="time_tok" searchWhenChanged="true">
<label></label>
<default>
<earliest>-24h@h</earliest>
<latest>now</latest>
</default>
</input>

<single>
<search>
<query>
index=_internal sourcetype=$sourcetype_tok$
| stats count as sourcetype</query>

<!-- Use the earliest and latest modifiers to the time input token -->
<earliest>$time_tok.earliest$</earliest>
<latest>$time_tok.latest$</latest>

</search>
</single>
</panel>
</row>
</form>

110
Static and dynamic inputs to forms

The following form inputs require multiple choices for selection by the user. You can statically define the inputs or use a
search to dynamically populate the inputs to a form.

• Check box
• Dropdown
• Multiselect
• Radio

The search in the following example compares static and dynamic definition for choices. The dropdown uses a populating
search to define the choices.

• Populating <search>
Returns fields to use for the label and value of the choices.

• <fieldForLabel> <fieldForValue>
Child elements to the <input> element. These specify the fields to use to populate choices for the dropdown.

111
<form>
<label>Populate an input with a search</label>
<description>Events Filtered by User and Sourcetype</description>
<!-- Do not need a Search Button. Inputs search when changed -->

<fieldset autoRun="true" submitButton="false">

<!-- Static definition of choices -->

<input type="radio" token="username_tok" searchWhenChanged="true">
<label>Select a User:</label>

<!-- Define the default value -->

<default>All</default>

<!-- Hard-code the choices -->

<choice value="*">All</choice>
<choice value="-">-</choice>
<choice value="admin">Admin</choice>
<choice value="nobody">Nobody</choice>
<choice value="splunk-system-user">Splunk System User</choice>
</input>

<!-- Dynamic definition of choices -->

<input type="dropdown" token="sourcetype_tok" searchWhenChanged="true">
<label>Select a Sourcetype:</label>
<prefix>sourcetype="</prefix>
<suffix>"</suffix>

<!-- Define the default value -->

<default>splunkd</default>

<!-- Hard-code the choice for "All" -->

<choice value="*">All</choice>

<!-- Define the other choices with a populating search -->

<search>
<query>
index=_internal | stats count by sourcetype
</query>
</search>
<fieldForLabel>sourcetype</fieldForLabel>
<fieldForValue>sourcetype</fieldForValue>
</input>

</fieldset>
<row>
<panel>
<!-- Use tokens from the <input> elements in the panel title -->
<title>
Input selections: (radio) "$username_tok$", (dropdown) $sourcetype_tok$
</title>

<chart>

<!-- search for the visualization, references the input tokens-->

<search>
<query>
index=_internal user=$username_tok$ $sourcetype_tok$ | timechart count
</query>
<earliest>-24h@h</earliest>
<latest>now</latest>
</search>

112
 </chart>

</panel>
</row>
</form>
Create a form with a global search

You can create a form that uses a global search that drives the data in the various panels. This scenario is another form
of post-process search. You should be careful about using post-process searches because of various limitations. In many
cases, a post-process search is not always the most efficient way to use search resources. Read carefully the topic
Post-process searches. It discusses Post-process best practices and other factors to consider before implementing a
post-process search.

The following example shows a form with a global search.

The global search uses a transforming search command to avoid the 10,000 event limit for the number of events that you
can pass to a post-process search:

<search id="global_search">
<query>
index=_internal source=*splunkd.log | stats count by component, log_level
</query>
</search>
The values for the dropdown choices contain the post-process searches:

<fieldset autoRun="true" submitButton="false">

<input type="dropdown" token="stats_tok" searchWhenChanged="true">
<label>Select count by:</label>
<default>Log level</default>
<choice value="stats sum(count) AS count by log_level">Log level</choice>
<choice value="search log_level=error | stats sum(count) AS count by component">Component</choice>
</input>
The panel in the form accesses the selected choice using the token from the dropdown:

<search base="global_search">
<query>
$stats_tok$
</query>

113
 </search>
Here is the complete code for a form with a global search:

<form>

<label>Form with global search</label>

<search id="global_search">
<query>
index=_internal source=*splunkd.log | stats count by component, log_level
</query>
</search>

<fieldset autoRun="true" submitButton="false">

<input type="dropdown" token="stats_tok" searchWhenChanged="true">
<label>Select count by:</label>
<default>Log level</default>
<choice value="stats sum(count) AS count by log_level">Log level</choice>
<choice value="search log_level=error | stats sum(count) AS count by component">Component</choice>
</input>

<input type="time">
<default>Last 7 days</default>
</input>
</fieldset>
<row>
<panel>
<chart>
<option name="charting.chart">bar</option>
<search base="global_search">
<query>
$stats_tok$
</query>
</search>
</chart>
</panel>
</row>
</form>
Using a third party XML editor
In most cases, you use the Splunk Web dashboard editor to edit Simple XML. See About the dashboard editor to learn
more.

If you are using Splunk Enterprise, you can also use a third-party editor to work with dashboard source code files in your
deployment.

Splunk Cloud Platform users cannot use a third-party editor because access to dashboard source code files is not
available. If you have Splunk Cloud Platform, use the dashboard editor in Splunk Web.

Source code files for dashboards and forms

Dashboard and form source code files can include the following.

• Simple XML
• JavaScript
• CSS

114
 • Static HTML and image files imported by reference

File usage requirements

File system write access

You must have write access to the Splunk deployment file system to access the Simple XML files as well as supporting
CSS and JavaScript files. If you do not have write access, check with an administrator.

Dashboard source file permissions

After copying dashboard source files, makes sure that you can read and write to them. Read and write permissions on the
files are defined separately from dashboard user access permissions.

File directories and locations

Use the local directory for source code files

When you edit Simple XML in the dashboard editor, source code file changes are written to the /local directory. Put
dashboard source code files that you edit with a third-party editor in the /local directory.

Caution: Do not put Simple XML source files in the /defaultdirectory. Files in the /default directory are overwritten on
deployment and app updates.

For more information on directories and file precedence, see Configuration file precedence.

File location and permissions

Source code file location depends on the file type and permissions.

Simple XML and prebuilt panel source files

The /views directory of an app contains the following files.

• Simple XML files

• Panel files available by reference in a dashboard. See Create and add a panel by reference for more information.
• Legacy Advanced XML files

Put Simple XML and panel source code files in the following locations for each permission type.

Permission type Location

Shared in app
$SPLUNK_HOME/etc/apps/<app>/local/data/ui/views/<file_name>

Private
$SPLUNK_HOME/etc/users/<user>/<app>/local/data/ui/views/<file_name>

HTML files
The /html directory in an app contains source files for dashboards converted to HTML.

115
Put HTML files in the following locations for each permission type.

Permission type Location

Shared in app
$SPLUNK_HOME/etc/apps/<app>/local/data/ui/html/<dashboard_file_name>

Private
$SPLUNK_HOME/etc/users/<user>/<app>/local/data/ui/html/<dashboard_file_name>

Show source code file changes in Splunk Web

To display changes to dashboard source code files, refresh configurations on your Splunk deployment by using the
debug/refresh endpoint.

http://localhost:8000/debug/refresh

After refreshing the instance, reload the edited dashboard.

Importing CSS, JavaScript, and other static files

A dashboard can import CSS and JavaScript files as well as image files and static HTML files. These files are in the
following location. The files cannot be in a subdirectory.

$SPLUNK_HOME/etc/apps/<app_name>/appserver/static/

By default, this directory contains the following two files:

• dashboard.css
• dashhboard.js

You can edit default files at this location or add additional CSS and JavaScript files. You can also add any HTML files that
you want to reference from a dashboard.

Import JavaScript and CSS files

Use the script and stylesheet attributes in <dashboard> or <form> element to import a JavaScript or CSS file from the
default location for an app. You can also reference script and CSS files from other apps.

Examples

Import files from the same app

<dashboard script="myScript.js" stylesheet="myStyles.css">

. . .
</dashboard>
Import files from another app

<dashboard script="myApp:myScript.js" stylesheet="myApp:myStyles.css">

116
. . .
</dashboard>

117
Drilldown and Dashboard Interactivity

Drilldown behavior
Use drilldown to provide additional data insights to dashboard users. Drilldown lets users click on visualization elements
like data points, columns, table rows, or a visualization legend to open a secondary search in a new browser window. The
secondary search is similar to the search driving the visualization but it generates results customized to the element that
users click.

You can enable or disable drilldown using the visualization Format menu. Table visualizations and events lists provide
additional configuration options in this menu.

Use Simple XML to make additional customizations. For example, you can create a dynamic drilldown linking users from a
dashboard to a form or to an external website. A contextual drilldown links users to content on the same page.

Dynamic drilldown

Specify the following types of custom drilldown targets.

• A dashboard or form in an app in your Splunk installation

• A third-party URL

Dynamic drilldown elements

Implement dynamic drilldown in Simple XML using the <drilldown> element with other simple XML elements. See
Drilldown elements in the Simple XML Reference for details.

Element Description
<drilldown> Defines a drilldown. Parent element of the other dynamic drilldown elements.

<condition> Specifes fields that generate drilldown actions.

<link> Specifies a target destination for a detailed search.

Publishes global tokens that can be consumed by any other element or search within a dashboard. Use <set> and <unset>
<set>
when displaying drilldown results on the same dashboard.

<unset> Removes a token that was previously set. Use <set> and <unset> when displaying drilldown results on the same dashboard.
To learn about using <set> and <unset> for contextual drilldown, see Contextual drilldown elements.

Drilldown event tokens

Dynamic drilldown uses drilldown event tokens to customize the values that you capture from a visualization. The tokens
available depend on the visualization. See Token usage in dashboards and Define tokens for drilldown in this manual.

118
For example, for a map visualization, the tokens specify the field and value from a map marker as well as latitude and
longitude values. For a table visualization, the tokens specify the name and value returned from a clicked cell. The
following table lists the drilldown event tokens available for a table visualization. See Drilldown event tokens in the Simple
XML Reference for a complete list of tokens available for all visualizations.

Token Description
click.name Name of the leftmost field that is displayed in the table. This is always _time, if present.

click.value Value of the left-most column in the clicked row.

click.name2 Name of the clicked column.

click.value2 Value of the clicked column.

row.<fieldname> All field values for the clicked table row, including those fields that are not displayed.

earliest/latest Time range of the clicked table row, or if not applicable, the time range of the search.
Drilldown event tokens differ from the tokens you define with the <set> element. Drilldown event tokens are pre-defined
for capturing values from a click in a visualization. Tokens that are defined with the <set> element specify values that the
target destination consumes.

Specify a destination link

The <link> element provides various options for specifying the destination for dynamic drilldown. For details, see <link>
element in the Simple XML Reference.

You can specify the following.

• Specify a dashboard in the same or different app in a Splunk deployment.

• Pass in a token value to populate a form in the destination target.
• Pass in earliest and latest values to define the search terms in the destination form.
• Open a third party URL, optionally passing in the value captured by the drilldown action as a query argument.
• Specify target values for the <a> HTTP anchor tag, indicating how to open the target HTTP web page.

When used with the <condition> element, you can specify the name of the field or series from which to capture values for
drilldown.

Dynamic drilldown example

This example shows how to pass a drilldown value from a dashboard to a form in a separate app. The dashboard
contains a table. A click anywhere in a row of the table captures the value for the source type from the first column in the
row. This value is passed as the input value to the form.

This is the dashboard containing the table.

119
This is the form, which is in a separate app. The value passed from the dashboard becomes the input to the form. The
form shows the results when a user of the dashboard clicks anywhere in the row for splunk_web_service source type.

Dashboard implementing dynamic drilldown

• Uses the <drilldown> and <link> elements.

• Specifies the target attribute in <link> to open the target in a new page.
• References the src_type_tok token, which is defined in the target form.
• Specifies row for the drilldown option.

Form

• Defines the src_type_tok token

• Populates the text input with the value passed in for the token and runs the form.

Source code for the table in the dashboard that implements dynamic drilldown:

<dashboard>
<label>Dynamic Drilldown</label>
<row>
<panel>
<table>

120
 <search>
<query>index="_internal" | chart count by sourcetype | sort sourcetype</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<drilldown>
<link target="_blank">
/app/MyApp/drilldown_dynamic_target_form?form.src_type_tok=$row.sourcetype$
</link>
</drilldown>
<option name="drilldown">row</option>
</table>
</panel>
</row>
</dashboard>
Source code for the form that accepts the passed in value:

<form>
<label>Dynamic Drilldown (Target Form)</label>
<description/>
<fieldset submitButton="false" autoRun="true">
<input type="text" token="src_type_tok" searchWhenChanged="true">
<label>Source type</label>
</input>
</fieldset>
<row>
<panel>
<chart>
<title>Source type details</title>
<search>
<query>
index=_internal | timechart span=1week count by $src_type_tok$
</query>
<earliest>-30d@d</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">column</option>
</chart>
</panel>
</row>
</form>
Single value drilldown using hidden fields

From a single value visualization you can drill down on hidden fields. The following example is from an app that uses
single value visualizations to display selected government regulations. The example app uses a global search that returns
information about government agencies, regulations, and regulation IDs. It contains two single value visualizations that
use post process searches to obtain the values to display.

There are two dropdowns:

• Select an agency
The selected agency name is displayed as a single value visualization.

• Select a regulation
Users can choose a regulation available from the agency they selected. The regulation name is shown as a single
value visualization.

121
The second single value visualization consumes the fields regulation_docketTitle and docketId from its post process
search. However, a single value field can only display the first returned value, which is the regulation_docketTitle in this
example.

The visualization uses the <drilldown> element to drill down on the "hidden value field," docketId. It specifies the hidden
field in the $row.<field>$ drilldown event token. See Single event tokens for a list of all drilldown event tokens.

$row.docketId$
The following source code shows how to access the hidden value field for single value visualizations.

<form stylesheet="regulations_explorer.css">
<label>Regulations Explorer</label>

<fieldset autoRun="true" submitButton="false">

<input type="dropdown" token="agency" searchWhenChanged="true">
<label>Select an Agency</label>
<search>
<query><!-- populating search for input --></query>
<earliest>$earliest$</earliest>
<latest>$latest$</latest>
<fieldForValue>agencyName</fieldForValue>
<fieldForLabel>agencyName</fieldForLabel>
</search>
<choice value="*">ALL</choice>
<default>*</default>
</input>

<input type="dropdown" token="docket" searchWhenChanged="true">

<label>Select a regulation</label>
<search>
<!-- populating search for input -->
</search>
<fieldForValue>docketTitle</fieldForValue>
<fieldForLabel>docketTitle</fieldForLabel>
</input>

<!-- time picker input -->

</fieldset>

<!-- Global search for post process -->

<!-- Provides docketId and regulation_docketTitle fields -->
<!-- That are consumed by the single value visualization -->
<search id="baseSearch">
<query>
| pivot regulations Regulations_Data count(Regulations_Data)
AS "Count of Regulations Data" SPLITROW docketId
AS "docketId" SPLITROW docketTitle
AS "regulation_docketTitle" SPLITROW commentStatus
AS "regulation_comment_status" SPLITROW commentEndDateLong
AS "regulation_comments_end_date" SPLITROW commentStartDateLong
AS "regulation_comment_start_date" SPLITROW agency_name
AS "agency_name" FILTER docketTitle contains $docket|s$
| sort - regulation_comment_start_date| head 1
</query>
</search>
<row>
<panel>
<single>

122
 <!-- Displays regulation_docket title -->
<search base="baseSearch">
<query>
| fields regulation_docketTitle, docketId
</query>
<earliest>$earliest$</earliest>
<latest>$latest$</latest>

</search>

<drilldown>
<link>
<![CDATA[ http://www.regulations.gov/#!docketDetail;D=]]>$row.docketId$
</link>
</drilldown>
</single>
</panel>
</row>
</form>
Contextual drilldown elements

Contextual drilldown generates results to a visualization on the same dashboard. Compare to the dynamic drilldown
example above, which generates drilldown results from one dashboard to a separate form. Use the <condition> element
with the <drilldown>, <set>, and <unset> elements to implement contextual drilldown.

Use the <condition> element as a child of the <drilldown> element. The field attribute of the <condition> element
specifies the fields whose values you want to capture. The <condition> element lets you specify different actions for the
drilldown, depending on the field clicked.

Use the <set> token to assign the value from a drilldown token to another token that the target of the drilldown consumes.
The <set> element is a child of the <condition> element. The <unset> element removes a token that was previously set.

Use the depends and rejects attributes of panel visualization elements to specify tokens that need to be present to
display a visualization.

Basic contextual drilldown example

This example shows how a click anywhere in a row of a table passes a value to a chart on the same page. The drilldown
captures the value from the first column in the clicked row to pass to the chart. The chart is hidden until a user clicks on
the table.

123
This example uses the <set> element to set the src_type_tok to the value returned from the $click.value$ drilldown
token, which is the value from the first column in the table. See table event tokens.

The chart consumes the src_type_tok in the depends attribute to the <chart> element, the <title> element, and in the
search. The depends attribute prevents the chart from displaying until a user clicks in the table.

<dashboard>
<label>Contextual drilldown</label>
<row>
<panel>
<table>
<title>Set sourcetype token on click</title>
<search>
<query>
index=_internal | stats count by sourcetype
</query>
<earliest>-4h</earliest>
<latest>now</latest>
</search>
<drilldown>
<set token="src_type_tok">$click.value$</set>
</drilldown>
</table>
</panel>
<panel>
<chart depends="$src_type_tok$">
<title>Chart for $src_type_tok$</title>
<search>
<query>
index=_internal sourcetype=$src_type_tok$
| timechart count by sourcetype
</query>
<earliest>-4h</earliest>
<latest>now</latest>
</search>
</chart>
</panel>
</row>
</dashboard>
Contextual example from map visualization

This example show how to drill down to markers on a map visualization. The map visualization shows earthquake activity
for the past month. The generated search on a map marker displays in a bar chart with details from the map data. For
example, a click on the marker straddling Montana, Utah, and Wyoming generates the chart on the right.

124
 Note: This example uses earthquake data downloaded from the USGS Earthquakes website.

The following search shows earthquake activity for incidents greater than magnitude .9.:

index=main mag > .9 | geostats latfield=latitude longfield=longitude count

The <drilldown> element sets tokens based on the bounds of a marker showing clustered locations. The captured values
derive from the click.bounds.<orientation> map token. See map event tokens for details on all map tokens available for
drilldown.

<drilldown>
<set token="bounds.north" > $click.bounds.north$</set>
<set token="bounds.east" > $click.bounds.east$</set>
<set token="bounds.south" > $click.bounds.south$</set>
<set token="bounds.west" > $click.bounds.west$</set>
</drilldown>
The chart contains the following search, which consumes the tokens that the drilldown action generates:

index=main mag > .9 | search latitude >= $bounds.south$ latitude < $bounds.north$ longitude >= $bounds.west$
longitude < $bounds.east$ | top place

Here is the source code that implements this contextual drilldown example:

<row>
<panel>
<map>
<search>
<query>
index=main mag>.9
| geostats latfield=latitude longfield=longitude count
</query>
<earliest>0</earliest>
<latest />
</search>
<option name="mapping.data.maxClusters">1000</option>
<option name="mapping.drilldown">all</option>
<option name="mapping.map.center">(39.3,-95.98)</option>
<option name="mapping.map.zoom">4</option>
<option name="mapping.markerLayer.markerMaxSize">40</option>
<option name="mapping.markerLayer.markerMinSize">20</option>
<option name="mapping.markerLayer.markerOpacity">0.9</option>
<option name="mapping.tileLayer.maxZoom">7</option>
<option name="mapping.tileLayer.minZoom">0</option>
<drilldown>
<set token="bounds.north">$click.bounds.north$</set>
<set token="bounds.east">$click.bounds.east$</set>
<set token="bounds.south">$click.bounds.south$</set>
<set token="bounds.west">$click.bounds.west$</set>
</drilldown>
<option name="mapping.tileLayer.url">
http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
</option>
</map>
</panel>
<panel>
<chart>
<title>Places</title>

125
 <search>
<query>
index=main mag>.9 | search
latitude >= $bounds.south$
latitude &lt; $bounds.north$
longitude >= $bounds.west$
longitude &lt; $bounds.east$
| top place
</query>
<earliest>0</earliest>
<latest />
</search>
<option name="charting.chart">bar</option>
</chart>
</panel>
</row>
Contextual example with multiple conditions

This example sets multiple conditions for drilldown. It contains a table listing event counts for source types by log level. A
click in the table generates a detail chart. The detail chart is not visible until the user drills down from the table. The
content of the detail chart differs, depending on where a user clicks in the table.

• Click the sourcetype or Total column

The detail chart displays details for all log levels.

• Click a log level column

The detail chart displays details for that log level.

126
This example sets three conditions using the field attribute of the <condition> tag. Each condition sets token values for
$s_sourcetype$ and $s_log_level$. The search in the detail chart consumes these tokens.

<drilldown>
<condition field="sourcetype">
<set token="s_sourcetype">$row.sourcetype$</set>
<set token="s_log_level">*</set>
</condition>
<condition field="Total">
<set token="s_sourcetype">$row.sourcetype$</set>
<set token="s_log_level">*</set>
</condition>
<condition field="*">
<set token="s_sourcetype">$row.sourcetype$</set>
<set token="s_log_level">$click.name2$</set>
</condition>
</drilldown>
For all columns in the table, the token $s_sourcetype$ captures the value from the $row.sourcetype$ table token. This
sets the value to the source type of the clicked cell.

For the sourcetype and Total columns, a click sets the $s_log_level$ token value to '*'.

For the log level columns, a click sets the $s_log_level$ token value to the value of the $click.name2$ table token. This
token captures the name of the column of the clicked table cell.

The <chart> element for the detail chart sets the value of the depends attribute to $s_sourcetype$. The chart does not
display until drilldown from the table sets this token.

<chart depends="$s_sourcetype$">
Here is the source code implementing this dynamic drilldown example:

<dashboard>
<label>Contextual Example with Multiple Conditons</label>
<row>
<panel>
<table>
<title>Events: Source type by log level</title>
<search>
<query>
index=_internal log_level=*
| chart count over sourcetype by log_level | addtotals
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<option name="drilldown">cell</option>
<drilldown>
<condition field="sourcetype">
<set token="s_sourcetype">$row.sourcetype$</set>
<set token="s_log_level">*</set>
</condition>
<condition field="Total">
<set token="s_sourcetype">$row.sourcetype$</set>
<set token="s_log_level">*</set>
</condition>
<condition field="*">
<set token="s_sourcetype">$row.sourcetype$</set>

127
 <set token="s_log_level">$click.name2$</set>
</condition>
</drilldown>
</table>
</panel>
<panel>
<chart depends="$s_sourcetype$">
<title>
Events: sourcetype="$s_sourcetype$" and log_level="$s_log_level$"
</title>
<search>
<query>
index=_internal sourcetype="$s_sourcetype$"
log_level="$s_log_level$" | timechart count
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
</chart>
</panel>
</row>
</dashboard>
Dynamic drilldown in dashboards and forms
Link to custom destinations and content when users click on elements in a dashboard or form. You can use dynamic
drilldown to capture information from a source dashboard or form and pass it to a target. The target can be another
dashboard or form, or a page within your Splunk deployment. You can also link to an external website.

Example dynamic drilldown

This dashboard shows sourcetype throughput in a table.

The drilldown is configured to link to a form. To show customized content in the form, the drilldown also captures values
from the source dashboard and/or elements that users click. For example, when users click the splunk_web_service
sourcetype in the table, this form opens.

128
When the form opens, the splunk_web_service sourcetype populates the form input and causes the form to show
customized content for this sourcetype.

Building a dynamic drilldown

Start building a dynamic drilldown by putting a <drilldown> element in a table or chart.

Specify a drilldown target

Inside the <drilldown> element, use a <link> element to indicate the drilldown target and to customize content in a target
dashboard or form.

<drilldown>
<link>...</link>
</drilldown>

The <link> element contains a path to the target and any token values that you are passing from the source to the target.
These examples show you the syntax for specifying the target path and passing values.

Target and
Syntax
behavior
Use a relative path that includes the dashboard or form id.
Link to a dashboard in
<link>
your Splunk deployment.
[relative path]/[dashboard or form id]
</link>

Link to a form in your

Add a ? symbol after the relative path. Set tokens in the target to values passed from the source. This example sets
Splunk deployment.
a token in a target form to a value from the source.
Show customized
content in the form by
Prefix tokens in the target form with form., as shown here.
passing a token value
captured from the
<link>
source. Use the token
[relative path]/[dashboard or form id]?form.[target_token_name]=[$source_value$]
value to populate a form
</link>
input.

Pass the <earliest> Add &earliest=$earliest$&latest=$latest$ to the target path and token values. Use the <![CDATA[ ...
and <latest> time ]]> wrapper to make sure that the & symbol is interpreted correctly.

129
 Target and
Syntax
behavior
range modifiers from the
source search to a
search in the target. <link>
<![CDATA[
[relative path]/[dashboard or form
id]?form.[target_token_name]=[$source_value$]&earliest=$earliest$&latest=$latest$
]]>
</link>

Use a URL and query

argument to pass a
<link>[target_URL]?q=[$source_value$]
value to a target web
</link>
page.
Syntax for specifying destinations

The syntax for specifying destinations varies, depending on the type of chart you are using and the destination you
choose. Refer to the entries for <drilldown> element and <link> element in the Simple XML Reference. See also Token
usage in dashboards to review available token filters.

Conditional linking

When configuring a drilldown, you can capture token values from a source dashboard or form. You can use these values
to configure the target dashboard or form and show users customized content.

You might want to configure conditional linking to different targets depending on the specific elements that users click in
the source dashboard or form. To do this, add a <condition> element to the <drilldown>. The <condition> element
contains the conditional <link> target and values to use.

A table field or chart series attribute in the <condition> indicates the field or series value to evaluate for conditional
linking.

Examples

A dashboard includes a table with columns A, B, and C. Here are some examples of conditional drilldown linking.

Set a form value

If a user clicks a value in column A, open a form with a token set to the captured value. If users click values in columns B
or C, use default drilldown behavior.

<drilldown>

<condition field="A">
<link> [relative_path]/[target_form_id]?form.[target_token]=$[value_from_source]$ </link>
</condition>

</drilldown>

Pass a query string parameter to a URL

If a user clicks a value in column B, the drilldown passes the value as a query string parameter to a target web page. If
users click values in column A or C, use default drilldown behavior.

<drilldown>

130
<condition field="B">
<link>[target_URL]?q=$[value_from_source]$</link>
</condition>

</drilldown>

Open the target in another browser window

By default, drilldown targets open in the same browser window as the source dashboard or form. You can add a
target="blank" attribute to the drilldown element to make the target open in a new browser window.

Example source code

<dashboard>
<label>Dynamic drilldown example</label>

<row>
<panel>
<table>

<title>Sourcetypes by source (Dynamic drilldown to a form)</title>

<search>
<query>
index="_internal" | stats dc(sourcetype) by sourcetype, source
</query>
<earliest>-60m</earliest>
<latest>now</latest>
</search>
<option name="count">15</option>
<option name="displayRowNumbers">false</option>
<option name="showPager">true</option>

<drilldown target="blank">
<!-- Access the input on the target form, which is in the same app -->
<!-- sourcetype.tok is the token for an input to the target form -->
<link>
form_for_drilldown?form.sourcetype_tok=$click.value$
</link>
</drilldown>

</table>
</panel>
</row>
</dashboard>
Dynamic drilldown examples

These examples show you how to build dynamic drilldown into dashboards and forms.

Target form

If you are linking to a target dashboard or form, make sure that it is configured to receive any token values that you are
setting in the drilldown.

This form is the target for all of the following drilldown examples. The relative path for the form is
/app/search/form_for_drilldown.

131
The form has a dropdown input that lets users select a sourcetype value. The input uses the sourcetype token to
represent the selected value. This token is used in a search that generates a chart showing results for this sourcetype.

<form>
<label>Destination form for drilldown</label>
<fieldset autorun="true" submitButton="false">
<input type="dropdown" token="sourcetype">
<label>Select a source type</label>
<default>splunkd</default>
<search>
<query>
index = _internal | stats count by sourcetype
</query>
</search>
<fieldForLabel>sourcetype</fieldForLabel>
<fieldForValue>sourcetype</fieldForValue>
</input>
</fieldset>
<row>
<panel>
<chart>
<search>
<query>index = _internal sourcetype=$sourcetype$
| timechart count by sourcetype</query>
<earliest>-7d</earliest>
<latest>-0d</latest>
</search>
</chart>
</panel>
</row>
</form>
Dashboard linking to a form

This example shows you how to set up a drilldown that links dashboard users to a form. When users click on a table row
in the dashboard, the form opens to show customized content.

Drilldown source code

This drilldown uses the <link> element to indicate the form to open and to set token values in the form.

<drilldown>
<link>
<![CDATA[
/app/search/form_for_drilldown?form.sourcetype=$row.sourcetype$&earliest=$earliest$&latest=$latest$
]]>
</link>
</drilldown>

In the <link> element, the following drilldown components configure linking and token setting when users click on a table
row in the dashboard.

Drilldown behavior that

Component this component Details
configures
Target form path Indicates the form to open /app/search/form_for_drilldown
when the user clicks on a table

132
 Drilldown behavior that
Component this component Details
configures
row

To pass token values from the source dashboard to the target form, query string parameters
are included in the path after the ? symbol.

form.sourcetype=$row.sourcetype$

When a user clicks a table row in the dashboard, pass the sourcetype value
Tokens customize form from this row to the form. Set the form.sourcetype token in the form to the
Token names content based on the table row $row.sourcetype$ value from the table row that the user clicked.
and values that users click in the
dashboard.
earliest=$earliest$&latest=$latest$

Set the earliest and latest time range modifiers in the form to the
$earliest$ and $latest$ values from the source dashboard.

The <![CDATA[...]]> tag makes sure that the & character is interpreted
correctly.
Complete dashboard source code

<dashboard>
<label>Dashboard with dynamic drilldown to a form</label>
<row>

<table>
<search>
<query>
index="_internal" group="per_sourcetype_thruput" |
chart sum(kbps) over series
</query>
<earliest>-60m</earliest>
<latest>now</latest>
</search>
<title>Top sourcetypes (drilldown example)</title>
<option name="count">15</option>
<option name="displayRowNumbers">false</option>
<option name="showPager">true</option>

<drilldown>
<link>
<![CDATA[
/app/search/form_for
_drilldown?form.sourcetype=$row.sourcetype$&earliest=$earliest$&latest=$latest$
]]>
</link>
</drilldown>
</table>

</row>
</dashboard>

133
Form linking to an external website

Link users who click an element in a chart to relevant search results on the Splunk Answers community forum.

Drilldown

<link>
http://answers.splunk.com/search.html?q=$click.value$
</link>
This drilldown includes the following components in the <link> element.

Drilldown behavior that

Component this component Details
configures
In this example, the URL
URL for the
points to a Splunk Answers http://answers.splunk.com/search.html
external website
search.

?q=$click.value$
Capture the clicked value from
Token names the chart and pass it to the The $click.value$ predefined token captures the clicked value from the chart. This
and values website as a URL query string value passes to the Answers search URL, meaning that it is used as a search term on the
parameter. Answers site. When the user clicks a value and the Answers site loads, users see search
results for this value.

Complete form source code

<form>
<label>Form Search</label>

<fieldset>
<!-- Use the html tag to specify text to display -->
<html>
<p>Enter a sourcetype in the field below. This view returns the most recent 1000 events for that
sourcetype.</p>
<p>In the Matching Events, click in the series column to open the value clicked in a new form</p>
</html>

<!-- The default input is a text box with no initial value -->
<input token="sourcetype" />

<!-- Include a time picker -->

<input type="time">
<default>Last 30 days</default>
</input>
</fieldset>

<row>
<panel>
<!-- output the results as a 50 row events table -->
<table>
<title>Matching events</title>

<!-- search with replacement token delimited with $ -->

<search>

134
 <query>
index="_internal" group="per_sourcetype_thruput" series=$sourcetype$
| chart sum(kbps) over series
</query>
</search>

<option name="count">50</option>

<!-- $click.value$ captures the value clicked by the user -->

<!-- and passes it to the website as a query parameter -->
<drilldown>
<link>
http://answers.splunk.com/search.html?q=$click.value$
</link>
</drilldown>
</table>
</panel>
</row>

</form>
Dashboard linking to a multivalue field

You might have a dashboard that includes multivalue fields. Multivalue fields can appear multiple times in an event. Each
time this field type appears in an event, it can have a different value. You can configure a drilldown to link to specific
targets depending on the value that users click.

See Configure multivalue fields in the Knowledge Manager Manual for more information on working with multivalue fields
in your data.

Capture a clicked value from a multivalue field

When setting up a drilldown from a table, you typically use $click.name$ or $click.name2$ to capture the value that users
click in a column or row. However, when working with multivalue fields, use $click.value2$ to capture the selected value
for the drilldown. Use a <condition> element with a field attribute to limit the column selection to the multivalue field.

Example
A dashboard includes a multivalue badges field representing user checkins to a conference event. This drilldown captures
a clicked value from the badges field.

<drilldown>

<condition field="badges">
<link>
/app/foursquare_vegas/vegas_badge_1?form.badge=$click.value2$
</link>
</condition>

</drilldown>

The drilldown includes the following components to set a target and capture the clicked value.

Drilldown behavior that this

Component Details
component configures
field attribute in the
Limits the selection to this field. <condition field="badges">
<condition> element

135
 Drilldown behavior that this
Component Details
component configures
Open this form when users click a
Target form path badges value in the source /app/foursquare_vegas/vegas_badge_1/
dashboard.

?form.badge=$click.value2$
Show customized content in the
Token names and values
target form. Set the form.badge token in the target form to the multivalue field
$click.value2$ that the user clicks in the source dashboard.
Complete dashboard source code

<dashboard>
<label>Demo: drilldown</label>
<row>
<panel>
<table>
<searchString>
index=foursquare checkin.primarycategory.nodename=*
| spath output=venue path=checkin.venue.name
| spath output=badges path=checkin.badges{}.name
| eval link="Yelp Search"
| stats count as checkins sparkline values(badges)
as "badges" values(link) as "links" by venue
| sort -checkins
</searchString>

<format field="sparkline" type="sparkline">

<option name="type">bar</option>
<option name="height">30</option>
<option name="barColor">green</option>
<option name="colorMap">
<option name="5:9">yellow</option>
<option name="10:">red</option>
</option>
</format>
<title>Top Venues</title>

<drilldown>

<!-- Mulitvalue field drilldown -->

<condition field="badges">
<link >
/app/foursquare_vegas/vegas_badge_1?form.badge=$click.value2$
</link>
</condition>

<condition field="venue">
<link>
/app/foursquare_vegas/vegas_venue_1?form.venue=$row.venue$
</link>
</condition>

<condition field="links">
<link>
http://www.yelp.com/search?find_desc=$row.venue$&find_loc=Las+Vegas,+NV
</link>
</condition>
</drilldown>

136
 </table>
</panel>
</row>
</dashboard>

Most of the searches access data available from the Search Tutorial. If you want to download the data from the Search
Tutorial to create the dashboards from these examples, see Get the tutorial data into your Splunk deployment.

Token usage in dashboards

Tokens are like programming language variables. A token is a placeholder for information that can change, such as a field
value or search job start time. You can use tokens to help implement interactive dashboard behavior.

Overview

Use predefined tokens or generate custom tokens to capture and access dynamic values. Tokens can propagate these
values throughout a dashboard or form.

As an example, a token can capture a value that users select in a form input. You can use this token value in one or more
search strings to generate visualizations that reflect this value. You might also use the value to manage which panels to
display.

Generate token values

• Define tokens to capture input values for forms.

• Define tokens to specify conditional actions, based on the value of the token.

• Define tokens within a search string that use values based on previously defined tokens.

• Splunk Enterprise defines token values that you can access.

Defined tokens include tokens for visualizations, for time inputs, and labels and values of form inputs.

Consume token values

There are many use cases for accessing the value of a token.

Use Case Description

You can control conditional behaviors on the page or enrich displays with search
Search events
metadata.

The inputs to a form modify the data a visualization displays. Tokens defined with user
Form inputs
inputs modify the search of the form.

For forms with multiple time pickers, tokens indicate the time picker to use for each
Multiple time pickers in forms
visualization.

When a user clicks a visualization in a dashboard, predefined tokens capture the value
Dynamic drilldown
clicked for the drilldown operation.

Conditional display of dashboard elements Tokens set and unset conditions for the display of panels and their contents.

137
 Use Case Description

Pan and zoom chart controls to select an area in the

Predefined tokens allow you to select a specific area for this behavior.
chart

Token syntax for searches

Tokens capture and pass values in a dashboard. Token values can come from various sources, including form inputs and
predefined token values for visualizations. Searches can access token values.

In a search, token name syntax uses $...$ delimiters. For example, if you define a form input token as field_tok, you
can specify the token in a search as $field_tok$. Here is an example.

<search>
index=_internal source=*splunkd.log | stats count by $field_tok$
</search>
See Token filters for advanced syntax to access token values.

Tokens with SplunkJS Stack

If you are using SplunkJS Stack with JavaScript extensions, see Tokens and Data Binding on the Splunk Developer Portal
to learn how to use tokens with JavaScript.

Define search tokens

You can set search tokens for a dashboard to display search job metadata or to control dashboard behavior.

There are many ways to use search tokens. Here are some example use cases.

• Including a search result count in a visualization title.

• If a search returns no results, run a different search or hide the panel.
• Hide or show panels if a search fails.

There are also various advanced options for working with search tokens. Options include the following:

• Show the time range of the search below the visualization element using HTML.
• Build a custom HTML element and insert search results as tokens.
• Define token values based on the result of token-specific eval expressions.

Search event elements and job properties

There are several search event handlers that you can use in Simple XML dashboards.

Handler name Access to search job properties? Access to first results row?
<progress> Yes Yes

<done> Yes Yes

<cancelled> No No

138
 Handler name Access to search job properties? Access to first results row?
<error> No No

<fail> No No
Within a search event handler, you can access specific job properties with tokens. For example, here are some commonly
used job metadata tokens.

• $job.earliestTime$: Initial job start time.

• $job.latestTime$: Latest time recorded for the search job.

• $job.resultCount$: Number of results a search job returned.

• $job.runDuration$: Time, in seconds, for the search to complete.

• $job.messages$: List of error and/or debug messages generated by the search job.

For more details on event handler elements, available properties, and usage examples, see Search event handlers.

To learn about more search job properties, see View search job properties in the Search Manual.

Search tokens for dynamic display example

Here is an example of the <search> element for a dashboard that hides a panel if no search results are returned.

<search id="search_logic">
<query>$index_switcher$ | top sourcetype</query>
<earliest>-60m@m</earliest>
<latest>now</latest>

<progress>
<!-- match attribute for condition uses eval-like expression (see Splunk search language 'eval'
command) -->
<!-- logic: if resultCount is 0, then show a static html element, and hide the chart element -->
<condition match="'job.resultCount' == 0">
<set token="show_html">true</set>
</condition>
<condition>
<unset token="show_html"/>
</condition>
</progress>
</search>
For more examples, see the Splunk Dashboard Examples App.

Custom logic for dashboards

Add custom logic to a dashboard with the <condition match=" "> and <eval> elements.

For both <condition> and <eval> elements, all data available from an event as well as the submitted token model is
available as a variable within the eval expression.

139
Token syntax

As of software version 6.4, you can use either $...$ delimiters or single quote delimiters for tokens in an <eval> or
<condition match=" "> statement. For example, both of the following options are valid.

• <condition match="$job.resultCount$ > 0">

• <condition match="'job.resultCount' > 0">

Define conditional matching

Use the <condition match=" "> element to define conditional behavior. The following example controls a token value
according to the result count job property.

<condition match="$job.resultCount$ == 0">

    <set token="show_table_query">true</set>
</condition>

You can also use a dashboard eval expression to define a condition to match. Here is an example using <condition
match=" "> to set a token value depending on whether the selected time range spans more than one day.

<condition match="relative_time(now(), earliest) - relative_time(now(), latest) > 86400">

<!-- Selected time range spans more than a day, use summary search -->
    <set token="table_query">index=my_summary_index | timechart count</set>
</condition>

Using strings in a conditional statement

If you are using a <condition match= " " > statement to evaluate a string value, such as a sourcetype name from the
first results row, put escaped quotation marks around the string value. This prevents the dashboard parser from handling
the quotation marks as special characters.

The following example sets up conditional token setting that depends on the sourcetype field value in the first results row.
If the sourcetype field value in the first results row is mongod, the "show_table" token is set to true.

To specify the "mongod" string in the conditional match statement, replace the quotation marks with the equivalent HTML
character entities.

<condition match="'result.sourcetype'==&quot;mongod&quot;">
    <set token="show_table">true</set>
</condition>

For more information about using special characters in dashboard source code, see Editing Simple XML.

Define token filtering and formatting

You can use eval expression logic to define token filtering and formatting. For example, you can set a token value to the
result of an eval expression.

140
Dashboard <eval> expression functionality

The dashboard eval expression has the same syntax and semantics as the eval expression syntax for SPL queries. Most
of the same eval expression functionality is the same between the dashboard eval expression and the SPL version of
eval. However, there are some important exceptions.

Unavailable dashboard eval expression functions

• commands(X)
• searchmatch(X)
• exact(X)
• Cryptographic hash functions:

*md5(X)
*sha1(X)
*sha256(X)
*sha512(X)
*sigfig(X)
*spath(X,"Y")

eval expression functions with different behavior for dashboards

• relative_time(X,Y): Uses client time zone.

• strftime(X,Y): Uses client time zone.
• strptime(X,Y): Uses client time zone.

It is also important to note that regular expressions in dashboard eval expressions use the syntax and semantics of the
JavaScript regular expression engine. This is not the same engine used for SPL eval expressions. If you are using regular
expressions in search tokens, check that syntax and semantics match those for JavaScript.

To learn more about eval expression functions, see eval in the Search Reference.

Custom logic examples

You can use an eval expression in <condition> event handler elements. Here is an example.

<condition match="[eval expression]">

. . . [conditional actions] . . .
</condition>

You can also compute a token's value based on the result of an eval expression. Here is an example.

<eval token="new_token">[eval expression]</eval>

Define tokens for form inputs

All form inputs have a token attribute that defines a token for the user-selected value for the input. Form inputs also have
child <prefix> and <suffix> elements that further modify the value of the token. For multiselect options, there are additional
elements that can modify the value of the token. See Define tokens for multiselect inputs.

141
This code snippet defines a token for a drop-down list. The selected choice for the dropdown provides the value of the
token.

<input type="dropdown" token="sourcetype_tok">

<label>Select a source type</label>
<default>splunkd</default>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd_ui_access">splunkd_ui_access</choice>
</input>
See Form input example.

Define tokens for multiselect inputs

A multiselect input uses the <prefix>, <suffix>, <valuePrefix>, <valueSuffix>, and <delimiter> elements to build the
multiselection search for the selected choices. The multiselection search, which is the value of the token for the input,
ensures that the input passes all selected values to the search for the form.

The following code snippet shows how to build a value for the multiselect token. If a user selects both splunkd and
splunk_web_access from the multiselect input, the token value is the following search fragment:

(sourcetype ="splunkd") OR (sourcetype ="splunk_web_access")

The search fragment derives from:

<prefix> + <valuePrefix> + [choice value] + <valueSuffix> + <suffix> + <delimiter> . . .

( sourcetype =" splunkd " ) _OR_

<input type="multiselect" token="sourcetype_tok">

<label>Select one or more source types</label>

<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_ui_access">splunk_ui_access</choice>
<choice value="splunkd_access">splunkd_access</choice>

<!-- Build multi-selection search:

(sourcetype ="value1" OR sourcetype ="value2" OR ...)
-->
<prefix>(</prefix>
<valuePrefix>sourcetype ="</valuePrefix>
<valueSuffix>"</valueSuffix>
<delimiter> OR </delimiter>
<suffix>)</suffix>

</input>
See Multiselect input example.

Define tokens for time inputs

If you have a form with panels that use different time pickers, use tokens for the time input to indicate the time picker to
use for each panel. To access the earliest and latest values from a time picker, use the following modifiers to the token:

• $timer_tok.earliest$
• $timer_tok.latest$

142
A time input that does not define a token is global. The values selected from such a time picker applies to all visualizations
that do not otherwise specify a time picker.

See Time input example.

Define tokens for conditional operations with form inputs

You can define tokens for conditional operations for form inputs. The value of the token changes according to the
condition you specify. For example, you can modify searches or select different visualizations to display based on the
conditional value of a token.

Conditional operations include:

• Modify searches based on the token value.

• Hide or display panels and the content of panels based on a condition.

• Select a view to open based on a token value.

Conditional operations are available for form inputs and dynamic drilldown. Form inputs use various combinations of the
following elements:

Element Description
<change> Container element for the conditions that you define.

Sets the condition based on the value of the input selection. In the Conditional input example, this is the value of the selected
<condition>
choice for the drop-down list.

<link> Specify a link to a destination based on a condition.

Defines various values for a token. The <search> element in the dashboard consumes the value of this token.
<set>
In the Conditional input example, defines value for the token earliest_tok.
Removes a token that was previously set.
<unset>
This is useful for conditional operations that depend on a token being set.
See the example at Conditional operations with form inputs.

Predefined tokens for accessing labels and values of form inputs

Splunk Enterprise provides predefined tokens to access the label and value of form inputs. Tokens are available for the
following inputs:

• check box
• drop-down list
• multiselect
• radio buttons

Token Description
label Contains the specified name of a form input choice.

143
Token Description
value Contains the value of a form input choice.
These tokens are useful to customize a search or place the label of the selected choice in a title or description of a panel
or visualization.

See Access labels and values of form inputs.

Set tokens on page load

Add an <init> element to a dashboard or form to reuse content or create a template. The token values inside this
element are set when the dashboard page loads.

Guidelines

Within a <dashboard> or <form> element, place content to set on page load inside the following tags.

<init>
</init>

• You can use the following event handlers to specify token settings within the <init> tags.
♦ <condition>
♦ <eval>
♦ <link>
♦ <set>
♦ <unset>

• PDF scheduling is disabled for dashboards and forms that include an <init> element.

• Token settings made within the <init> element override any settings made in URL query string parameters.

• Token setting on page load is only supported for Simple XML dashboards. If you convert a dashboard to HTML,
token settings within the <init> element are disabled.

Example

This form sets an app name token on page load. The token value is used in a panel label and a search with the |s$ filter
to wrap the value in quotation marks.

<form>
<label>Application Monitoring: Exchange</label>
<init>
<set token="app_name">my_app_name</set>
</init>
<row>
<panel>
<title>Activity Monitoring: $app_name$</title>
<search>
<query>index=main app=$app_name|s$</query>
</search>

144
 </panel>
</row>
</form>

Use global tokens to access environment information

Access details about the user, Splunk platform instance, and environment using global tokens. The following tokens are
available.

Name Description
$env:user$ Current user's user name

$env:user_realname$ Current user full name.

$env:user_email$ Current user email address.

$env:app$ Current app context

$env:locale$ Current locale

$env:page$ Currently open page

$env:product$ Current instance product type

$env:instance_type$ Indicates whether the current instance is Splunk Cloud or an on-premises deployment

$env:is_cloud$ Indicates if the current instance is Splunk Cloud. This token is only set when "true".

$env:is_enterprise$ Indicates if the current instance is a Splunk Enterprise deployment. This token is only set when "true".

$env:is_hunk$ Indicates if the current instance is a Hunk deployment. This token is only set when "true".

$env:is_lite$ Indicates if the current instance is a Splunk Light deployment. This token is only set when "true".

$env:is_lite_free$ Indicates if the current instance is using a Splunk Light free license. This token is only set when "true".

$env:is_free$ Indicates if the current instance is using a Splunk Enterprise free license. This token is only set when "true".

$env:version$ Current instance product version

Define tokens for dynamic drilldown

Predefined tokens for dynamic drilldown

Splunk Enterprise provides predefined tokens for dynamic drilldown. The predefined tokens capture values according to
the location a user clicks in a visualization. See Dynamic drilldown in dashboards and forms.

The predefined tokens available and the values they capture, differ according to the type of visualization. The following
table lists the predefined tokens for the table visualization. Drilldown event tokens in the Simple XML Reference lists all
predefined tokens for dynamic drilldown.

Token Description
click.name Name of the leftmost field that appears in the table. This is always _time, if present.

click.value Value of the leftmost column in the row.

click.name2 Name of the column.

click.value2 Value of the column.

145
 Token Description
row.<fieldname> All field values for the table row, including those fields that are not displayed.

earliest/latest Time range of the table row, or if not applicable, the time range of the search.
The <link> element uses the value of the predefined token to link to a new view or web page. See Predefined tokens for
accessing labels and values of form inputs. Predefined tokens are also useful in conditional operations using the
<drilldown> element.

See Dynamic drilldown examples.

Define tokens for conditional operations with the <drilldown> element

Conditional operations include:

• Set token values, based on a condition.

• Select a value for multivalue fields in a visualization.

A multivalue field is a field that appears more than once with different values.

• Select a view to open based on a token value.

• Hide or show panels based on conditions.

Conditional operations are available for both form inputs and conditional drilldown. Defining tokens for conditional
drilldown uses various combinations of the following tags:

Element Description
<drilldown> Define link destinations for fields in a dashboard or form. You can also use with <condition> to set tokens for custom actions.

<condition> Limit the scope of drilldown actions to specific fields.

Use with the <set> element to set the time window for the pan and zoom features of charts.

<selection> Applies to charts of type area, column, or line.

See Chart controls and the <selection> entry in the Simple XML Reference.
<link> Specify a link to a destination for drilldown.

<set> Defines various values for a token.

Removes a token that was previously set.

<unset>
Use with conditional operations that depend on a token being set.
Use the <set> element to define tokens

Use the <set> element to define tokens for conditional use. You can use the value of another token when defining a token
with the <set> element. For example, the following code snippet defines the sourcetype_tok token. This token captures
the value clicked from a <table> element for the field sourcetype.

<drilldown>
<condition field="sourcetype">
<set token="sourcetype_tok">$click.value2$</set>

146
 </condition>
</drilldown>
You can use the sourcetype_tok token in a search:

index=_internal sourcetype=$sourcetype_tok$ | timechart count by sourcetype

Use the <condition> element to select a value for multivalue fields in a visualization

Multivalue fields are fields that appear multiple times in an event and have a different value for each appearance. See
Configure multivalue fields in the Knowledge Manager manual.

If you have a dashboard that displays multivalue fields, use the <condition> element to specify a drilldown location specific
to the value of a clicked field. The following example links to different destinations based on the specific value for the field.
The <link> element consumes different predefined tokens for each condition. See Dashboard linking to a multivalue field
for the complete example.

<drilldown>
<condition field="badges">
<link >
/app/foursquare_vegas/vegas_badge_1?form.badge=$click.value2$
</link>
</condition>

<condition field="venue">
<link>
/app/foursquare_vegas/vegas_venue_1?form.venue=$row.venue$
</link>
</condition>

<condition field="links">
<link>
http://www.yelp.com/search?find_desc=$row.venue$&find_loc=Las+Vegas,+NV
</link>
</condition>
</drilldown>
Define tokens for pan and zoom chart controls

Splunk Enterprise uses predefined tokens to implement the zoom feature on a chart. Using the zoom feature, you can
select a portion of a data series in a chart that opens in a separate chart. See Pan and zoom chart controls.

Set the values of the predefined tokens within a <selection> element that is a child element of a chart. Use the token
values in the original chart to display a new chart that zooms to the selection.

Token Description
Captures the value of the x-axis at the beginning and end of a selection in a chart.
start
end Valid only in the context of the chart. Assign the values to tokens that you define to access the values
elsewhere in a dashboard.
Captures the values for the y-axis values for a selection. <field> represents a series displayed in the chart.
start.<field>
end.<field> Valid only in the context of the chart. Assign the values to tokens that you define to access the values
elsewhere in a dashboard.
See Pan and zoom chart controls for an example that shows how zoom to a selection in a time chart.

147
Syntax to consume tokens

Use $...$ delimiters to access the value of a token. For example, the following search for a visualization accesses the
field_tok token. A form input previously defined the field_tok token:

index=_internal source=*splunkd.log | stats count by $field_tok$

Token filters

Token filters ensure that you correctly capture the value of a token.

Filter Description
Wrap value in quotes Ensures that quotation marks surround the value referenced by the token. Escapes all quotation characters, ",
$token_name|s$ within the quoted value.

Ensures that the token value is valid for HTML formatting.

HTML format
$token_name|h$
Token values for the <HTML> element use this filter by default.
Ensures that the token value is valid to use as a URL.
URL format
$token_name|u$
Token values for the <link> element use this filter by default.
Specify no character
escaping Prevents the default token filter from running. No characters in the token are escaped.
$token_name|n$
The following code snippet uses the |s filter to place quotation marks around the value returned from a token:

<search>
<query>
index=_internal sourcetype=$sourcetype_tok|s$ | timechart count by sourcetype
</query>
</search>
If the value of sourcetype_tok is access_combined, it builds the following search string:

index=_internal sourcetype="access_combined" | timechart count by sourcetype

Escape the $ token delimiter character

If you include static text that contains the $ character, use $$ to escape the token delimiter value.

Combine literal values with token values

You can combine literal values with the value returned from a token. Use with the <set> element to set conditional actions
based on token values.

The following template combines the captured value from the predefined token, click.value, with static text. It places the
value of NewToken in quotation marks.

<set token="NewToken">sourcetype=$click.value|s$</set>

If the value of click.value is access_combined, then the value of NewToken is the following search fragment:

148
 sourcetype="access_combined"

You can use the prefix and suffix attributes to the <set> element to specify static text for a token value. The following
example sets the value for NewToken. It is equivalent to the template example:

<set token="NewToken" prefix="sourcetype=&quot;" suffix="&quot;">

$click.value$
</set>
Access tokens to show or hide user interface components

You can use token values to conditionally show or hide user interface components. The following elements contain the
attributes depends and rejects. Use the <set> and <unset> elements to set the token values that these attributes
consume.

• <row>
• <panel>
• <chart>
• <event>
• <html>
• <map>
• <single>
• <table>
• <input>

For example, show the <chart> element only when the showChart token has been set.

<chart depends="$showChart$">
Examples of token usage

Form input example

This example shows the basic usage of tokens in form inputs. It uses a drop-down list to select the source type for the
time chart. See Define tokens for form inputs.

The <input> element defines the sourcetype_tok that is consumed by the search for the visualization.

149
<form>
<label>Form example: source type time chart</label>
<fieldset autorun="true" submitButton="false">
<input type="dropdown" token="sourcetype_tok">
<label>Select a source type</label>
<default>splunkd</default>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd_ui_access">splunkd_ui_access</choice>
</input>
</fieldset>
<row>
<panel>
<chart>
<search>
<query>
index = _internal sourcetype=$sourcetype_tok$
| timechart count by sourcetype
</query>
<earliest>-7d</earliest>
<latest>-0d</latest>
</search>
</chart>
</panel>
</row>
</form>
Multiselect input example

This example shows how to build a search string for a form input using static text and token values. This is useful for
building multiselect options. See Define tokens for multiselect inputs.

The example uses the <prefix>, <suffix>, <valuePrefix>, <valueSuffix>, and <delimiter> elements to build the multiselect
search string. When a user selects splunkd and splunk_web_access, it generates the following search string:

(sourcetype ="splunkd" OR sourcetype ="splunk_web_access")

150
<form>
<label>Form with multiselect</label>
<fieldset autoRun="false" submitButton="true">
<html>
<p>
<strong>Multiselect choices</strong>
</p>
</html>
<input type="multiselect" token="sourcetype_tok" searchWhenChanged="false">
<label>Select one or more source types</label>
<choice value="*">All</choice>
<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_ui_access">splunk_ui_access</choice>
<choice value="splunkd_access">splunkd_access</choice>

<!-- Build multiselect search:

(sourcetype ="value1" OR sourcetype ="value2" OR ...)
-->
<prefix>(</prefix>
<valuePrefix>sourcetype ="</valuePrefix>
<valueSuffix>"</valueSuffix>
<delimiter> OR </delimiter>
<suffix>)</suffix>

</input>
</fieldset>
<row>
<panel>
<title></title>
<chart>
<search>
<query>index =_internal $sourcetype_tok$ | stats count by sourcetype</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">line</option>
<option name="charting.axisY.scale">log</option>
</chart>
</panel>
</row>
</form>
Time input example

This example shows how to use both a global and local time picker in a form. It also shows how to access the predefined
modifiers to a time input token. See Define tokens for time inputs.

The example shows a form with both a global time picker and local time picker. The <chart> element contains the local
time picker and uses modifiers to the local_time_input_tok token to access the earliest and latest values.

151
<form>

<label>Form with mutliple time pickers</label>

<description></description>
<fieldset submitButton="false">
<input type="dropdown" token="source_tok" searchWhenChanged="true">
<label>Select a source type</label>
<choice value="*">All</choice>
<search>
<query>index=_internal | stats count by sourcetype</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<fieldForLabel>sourcetype</fieldForLabel>
<fieldForValue>sourcetype</fieldForValue>
<prefix>sourcetype="</prefix>
<suffix>"</suffix>
<default>splunkd</default>
</input>

<!-- Do not define token for global timer -->

<input type="time" searchWhenChanged="true">
<label>Select time range</label>
<default>
<earliest>-7d@h</earliest>
<latest>now</latest>
</default>
</input>
</fieldset>
<row>
<panel>
<title>Global timer</title>
<chart>
<search>
<query>index=_internal $source_tok$ | timechart count</query>
</search>
</chart>
</panel>

<panel>
<title>Local timer</title>
<!-- Define token for local timer -->
<input type="time" searchWhenChanged="true" token="local_time_input_tok">

152
 <label>Select time range</label>
<default>
<earliest>-24h@h</earliest>
<latest>now</latest>
</default>
</input>
<chart>
<search>
<query>
index=_internal $source_tok$ | timechart count
</query>

<!-- Use modifiers to token for a timer -->

<earliest>$local_time_input_tok.earliest$</earliest>
<latest>$local_time_input_tok.latest$</latest>
</search>
</chart>
</panel>
</row>

</form>

Conditional operations with form inputs

This example shows how to use conditional operations with form inputs. See Define tokens for conditional operations with
form inputs.

The example uses the <change>, <condition>, and <set> elements to conditionally set the label for the selected time and
to set the earliest time token. The search consumes the earliest time token to set the bounds for the search. This example
uses the label and value predefined tokens for input choices. See Predefined tokens for accessing labels and values of
form inputs.

153
 Note: All input elements, with the exception of the time input, require a token attribute to be present. In the
example, the input element defines the token, period_tok. However, this token is never consumed by the search.

<form>
<label>Use tokens with conditional input choices</label>
<fieldset submitButton="false">
<input type="radio" token="period_tok">
<label>Select a time range</label>
<choice value="-24h@h">Last 24 Hours</choice>
<choice value="-7d@h">Last 7 Days</choice>
<choice value="-30d@h">Last 30 Days</choice>
<default>Last 24 Hours</default>

<!-- set condition based on the label defined by <choice> -->

<!-- Within each condition, specify a custom label for display -->
<!-- Capture the selected value in the token, earliest_tok -->
<change>
<condition label="Last 24 Hours">
<set token="date_label">Yesterday</set>
<set token="earliest_tok">$value$</set>
</condition>
<condition label="Last 7 Days">
<set token="date_label">Last week</set>
<set token="earliest_tok">$value$</set>
</condition>
<condition label="Last 30 Days">
<set token="date_label">Last month</set>
<set token="earliest_tok">$value$</set>
</condition>
</change>
</input>
</fieldset>
<row>
<panel>
<title>Conditional Inputs</title>
<chart>

<!-- Display selected label in the title -->

<title>$date_label$</title>

<search>
<query>index = _internal | timechart count by sourcetype</query>
<!-- use the value of earliest_tok -->
<!-- to set the time range -->
<earliest>$earliest_tok$</earliest>
<latest>now</latest>
</search>

<option name="charting.axisY.scale">log</option>
<option name="charting.axisTitleX.text">Time periods</option>
<option name="charting.axisTitleY.text">Events</option>
</chart>
</panel>
</row>
</form>

154
Access labels and values of form inputs

This example shows how to use tokens to access the labels and values of form inputs. See Predefined tokens for
accessing labels and values of form inputs.

The example uses the label of the selected radio button in the title of the visualization. It uses the value of the selected
radio button to determine the bounds of the search.

<form>
<label>Use tokens with input choices to capture input labels and values</label>
<fieldset submitButton="false">
<input type="radio" token="period_tok">
<label>Select a time range</label>
<choice value="-24h@h">Last 24 Hours</choice>
<choice value="-7d@d">Last 7 Days</choice>
<choice value="-30d@d">Last 30 Days</choice>
<default>Last 24 Hours</default>

<change>
<!-- use predefined input tokens to set -->
<!-- tokens for the selected label and value -->
<set token="date_label">$label$</set>
<set token="earliest_tok">$value$</set>
</change>

</input>
</fieldset>

<row>
<panel>
<title>Conditional Inputs</title>
<chart>
<!-- Display selected label in the title -->
<title>Source Type by $date_label$</title>

<search>
<query>index = _internal | timechart count by sourcetype</query>
<!-- use the value of earliest_tok -->
<!-- to set the time range -->

155
 <earliest>$earliest_tok$</earliest>
<latest>now</latest>
</search>

<option name="charting.axisY.scale">log</option>
<option name="charting.axisTitleX.text">Time period</option>
<option name="charting.axisTitleY.text">Events</option>
</chart>
</panel>
</row>
</form>
Chart controls
This topic describes advanced behavior for viewing data in charts.

Pan and zoom chart controls

The pan and zoom feature allows you to highlight chart details and optionally view the details in a separate panel. Pan
and zoom is available for the following charts:

• Column
• Line
• Area

The following examples show how to access the pan and zoom charting features.

Pan and zoom behavior

The following dashboard shows a chart displaying source types over a seven day period. The Y-axis uses a logarithmic
scale to provide a more meaningful graphic. The panel specifies the following search.

index=_internal | timechart count by sourcetype

The screen capture below shows a selection for the results for two days.

156
The resulting chart zooms in to the selection and now displays details of the selected area.

• Use the left and right arrows along the X-axis to move the selection window earlier or later.
• Click Reset Zoom to return to the original chart.

Zoom to another chart

You can specify pan and zoom behavior to display results in a separate chart. The following example uses the same base
example illustrated above in Pan and zoom behavior. The chart on the left lists all source types and also shows the
selection for a single day. The other chart lists only the splunk_web_access source type for the selected time range.

You can drag an edge of the time range in the left chart to expand the time range. You can also move the selected time
range to the left or right to specify an earlier or later time range.

The chart at the bottom shows the values for the tokens that implement the pan and zoom behavior.

157
Implementation details

To display zoom results in a separate chart, first edit the base chart in simple XML. Use the <selection> element to set
token values for the selection time range.

Note: See Token usage in dashboards for information on tokens. The section Define tokens for pan and zoom
chart controls provides details for tokens specific to pan and zoom behavior.

$start$
$end$
Predefined tokens that capture the values of the X-axis at the beginning and end of the selection time range. In this
example, capture the time at the beginning and end of a time chart. The value is in epoch time.

$start.splunk_web_access$
$end.splunk_web_access$
Captures the values of the Y-axis for the specified series at the beginning and end of the selection. In this example, the
value is the number of events for the field splunk_web_access.

The start and end tokens are valid only in the context of the chart. Assign the values to tokens that you define so you can
access the values throughout the dashboard.

<chart>
<title>Pan and Zoom (All source types)</title>
<search>
<query>
index=_internal | timechart count by sourcetype
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
. . .
<selection>
<set token="selection_earliest">$start$</set>
<set token="selection_latest">$end$</set>
<set token="start_splunk_web_access">$start.splunk_web_access$</set>
<set token="end_splunk_web_access">$end.splunk_web_access$</set>
</selection>
. . .
</chart>

In the target chart, use $selection_earliest$ and $selection_latest$ to access the selection time range.

<chart>
<title>Pan and Zoom (Web access source type)</title>
<search>
<query>
index=_internal sourcetype=splunk_web_access
| timechart count by sourcetype
</query>
<earliest>$selection_earliest$</earliest>
<latest>$selection_latest$</latest>
</search>
. . .
</chart>

The HTML panel shows the values captured by the $start$ and $selection$ tokens.

158
<html>
<h3>Token values for the splunk_web_access selection</h3>
<table border="0" cellpadding="12" cellspacing="0">
<tr>
<td>
<p><b>Time range (epoch time)</b></p>
<p><b>$$selection_earliest$$</b>: $selection_earliest$
<br /><b>$$selection_latest$$</b>: $selection_latest$</p>
</td>
<td>
<p><b>Count at the begining and end of time range.</b></p>
<p><b>$$start_splunk_web_access$$</b>: $start_splunk_web_access $
<br /><b>$$end_splunk_web_access$$</b>: $end_splunk_web_access$</p>
</td>
</tr>
</table>
</html>
Chart overlay

Use chart overlays to represent two different series on a single chart. You can highlight one series of search results as a
line graph on top of a column chart, area chart, or another line chart.

When using overlays, you can specify the overlaid values on a single axis or dual axis. With single axis, you plot the
overlaid value and the search results against the same Y-axis. For dual axis, you specify a second Y-axis to represent the
overlaid values.

Chart overlay example (single axis)

This example shows the count of splunk_web_access source type events over a time chart on a weekly basis for one
month. Overlaid on this chart is the weekly average count of these events.

159
Here is the search to create this chart:

index=_internal sourcetype=splunk_web_access | timechart span=1week count | eventstats avg(count) as average

| eval average=round(average,0)

You can create the overlay using the Visualization Editor.

1. From the dashboard, click Edit > Edit Panels.

2. Add a panel specifying the following:

♦ Content Title: Chart Overlay (Single Axis)

♦ Search String: The search string listed above.
♦ Time Range: 30 days.
3. For the chart overlay panel, click the Edit Properties icon. Click Chart Overlay.
4. Click in the Overlay field. Select average from the fields available for selection as an overlay.
5. For View as Axis, click Off.
This example does not specify a second Y-axis.

Chart overlay example (dual axis)

This example overlays the event count of the splunk_web_access source type against the total for all source types. The
chart plots the Web Access totals against a separate Y-axis.

Here is the search to create this chart:

index=_internal sourcetype=* | timechart span=1week count as "All Sourcetypes"

count(eval(sourcetype="splunk_web_access")) as "Web Access"

You can create the overlay using the Visualization Editor.

1. From the dashboard, click Edit > Edit Panels.

2. Add a panel specifying the following:

♦ Content Title: Chart Overlay (Dual Axis)

♦ Search String: The search string listed above.
♦ Time Range: 30 days.
3. For the chart overlay panel, click the Edit Properties icon. Click Chart Overlay.

160
4. Click in the Overlay field. Select Web Access from the fields available for selection as an overlay.
5. For View as Axis, click On to specify a second Y-axis.
6. For Title, click Custom. Type Web Access in the adjacent text field to specify a title for the second axis..
7. For Scale, click Inherit to inherit the selection for the scale from the first Y-axis.

161
Manage and Share Dashboards

Configure dashboard permissions

Learn how to manage dashboard and panel search permissions.

Managing dashboard permissions

A dashboard is a knowledge object. The roles that you hold as a Splunk platform user govern your ability to configure
dashboard permissions for yourself and others.

The following table shows the permissions management functions that the default roles in a new Splunk Platform
implementation grant.

Default Splunk Role Permission Management Abilities

User Create new dashboards that are private to you.

Create new dashboards that are private to you.

Power, Admin
Share private dashboards with users of an app, or users of all apps.
Set read and write access to a dashboard, by role.
Your implementation might have a different set of roles for its users. Or it could have the default roles but the permission
management abilities might be moved around between them. If you want more information about the permission
management capabilities of your role, talk to your Splunk administrator. For more information about role-based knowledge
object permissions management, see Manage knowledge object permissions in the Knowledge Manager Manual.

Managing panel search permissions

The search that drives a dashboard panel is a separate knowledge object from the dashboard. The search has its own
configurable permissions. Inline, or ad hoc searches, rather than saved searches, are not knowledge objects, so you don't
need permission to view visualizations that ad hoc searches drive. To limit access to ad hoc searches, as an admin, you
must restrict access to one of the knowledge objects that the ad hoc search depends on, such as an index or a source.

Panel search permissions

A saved panel search can run using the permissions of the person who created the saved search (the search owner) or
the person who views the dashboard (the search user). The search user context can affect results and what different
users see in a dashboard panel. For example, if you have permissions to an index that others do not, you might want to
run the saved search as the owner so that any other user will see the same results.

Depending on the results data access that you want to provide, you can adjust the permissions context for the search in
the Reports listing page. Locate the search on this page and select Edit > Edit Permissions to change whether the
search runs with the owner or user context. For more details about the permissions for saved searches and reports, see
Set report permissions.

Also, consider the enabled permissions for other knowledge objects in a dashboard, such as Field Extractions and Event
Types. For additional information on setting up permissions for other knowledge objects see Manage knowledge object
permissions in the Knowledge Manager manual.

162
Specify permissions for a new dashboard

When you create a new dashboard from the Search or Dashboard pages, you can configure permissions. Choose one of
the following options.

Option Description
Private Only you have permission to view and edit the dashboard. The dashboard is not visible to other users.

The dashboard is available to other users in the app context where it was created. For example, if you create the dashboard in the
Shared in
Search and Reporting app, the dashboard is visible to other users in this context. Depending on their permissions, other users
app
can edit the dashboard.

Update dashboard permissions

After creating a dashboard you can change the permissions:

1. Navigate to the Dashboards page in Search and Reporting.

2. Locate the dashboard whose permissions you are updating.
3. Under Actions, select Edit > Edit Permissions
4. Depending on your role and capabilities, specify the following details.
♦ Choose Owner to make the dashboard private.
♦ Select App to share the dashboard in the current app context or share the dashboard in All apps on the
Splunk platform instance.
♦ Grant read and write permissions
♦ Configure read (viewing) and writing (editing) privileges for other system users and/or roles.

Generate dashboard PDFs

Dashboard PDF generation includes the following options.

• Generate and save a dashboard PDF.

• Print dashboard PDFs.
• Schedule PDF email delivery.

There are some limitations to PDF generation. See "Limitations to PDF generation" for details.

For information on sending scheduled report PDFs as email attachments, see "Schedule reports", in the Reporting
Manual.

Generate and print dashboard PDFs

Generate a dashboard PDF

1. From the dashboard, select Export > Export PDF. The generated PDF appears in a browser window.
2. View, download, or print the PDF from the browser window.

Print a dashboard PDF

163
 1. From the dashboard, select Export > Print. The default print driver for your browser opens with print settings.

Real-time searches and integrated PDF generation

PDF generation has special time range handling for real-time searches. PDFs for real-time searches, reports, or
dashboards show results for the search time window relative to PDF generation time. As an example, when you generate
a PDF for a real-time search with a five minute time window, the PDF shows search results for the past five minutes.

PDFs for dashboard panels with "real-time all time" search time ranges show results for the search over all time.

Schedule PDF delivery

Authorized users can schedule PDF delivery for dashboards. To set up PDF delivery, select Export > Schedule PDF
delivery. Ensure that email notification settings are configured prior to scheduling PDF delivery.

For more information, see Configure email notification settings in the Alerting Manual.

Note: Scheduled PDF delivery is not available for dashboards that include forms or for dashboards converted to HTML.

Use tokens in scheduled dashboard delivery

Splunk software provides tokens that you can use to include information generated by a search in the fields of an email.
For scheduled PDF 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 PDF delivery to reference the app containing the
dashboard.

Search results from $app$

Tokens available for email notifications

This section lists common tokens you can use in scheduled email delivery of dashboards. 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. For scheduling PDF delivery, only the categories Search metadata and
Server information apply.

Category Description Context

Search metadata Information about the search. Scheduled PDF delivery of dashboards
Alert actions from search
Scheduled reports

164
 Category Description Context

Scheduled PDF delivery of dashboards

Server information Information about the Splunk server Alert actions from search
Scheduled reports

Alert actions from search

Search results Access results of a search
Scheduled reports

Alert actions from search

Job information Data specific to a search job
Scheduled reports
If you are using Splunk Enterprise, you can view the savedsearches.conf configuration file. This file lists attributes with
values 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 for the scheduled PDF delivery of
dashboards.

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

Token Description
$action.email.hostname$ Hostname of the email server.

$action.email.priority$ Priority of the email delivery.

$app$ Name of the app containing the dashboard.

$cron_schedule$ Cron schedule for PDF delivery.

$description$ Description of the dashboard.

$name$ Name of the dashboard.

$next_scheduled_time$ The next time the search runs.

$owner$ Owner of the dashboard.

$type$ Indicates if the search is from an alert, report, dashboard, or the search command.

$view_link$ Link to view the dashboard.

Tokens available from server

Common tokens that provide details available from your Splunk platform 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$ Instance build number.

$server.serverName$ Instance server name.

$server.version$ Instance version number.

165
Schedule PDF delivery of a dashboard

To schedule PDF delivery of a dashboard:

1. For the dashboard you want to schedule, select Export > Schedule PDF Delivery.
2. Select the Schedule PDF Delivery check box to enable PDF delivery.

3. Select a schedule
If you select Run on Cron Schedule see cron examples.
4. Specify email details.
You can use tokens in the Subject and Message fields.

♦ To, CC, and BCC email recipients.

Specify a comma-separated list of email recipients.
♦ Priority
Enforcement of priority depends on your email client.
♦ Subject
♦ Message
5. Select Paper Size and Paper Layout.
6. Click Save to save the schedule delivery settings.

To Discontinue a scheduled email delivery of a dashboard PDF

1. For the dashboard you want to discontinue PDF delivery, select Export > Schedule PDF Delivery.
2. Deselect the Schedule PDF Delivery.
3. Click Save to save the schedule delivery settings.

Scheduled views reports

Every time you schedule a PDF for delivery, a report called a scheduled view is created. These reports are "hidden," in
that they don't appear in Searches, Reports, and Alerts under Settings; they only appear as a stanza in

166
savedsearches.conf. The naming convention for these reports is _ScheduledView_<dashboard_name>, where
dashboard_name is the name of the corresponding dashboard. You should monitor how many of these searches are
running, especially if you are experiencing problems with concurrent search limits for your deployment.

Specify a cron schedule for PDF delivery

You can use cron notation to define a custom delivery schedule. Select the Cron option to input a schedule.

Cron parameters
When specifying a cron expression, only five cron parameters are available, not six. The sixth parameter for year,
common in other forms of cron notation, is not available.

The cron parameters, * * * * *, correspond to minute hour day month day-of-week.

Example expressions
Here are some example cron expressions.

*/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.
Additional configurations for PDF printing

Splunk Enterprise users can specify the following configurations for PDF printing.

• Maximum number of table rows to print

• Timeout setting for generating a PDF
• Whether to include a logo
• Enable usage of non-Latin fonts

Note: If you are using Splunk Cloud and want these settings changed, file a Support ticket.

Configure the number of rows in a table

By default, 1000 rows are generated for a simple results table in a dashboard panel. If you have a dashboard with a table
that has more than 1000 rows, the initial 1000 rows are rendered for the PDF, printing the results across several pages if
necessary.

Splunk Enterprise users can override the default number of rows generated for PDF in the limits.conf file.

To configure the maximum number of rows in a table that can be printed in PDF:

1. Open $SPLUNK_HOME/etc/system/local/limits.conf for editing.

Create this file if it does not already exist.
2. Specify the following property in the [pdf] stanza:

[pdf]
max_rows_per_table = <unsigned int>

167
 Note: This setting configures PDF settings for all tables in your Splunk deployment.

Configure the timeout setting for generating a PDF

The default timeout for generating a PDF is 3600 seconds, as specified in limits.conf. A complex search that is slow to
completion might need additional time to generate the PDF.

To configure the timeout for generating a PDF:

1. Open $SPLUNK_HOME/etc/system/local/limits.conf for editing.

Create this file if it does not already exist.
2. Specify the number of seconds to wait to generate a PDF. This property is in the [pdf] stanza:

[pdf]
render_endpoint_timeout = <unsigned int>

Note: This setting configures PDF generation timeout settings for all PDFs in your Splunk deployment.

Configure whether to include the Splunk logo for a PDF

By default, the Splunk logo is included in a generated PDF. You can override the default setting in alert_actions.conf.

To not include the Splunk logo in a generated PDF:

1. Open $SPLUNK_HOME/etc/system/local/alert_actions.conf for editing.

Create this file if it does not already exist.
2. Specify the following property in the [email] stanza:

[email]
reportIncludeSplunkLogo=0

Note: This setting configures settings for all generated PDFs in your Splunk deployment.

Enable usage of non-Latin fonts in PDFs

Splunk software comes prepackaged with a collection of Latin fonts, and also a set of CID fonts for handling Japanese,
Korean, Simplified Chinese, and Traditional Chinese.

You can control how Splunk software loads the CID fonts by making changes to the reportCIDFontList parameter in
alert_actions.conf. Specify fonts in a space-separated list. If multiple fonts provide a glyph for a given character code,
the glyph from the first font in the list is used.

The reportCIDFontList parameter is in the [email] stanza. Make any changes for font usage here:

$SPLUNK_HOME/etc/system/local/alert_actions.conf

Here are the CID fonts supported by default:

gb cns jp kor

These reference Simplified Chinese, Traditional Chinese, Japanese, and Korean respectively.

To skip loading any CID fonts, in the local version of alert_actions.conf, leave the value of reportCIDFontList blank.

168
If you want your PDFs to use another non-Latin font (such as Cyrillic or Greek) ask an administrator add the Unicode font
to $SPLUNK_HOME/share/splunk/fonts. Create the fonts directory if it doesn't already exist.

Note: When multiple fonts are installed, they are sorted by name in alphabetical order. For example, If you have Cyrillic
and Greek installed, Splunk software always chooses Cyrillic unless you change the name of the files in
$SPLUNK_HOME/share/splunk/fonts so that Greek comes first.

Limitations to PDF generation

Integrated PDF generation functionality has a few limitations.

• PDFs in languages, such as Hebrew, where text should appear in right to left order, are rendered with text in left
to right order.
• PDFs for dashboards with multiple panels in a row might generate with only a single panel per row.
• You cannot generate PDFs of dashboards that are built using advanced XML or HTML. PDF generation works
only with dashboards built with simple XML.
• You cannot generate PDFs for forms.
• PDF generation ignores charting customizations that are not supported by the JSChart charting library. The
finished PDF displays the panels as rendered in JSChart with the unsupported customizations removed.

Clone and manage dashboards

You can copy dashboards or select a dashboard to appear on the app home screen.

You can also adjust caching for deployments with large numbers of dashboards.

Clone a dashboard

Create a copy of a dashboard from the Dashboards page or using the dashboard editor.

Steps

From What to do

1. Locate the dashboard that you want to set as the home dashboard.
2. Select Edit > Clone.
Dashboards page
3. (Optional) Update the cloned dashboard title and id. Provide a
description.
4. Click Clone dashboard.

1. Click the ... button and select Clone.

Dashboard editor 2. (Optional) Update the cloned dashboard title and id. Provide a
description.
3. Click Clone dashboard.

Set a home dashboard

Configure a dashboard to appear on the app home page.

169
Steps

From What to do

1. Locate the dashboard that you want to set as the home

Dashboards listing page
dashboard.
2. Select Edit > Set as home dashboard.

Dashboard editor
1. Click the ... button and select Set as home dashboard.

Adjust UI caching to handle large numbers of dashboards

Splunk Enterprise deployments with several hundred or more dashboards might have slower UI performance.

To improve UI performance, increase the default max_view_cache_size setting in the web.conf configuration file. For
example, for an instance with 700 dashboards, you can increase this setting to 1000.

For more information, see the web.conf spec file.

170
Simple XML Reference

Simple XML reference

Dashboards and forms

dashboard

Root element of a view. A dashboard contains one or more rows, each of which can display one or more panels.

A dashboard can contain one or more global <search> elements that drive the data displayed in the dashboard. The
<panel> elements can contain one or more <search> elements that drive the data in each panel.

If the dashboard contains a global search, there must be a post-process search in a <panel> element to display data from
the search.

<dashboard>
<init> (0..1)
<label> (0..1)
<description> (0..1)
<search> (0..1)
<row> (1..n)
<panel> (0..n)
<search> (0..n)
<chart> | <event> | <html> | <map> | <single> | <table> (1..n)
<search> (0..n, for each visualization element)
Attributes

Name Type Default Description

hideChrome Boolean False Attributes to remove standard Splunk Web dashboard components from a dashboard.
hideAppBar
hideEdit If specified as a URL query string parameter without a value, set to "true". For
hideFilters
hideFooter
example, <dashboard_url>?hideChrome and <dashboard_url>?hideChrome= are
hideSplunkBar both handled as "true".
hideTitle
Chrome: Hide Splunk Bar, App Bar, and Footer.

App Bar: Lists applications and views.

Edit: Drop-down lists and components that enable editing of a dashboard. If

enabled, use Settings > User interface > Views or the Dashboards page to edit
the dashboard.

Filters: Hide form inputs to increase dashboard panel display space.

Footer: List of links and a copyright notice at the foot of the dashboard.

Splunk Bar: Top bar that provides a link to the home page and access to
Settings pages.

171
 Name Type Default Description
Title: The text defined in the <label> and <description> elements of the
dashboard.
For internal use.

isDashboard Boolean True

Indicates if a view is a dashboard or a view implemented with advanced XML
that is not a dashboard.
Indicates if the dashboard is listed in the Dashboards listing in an app and the navigation menus
isVisible Boolean True
for an app.

onunloadCancelJobs Boolean Specifies whether to cancel search jobs when a user navigates away from a dashboard.

Sets the dashboard refresh interval, in seconds. The dashboard reloads after the specified
refresh Integer 0
refresh interval.

Comma-separated list of custom js files to load. The files must be in a folder or subfolder of the
appserver/static directory.
$SPLUNK_HOME/etc/apps/<app_name>/appserver/static/

script String To reference custom js files from another app, specify the the app name when
referencing the file. For example, use the following reference.

<dashboard script="myApp:myScript.js">

Comma-separated list of custom stylesheets to use for the dashboard. The stylesheet files must
be in a folder or subfolder of the following directory.
$SPLUNK_HOME/etc/apps/<app_name>/appserver/static/

stylesheet text To reference a custom css file from another app, specify the the app name when
referencing the file. For example, use the following reference.

<dashboard stylesheet="myApp:myStyles.css">
Example

<dashboard script="myScript.js, myScript2.js" stylesheet="myLocalStyles.css, myApp:myAppStyles.css">

<label>Data inputs</label>
<description>Listing of data inputs</description>
<row>
<panel>
<chart>
<title>Source types last 7 days</title>
<search ref="Source types last 7 days report" />
</chart>
</panel>
</row>
</dashboard>
form

A dashboard that contains user input elements. The user input elements supply values for one or more search terms that
are used in searches in the form.

<form>

172
 <init> (0..1)
<label> (0..1)
<description> (0..1)
<search> (0..1)
<fieldset> (1)
<input> (1..n)
<row> (1..n)
<panel> (0..n)
<search> (0..n)
<chart> | <event> | <html> | <map> | <single> | <table> (1..n)
<search> (0..n, for each visualization element)
Attributes

Name Type Default Description

Attributes to remove standard components from a dashboard.

Chrome: Hide Splunk Bar, App Bar, and Footer.

App Bar: Lists applications and views.

Edit: Drop-down lists and related components that enable editing of a

hideChrome
hideAppBar
dashboard. If enabled, use Settings > User interface > Views or the
hideEdit Dashboards page to edit the dashboard.
hideFilters Boolean False
hideFooter Filters: Hide form inputs to increase dashboard panel display space.
hideSplunkBar
hideTitle
Footer: List of links and a copyright notice at the foot of the dashboard.

Splunk Bar: Top bar that provides a link to the home page and access to
Settings pages.

Title: The text defined in the <label> and <description> elements of the
dashboard.
For internal use.

isDashboard Boolean True

Indicates if a view is a dashboard or a view implemented with advanced XML
that is not a dashboard.
Indicates if the dashboard is listed in the Dashboards listing for an app and the navigation menus
isVisible Boolean True
for an app.

onUnloadCancelJobs Boolean Specifies whether to cancel search jobs when navigating away from a dashboard.

refresh Integer 0 Sets the refresh interval, in seconds. Dashboard reloads after the specified refresh interval.

Comma-separated list of custom JavaScript files to load. The files must be in the following
location. The files cannot be in a subdirectory.

$SPLUNK_HOME/etc/apps/<app_name>/appserver/static/
script String
To reference the custom JavaScript files from another app, specify the the app
name when referencing the file as follows:

<form script="myApp:myScript.js">

173
 Name Type Default Description
Comma-separated list of custom stylesheets to use for the dashboard. The stylesheet files must
be in the following location. The files cannot be in a subdirectory.

$SPLUNK_HOME/etc/apps/<app_name>/appserver/static/
stylesheet Text
To reference a custom stylesheet file from another app, specify the the app
name when referencing the file as follows:

<dashboard stylesheet="myApp:myStyles.css">
Example

<form script="myLocalScript.js, myApp:myAppScript.js" stylesheet="myStyles.css, myStyles2.css">

<label>Form example: source type time chart</label>
<fieldset autorun="true" submitButton="false">
<input type="dropdown" token="sourcetype_tok">
<label>Select a source type</label>
<default>splunkd</default>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd_ui_access">splunkd_ui_access</choice>
</input>
</fieldset>
<row>
<panel>
<chart>
<search>
<query>
index = _internal sourcetype=$sourcetype_tok$
| timechart count by sourcetype
</query>
<earliest>-7d</earliest>
<latest>-0d</latest>
</search>
</chart>
</panel>
</row>
</form>

174
panel

A container to display and group one or more panel visualization elements.

Two or more visualization elements in a panel group vertically. The exception is the single visualization element. Two or
more single elements group horizontally.

There are two types of panels, inline and reference.

• Inline panel: An inline panel contains one or more visualization elements. You can create and edit an inline panel
with the Dashboard Editor and the Panel Editor. You can also edit the panel in simple XML source code.

• Reference panel: A reference panel displays the contents of a prebuilt panel on a dashboard. A reference panel
contains a ref attribute and an optional app attribute that provide a reference to the prebuilt panel.

A reference panel does not recognize child elements of a <panel> element that you specify in the dashboard XML
code.

You cannot use the Panel Editor to edit the contents of a reference panel.

For more information on prebuilt panels, see Dashboard panels and Create and add a panel by reference.

Attributes

Name Type Default Description

(Required) Applies only to reference panels.

ref Text
References the name of a prebuilt panel. This is the name that appears in
Settings > User Interface > Panels.
(Optional) Applies only to reference panels.

See References the name of the app that contains the reference panel. The
app Text
description. app for a reference panel appears in Settings > User Interface > Panels.

Default value for app is the app that contains the dashboard.
Comma-separated
depends All tokens from the list of tokens must be defined to render this panel in a dashboard.
list of tokens

id Text (minimum two Identifier for the panel.

characters)
Only alphanumeric and underscore characters are valid. Cannot begin
with a number or the underscore character.

The following terms are reserved for internal use and cannot be used for
an id.

• dashboard
• search
• default
• submitted
• footer
• url

175
 Name Type Default Description
• header

Comma-separated
rejects Prevent panel rendering if one or more tokens in this list are defined.
list of tokens
Parent element

<row>

Inline panel

<row>
<panel> (0..n)
<title> (0..1)
<description> (0..1)
<search> (0..n)
<chart> | <event> | <html> | <map> | <single> | <table> (1..n)

Reference panel

<row>
<panel ref="[panel name]" [app="[app name]"]> (0..n)
<!-- Other <panel> child elements ignored -->

Child elements (Inline panel)

Element Type Default Description

<description> text Descriptive text to display in the panel.

A visualization element to display results of a search.

Panel visualization
text
element Can also be an <html> panel to display text with HTML mark-up. See Panel
visualization element.
Search string.
<search> text
A base search available for post process searches.
<title> text Display title for the panel.
Example

Grouping of chart visualizations and single value visualizations using the <panel> element.

<dashboard>
<label>Dashboard Panel Example</label>
<description></description>
<row>
<panel>
<chart>
<title>Chart grouping</title>
<search>
<query>
index=_internal source="*splunkd.log"
( log_level=ERROR OR log_level=WARN*

176
 OR log_level=FATAL OR log_level=CRITICAL )
| stats count as log_events
| rangemap field=log_events low=1-100 elevated=101-300 default=severe
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">radialGauge</option>
</chart>
<chart>
<search>
<query>
index=_internal source="*splunkd.log"
( log_level=ERROR OR log_level=WARN*
OR log_level=FATAL OR log_level=CRITICAL )
| stats count as log_events
| rangemap field=log_events low=1-100 elevated=101-300 default=severe
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">markerGauge</option>
</chart>
</panel>
</row>
<row>
<panel>
<single>
<title>Single value grouping</title>
<search>
<query>
index=_internal source="*splunkd.log"
( log_level=ERROR OR log_level=WARN*
OR log_level=FATAL OR log_level=CRITICAL )
| stats count as log_events
| rangemap field=log_events low=1-100 elevated=101-300 default=severe
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<option name="beforeLabel">Found</option>
<option name="afterLabel">errors</option>
</single>
<single>
<search>
<query>
index=_internal source="*splunkd.log"
( log_level=ERROR OR log_level=WARN*
OR log_level=FATAL OR log_level=CRITICAL )
| stats count as log_events
| rangemap field=log_events low=1-100 elevated=101-300 default=severe
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<option name="beforeLabel">Found</option>
<option name="afterLabel">errors</option>
</single>
</panel>
</row>
</dashboard>

177
row

A container for displaying one or more visualization elements in a horizontal layout of a dashboard or form.

Use the <panel> element to group visualization elements in a row.

Attributes

Name Type Default Description

Comma-separated
depends All tokens from the list of tokens must be defined to render this row in a dashboard.
list of tokens

grouping comma-separated No Deprecated. Use the <panel> element to group visualization elements.
list of integers grouping
Sets the grouping for the panels in a row according to a comma-separated list of
numbers representing the panels to be grouped. When you group panels, the
visualization for each grouped panel is placed in a container. With one exception,
you can consider the containers as columns for the panel visualizations.
Visualizations are placed one above the other in the container. If the grouping
contains only visualizations of type <single>, the visualizations are placed
side-by-side.

The first number in a grouping configures a group for the initial number of panels
specified for that group. Subsequent numbers in the list form a group for the next
set of panels.

For example, suppose you have a row with 6 visualizations. Specify the following
grouping:

<row grouping="2,1,3">

This creates a container with the first two panels, a second container with one
visualization, and a third container with the last three panels grouped.

178
 Name Type Default Description

Identifier for the row.

Only alphanumeric and underscore characters are valid. Cannot begin with a
number or the underscore character.

The following terms are reserved for internal use and cannot be used for an id:
Text (minimum two
id
characters)
• dashboard
• search
• default
• submitted
• footer
• url
• header

Comma-separated
rejects Prevent row rendering if one or more tokens in this list are defined.
list of tokens
Parent elements

<dashboard> | <form>

<row>
<panel> (0..n)

Example

See the example for the <panel> element. This example shows grouping of visualizations in row, using the <panel>
element.

label

Optional header text for a dashboard, form, or form input.

Parent element

<dashboard> | <form>

<label>[text]</label> (0..1)

Example

<form>
<label>Event count for different source types</label>
. . .
<fieldset>
<input type="text" token="series">
<label>Enter a source type</label>
<default></default>
<initialValue>splunkd</initialValue>
</input>
</fieldset>
. . .

179
</form>
description

Text that displays beneath a <dashboard>, <form>, or <panel>.

Parent element

<dashboard> | <form> | <panel>

Syntax

<description>[text]</description> (0..1)

Example

<dashboard>
<label>Event count for different source types</label>
<description>Listing of common source types</description>
. . .
<panel>
<title>Source types for the last 7 days</title>
<description>Count for each source type in the internal index</description>
. . .
. . .
</dashboard>

init

Use the <init> element to set or update token values when a dashboard or form opens. See Token usage in dashboards
to learn about using the <init> element to set tokens on page load.

Form inputs

fieldset

Defines the input elements to a form.

Attributes

Name Type Default Description

autoRun Boolean False Indicates whether to run the search when the page loads.

submitButton Boolean True Indicates whether to display a Submit button.

Parent element

<form>

<fieldset autoRun="[Boolean]" submitButton="[Boolean]">

<html> (0..n)
<input type="[input type]" token="[search token]"> (1..n)
<default> (0..1)

180
 <fieldForLabel> (0..1)
<fieldForValue> (0..1)
<initialValue> (0..1)
<label> (0..1)
<prefix> (0..1)
<search> (0..1)
<selectFirstChoice> (0..1)
<suffix> (0..1)
<populatingSearch> | <populatingSavedSearch> (0..1, deprecated)

Example

<fieldset autoRun="true" submitButton="false">

<input type="text" token="series">
<label>sourcetype</label>
<default></default>
<initialValue>splunkd</initialValue>
<suffix>*</suffix>
</input>
</fieldset>
checkbox

Defines a check box input to a form.

Attributes

Name Type Default Description

Comma-separated All tokens from the list of tokens must be defined to render this input. Tokens can
depends
list of tokens be from the context of form inputs or from the context of in-page drilldown.

Identifier for this input.

Text (minimum two
id
characters) Only alphanumeric and underscore characters are valid. Cannot
begin with a number or the underscore character.
Prevent input rendering if one or more tokens in this list are defined.
Comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context
of in-page drilldown.
searchWhenChanged Boolean False Specifies to run the search when the selection changes.

token String Specifies which token in the search string to replace with the specified value.

Parent element

<fieldset>

<input type="checkbox" token="[search token]"> (1..n)

<default> (0..1)
<delimiter> (0..1)
<initialValue> (0..1)
<label> (0..1)
<prefix> (0..1)
<search> (0..1)

181
 <suffix> (0..1)
<valuePrefix> (0..1)
<valueSuffix> (0..1)

Child elements

element Type Default Description

Specifies the input choices that set conditional actions.
<change> <condition>
The <change> element is not available for multiselect inputs. See <change>.
Specifies an input choice that sets conditional actions.
<condition> Input choice
See <condition> (input).
<default> Attribute value Specifies a default value for an input element.

A string that will be placed between each selected value. Typically, you specify " OR " or " AND "
<delimiter> text using upper case – do not specify the quote marks, but specify a space character before and
after the text.

Time expressions that specify the earliest and latest time parameters. Use with the <search>
element to dynamically populate choices for the input.
<earliest>
text
<latest> You can specify the time as relative time or absolute time. For relative time, use
relative time modifiers, as described in Specify time modifiers in your search. For
absolute time, specify the time in UNIX epoch time format.
<fieldForLabel> The field to use for the label and value when using the <search> element to dynamically
text
<fieldForValue> populate choices for the input.

The initial value of the input element.

<initialValue> Attribute value
The value for <default> overrides the value for <initialValue>.
<label> text Text displayed with the input element.

<prefix> text String prefixed to the value of the input element. Can be a regular expression.

Search that dynamically populates choices for the input. Use the ref attribute of the <search>
<search> text
element to reference a search from a report. See <search>.

<suffix> text String appended to the value of the input element. Can be a regular expression.

<valuePrefix> text String prefixed to the value of the input element. Can be a regular expression.

<valueSuffix> text String appended to the value of the input element. Can be a regular expression.
Example

This example produces the following string when a user selects One and Three from the multiselect:

("1*" AND "3*")

<fieldset>
<input type="checkbox" token="mv5">
<choice value="1">One</choice>
<choice value="2">Two</choice>
<choice value="3">Three</choice>
<delimiter> AND </delimiter>

182
 <prefix>(</prefix>
<suffix>)</suffix>
<valuePrefix>"</valuePrefix>
<valueSuffix>*"</valueSuffix>
</input>
</fieldset>
dropdown

Defines a dropdown input to a form.

Attributes

Name Type Default Description

comma-separated All tokens from the list of tokens must be defined to render this input. Tokens can
depends
list of tokens be from the context of form inputs or from the context of in-page drilldown.

Identifier for this input.

Text (minimum two
id
characters) Only alphanumeric and underscore characters are valid. Cannot
begin with a number or the underscore character.
Prevent input rendering if one or more tokens in this list are defined.
Comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context
of in-page drilldown.
searchWhenChanged Boolean False Specifies to run the search upon a new selection.

token String Specifies which token in the search string to replace with the specified value.
Parent element

<fieldset>

<input type="dropdown" token="[search token]"> (1..n)

<choice> (0..n)
<initialValue> (0..1)
<label> (0..1)
<default> (0..1)
<prefix> (0..1)
<search> (0..1)
<selectFirstChoice> (0..1)
<suffix> (0..1)

Child elements

element Type Default Description

<allowCustomValues> boolean false If true, enables the selection of custom values typed into the text field for the input.

Specifies the input choices that set conditional actions.

<change> <condition>
The <change> element is not available for multiselect inputs. See
<change>.
<choice value=[value]> text value: Required. Specifies the value to use for the choice.

183
 element Type Default Description
Specifies choices for a radio or dropdown element. <choice> Is the label
to use for the specified value.
Specifies an input choice that sets conditional actions.
<condition> Input choice
See <condition> (input).
<default> Attribute value Specifies a default value for an input element.

Time expressions that specify the earliest and latest time parameters. Use with the
<search> element to dynamically populate choices for the input.

<earliest> You can specify the time as relative time or absolute time. For relative
text
<latest>
time, use relative time modifiers, as described in Specify time modifiers in
your search. For absolute time, specify the time in UNIX epoch time
format.
<fieldForLabel> The field to use for the label and value when using the <search> element to dynamically
text
<fieldForValue> populate choices for the input.

The initial value of the input element.

<initialValue> Attribute value
The value for <default> overrides the value for <initialValue>.
<label> text Text displayed with the input element.

<prefix> text String prefixed to the value of the input element. Can be a regular expression.

Search that dynamically populates choices for the input. Use the ref attribute of the
<search> text
<search> element to reference a search from a report. See <search>.

Indicates if the first item listed is the default item for the input. If a value for <default> is
<selectFirstChoice> boolean false
present, <selectFirstChoice> is ignored.

Indicates if the clear button for the dropdown is present.

<showClearButton> boolean true

When present, the user clicks the clear button to change the choice to the
default value for the dropdown.
<suffix> String String appended to the value of the input element. Can be a regular expression.
Example

<form>
<label>Form example: source type time chart</label>
<fieldset autorun="true" submitButton="false">
<input type="dropdown" token="sourcetype_tok">
<label>Select a source type</label>
<default>splunkd</default>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd_ui_access">splunkd_ui_access</choice>
</input>
</fieldset>
<row>
<panel>
<chart>
<search>
<query>

184
 index = _internal sourcetype=$sourcetype_tok$
| timechart count by sourcetype
</query>
<earliest>-7d</earliest>
<latest>-0d</latest>
</search>
</chart>
</panel>
</row>
</form>

link

Defines a link switcher input to a form.

Attributes

Name Type Default Description

Comma-separated All tokens from the list of tokens must be defined to render this input. Tokens can
depends
list of tokens be from the context of form inputs or from the context of in-page drilldown.

Identifier for this input.

Text (minimum two
id
characters) Only alphanumeric and underscore characters are valid. Cannot
begin with a number or the underscore character.
Prevent input rendering if one or more tokens in this list are defined.
Comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context
of in-page drilldown.
searchWhenChanged Boolean False Specifies to run the search upon a new selection.

token String Specifies which token in the search string to replace with the specified value.
Parent element

<fieldset>

<input type="link" token="[search token]"> (1..n)

<choice> (0..n)
<initialValue> (0..1)

185
 <label> (0..1)
<default> (0..1)
<prefix> (0..1)
<search> (0..1)
<selectFirstChoice> (0..1)
<suffix> (0..1)

Child elements

element Type Default Description

<change> <condition> Specifies the input choices that set conditional actions. See <change>.

value: Required. Specifies the value to use for the choice.

<choice value=[value]> text

Specifies choices for the link input element. <choice> Is the label to use
for the specified value.
Specifies an input choice that sets conditional actions.
<condition> Input choice
See <condition> (input).
<default> Attribute value Specifies a default value for an input element.

Time expressions that specify the earliest and latest time parameters. Use with the
<search> element to dynamically populate choices for the input.

<earliest> You can specify the time as relative time or absolute time. For relative
text
<latest>
time, use relative time modifiers, as described in Specify time modifiers in
your search. For absolute time, specify the time in UNIX epoch time
format.
<fieldForLabel> The field to use for the label and value when using the <search> element to dynamically
text
<fieldForValue> populate choices for the input.

The initial value of the input element.

<initialValue> Attribute value
The value for <default> overrides the value for <initialValue>.
<label> text Text displayed with the input element.

<prefix> String String prefixed to the value of the input element. Can be a regular expression.

Search that dynamically populates choices for the input. Use the ref attribute of the
<search> text
<search> element to reference a search from a report. See <search>.

Indicates if the first item listed is the default item for the input. Overrides any value for
<selectFirstChoice> boolean false
<initialValue>. If a value for <default> is present, <selectFirstChoice> is ignored.

<suffix> String String appended to the value of the input element. Can be a regular expression.
Example

<form>
<label>Form with Link Selector</label>
<description></description>
<fieldset autoRun="True" submitButton="false">
<input type="link" token="field_tok">
<label>Select field to analyze</label>

186
 <default>Reason</default>
<choice value="reason">Reason</choice>
<choice value="log_level">Log level</choice>
<choice value="component">Component</choice>
</input>
</fieldset>
<row>
<panel>
<chart>
<title>Log level by $field_tok$</title>
<search>
<query>index=_internal source=*splunkd.log | stats count by $field_tok$</query>
<earliest>-30d</earliest>
<latest>now</latest>
</search>
<option name="charting.axisY.scale">log</option>
<option name="charting.chart">bar</option>
</chart>
</panel>
</row>
</form>

multiselect

Defines an input to a form that accepts multiple choices. When a user selects the input, defined choices appear as a
dropdown list. The user can also type directly in the input to filter the available choices.

Attributes

Name Type Default Description

Comma-separated All tokens from the list of tokens must be defined to render this input. Tokens can
depends
list of tokens be from the context of form inputs or from the context of in-page drilldown.

Identifier for this input.

Text (minimum two
id
characters) Only alphanumeric and underscore characters are valid. Cannot
begin with a number or the underscore character.
Prevent input rendering if one or more tokens in this list are defined.
comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context
of in-page drilldown.
searchWhenChanged Boolean False Specifies to run the search upon a new selection.

token text Specifies which token in the search string to replace with the specified value.
Parent element

<fieldset>

<input type="multiselect" token="[search token]"> (1..n)

<default> (0..1)
<delimiter> (0..1)
<initialValue> (0..1)
<label> (0..1)
<prefix> (0..1)

187
 <search> (0..1)
<suffix> (0..1)
<valuePrefix> (0..1)
<valueSuffix> (0..1)

Child elements

element Type Default Description

<allowCustomValues> boolean false If true, enables the selection of custom values typed into the text field for the input.

<default> Attribute value Specifies a default value for an input element.

A string that will be placed between each selected value. Typically, you specify " OR " or "
<delimiter> text AND " using upper case – do not specify the quote marks, but specify a space character
before and after the text.

Time expressions that specify the earliest and latest time parameters. Use with the
<search> element to dynamically populate choices for the input.

<earliest> You can specify the time as relative time or absolute time. For relative
text
<latest>
time, use relative time modifiers, as described in Specify time modifiers in
your search. For absolute time, specify the time in UNIX epoch time
format.
<fieldForLabel> The field to use for the label and value when using the <search> element to dynamically
text
<fieldForValue> populate choices for the input.

The initial value of the input element.

<initialValue> Attribute value
The value for <default> overrides the value for <initialValue>.
<label> text Text displayed with the input element.

<prefix> text String prefixed to the value of the input element. Can be a regular expression.

Search that dynamically populates choices for the input. Use the ref attribute of the
<search> text
<search> element to reference a search from a report. See <search>.

<suffix> text String appended to the value of the input element. Can be a regular expression.

<valuePrefix> text String prefixed to the value of the input element. Can be a regular expression.

<valueSuffix> text String appended to the value of the input element. Can be a regular expression.
Example

This example produces the following multiselect string for the search when a user selects splunkd and
splunk_web_access:

sourcetype ="splunkd" OR sourcetype ="splunk_web_access"

<form>
<label>Form with multiselect</label>
<fieldset autoRun="false" submitButton="true">
<html>

<strong>Multiselect choices</strong>

</html>
<input type="multiselect" token="sourcetype_tok" searchWhenChanged="false">
<label>Select one or more source types</label>

188
 <choice value="*">All</choice>
<choice value="splunk_web_access">splunk_web_access</choice>
<choice value="splunkd">splunkd</choice>
<choice value="splunk_ui_access">splunk_ui_access</choice>
<choice value="splunkd_access">splunkd_access</choice>

<!-- Build multi-selection search:

(sourcetype ="value1" OR sourcetype ="value2" OR ...)
-->
<prefix>(</prefix>
<valuePrefix>sourcetype ="</valuePrefix>
<valueSuffix>"</valueSuffix>
<delimiter> OR </delimiter>
<suffix>)</suffix>

</input>
</fieldset>
<row>
<panel>
<title></title>
<chart>
<search>
<query>index =_internal $sourcetype_tok$ | stats count by sourcetype</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">line</option>
<option name="charting.axisY.scale">log</option>
</chart>
</panel>
</row>
</form>

189
radio

Defines a radio input to a form.

Attributes

Name Type Default Description

Comma-separated All tokens from the list of tokens must be defined to render this input. Tokens can
depends
list of tokens be from the context of form inputs or from the context of in-page drilldown.

Identifier for this input.

Text (minimum two
id
characters) Only alphanumeric and underscore characters are valid. Cannot
begin with a number or the underscore character.
Prevent input rendering if one or more tokens in this list are defined.
Comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context
of in-page drilldown.
searchWhenChanged Boolean False Specifies to run the search upon a new selection.

token String Specifies which token in the search string to replace with the specified value.
Parent element

<fieldset>

<input type="radio" token="[search token]"> (1..n)

<choice> (0..n)
<initialValue> (0..1)
<label> (0..1)
<default> (0..1)
<prefix> (0..1)
<search> (0..1)
<selectFirstChoice> (0..1)
<suffix> (0..1)

Child elements

element Type Default Description

<change> <condition> Specifies the input choices that set conditional actions. See <change>.

value: Required. Specifies the value to use for the choice.

<choice value=[value]> text

Specifies choices for a radio or dropdown element. <choice> Is the label
to use for the specified value.
Specifies an input choice that sets conditional actions.
<condition> Input choice
See <condition> (input).
<default> Attribute value Specifies a default value for an input element.

<earliest> text Time expressions that specify the earliest and latest time parameters. Use with the
<latest> <search> element to dynamically populate choices for the input.

190
 element Type Default Description
You can specify the time as relative time or absolute time. For relative
time, use relative time modifiers, as described in Specify time modifiers in
your search. For absolute time, specify the time in UNIX epoch time
format.
<fieldForLabel> The field to use for the label and value when using the <search> element to dynamically
text
<fieldForValue> populate choices for the input.

The initial value of the input element.

<initialValue> Attribute value
The value for <default> overrides the value for <initialValue>.
<label> text Text displayed with the input element.

<prefix> String String prefixed to the value of the input element. Can be a regular expression.

Search that dynamically populates choices for the input. Use the ref attribute of the
<search> text
<search> element to reference a search from a report. See <search>.

Indicates if the first item listed is the default item for the input. If a value for <default> is
<selectFirstChoice> boolean false
present, <selectFirstChoice> is ignored.

<suffix> String String appended to the value of the input element. Can be a regular expression.
Example

<form>
<label>Form with radio input</label>
<description></description>
<fieldset autoRun="True" submitButton="false">
<input type="radio" token="field_tok">
<label>Select field to analyze</label>
<default>component</default>
<choice value="reason">Reason</choice>
<choice value="name">Name</choice>
<choice value="component">Component</choice>
</input>
</fieldset>
<row>
<panel>
<chart>
<title>Log level by $field_tok$</title>
<search>
<query>
index=_internal source=*splunkd.log | stats count by $field_tok$
</query>
<earliest>-30d</earliest>
<latest>now</latest>
</search>
<option name="charting.axisY.scale">log</option>
<option name="charting.chart">bar</option>
</chart>
</panel>
</row>
</form>

191
text

Defines a text input to a form.

Attributes

Name Type Default Description

Comma-separated All tokens from the list of tokens must be defined to render this input. Tokens can
depends
list of tokens be from the context of form inputs or from the context of in-page drilldown.

Identifier for this input.

Text (minimum two
id
characters) Only alphanumeric and underscore characters are valid. Cannot
begin with a number or the underscore character.
Prevent input rendering if one or more tokens in this list are defined.
Comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context
of in-page drilldown.
searchWhenChanged Boolean False Specifies to run the search when new text is entered.

token String Specifies which token in the search string to replace with the specified value.
Parent element

<fieldset>

<input type="text" token="[search token]"> (1)

<initialValue> (0..1)
<label> (0..1)
<default> (0..1)
<prefix> (0..1)
<suffix> (0..1)

192
Child elements

element Type Default Description

<change> <condition> Specifies the input choices that set conditional actions. See <change>.

Specifies an input choice that sets conditional actions.

<condition> Input choice
See <condition> (input).
<default> Attribute value Specifies a default value for an input element.

The initial value of the input element.

<initialValue> Attribute value
The value for <default> overrides the value for <initialValue>.
<label> text Text displayed with the input element.

<prefix> String String prefixed to the value of the input element. Can be a regular expression.

<suffix> String String appended to the value of the input element. Can be a regular expression.
Example

<form>
<label>Form with text input</label>
<description></description>
<fieldset autoRun="True" submitButton="false">
<input type="text" token="log_level_tok">
<label>Specify a log level</label>
<default>INFO</default>
</input>
</fieldset>
<row>
<panel>
<chart>
<title>Timechart for $log_level_tok$</title>
<search>
<query>
index=_internal source=*splunkd.log log_level="$log_level_tok$"
| timechart count by log_level
</query>
<earliest>-7d</earliest>
<latest>now</latest>
</search>
<option name="charting.axisY.scale">log</option>
<option name="charting.chart">line</option>
</chart>
</panel>
</row>
</form>

193
time

Specifies a time picker input to a form.

Use tokens to specify more than one time range picker. If you do not specify a token for a time picker, the time picker
becomes global. Any visualization that does not specify a time range, either through a reference to a time picker token or
directly in code, applies the time range from the global time picker.

Attributes

Name Type Default Description

Comma-separated All tokens from the list of tokens must be defined to render this input. Tokens can
depends
list of tokens be from the context of form inputs or from the context of in-page drilldown.

Identifier for this input.

Text (minimum two
id
characters) Only alphanumeric and underscore characters are valid. Cannot
begin with a number or the underscore character.
Prevent input rendering if one or more tokens in this list are defined.
comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context
of in-page drilldown.
Use tokens to associate a time picker with a panel.

token text When referencing a time picker token, use the earliest and latest
modifiers to the token to specify a time range. See the example
below.
searchWhenChanged Boolean False Specifies to run the search upon a new selection.
Parent element

<fieldset>

<input type="time" [ token="[text]" ] [ searchWhenChanged="[true|false]" ]> (0..n)

<label> (0..1)

194
 <default> (0..1)
[time preset] (0..1) |
<earliest> (0..1)
<latest> (0..1)
</default>

Child elements

element Type Default Description

Specifies the input choices that set conditional actions.
<change> <condition>
The <change> element is not available for multiselect inputs. See <change>.
Specifies an input choice that sets conditional actions.
<condition> Input choice
See <condition> (input).
Time expressions that specify the earliest and latest time parameters.

<earliest>
text You can specify the time as relative time or absolute time. For relative time, use
<latest>
relative time modifiers, as described in Specify time modifiers in your search. For
absolute time, specify the time in UNIX epoch time format.
Specifies a default value for an input element.

text
You can specify either a preset value, as listed in times.conf,
or
<default> or
time
the <earliestTime> and <latestTime> for a custom default time range.
modifier
See <earliestTime> and <latestTime> for details.
<label> text Text displayed with the input element.
Example

The default value for the time picker is set to the last seven days. The <chart> element in this example references the
$time_tok$ token for the time picker. The chart updates with any new selected time range.

<form>
<label>Form with time input</label>
<description/>
<fieldset submitButton="false">
<input type="dropdown" token="source_tok" searchWhenChanged="true">
<label>Select a source type</label>
<choice value="*">All</choice>
<search>
<query>
index=_internal | stats count by sourcetype
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<fieldForLabel>sourcetype</fieldForLabel>
<fieldForValue>sourcetype</fieldForValue>
<prefix>sourcetype="</prefix>

195
 <suffix>"</suffix>
<default>*</default>
</input>
<input type="time" token="time_tok" searchWhenChanged="true">
<label>Select time range</label>
<default>
<earliest>-7d@h</earliest>
<latest>now</latest>
</default>
</input>
</fieldset>
<row>
<panel>
<chart>
<title>$source_tok$ -- Count for last 7 days</title>
<search>
<query>
index=_internal $source_tok$ | timechart count
</query>
<earliest>$time_tok.earliest$</earliest>
<latest>$time_tok.latest$</latest>
</search>
<option name="charting.chart">column</option>
</chart>
</panel>
</row>
</form>

196
change
Parent elements

<input type="checkbox">
<input type="dropdown">
<input type="radio">
<input type="text">
<input type="time">

<change>
<condition>(0..n)
(<link> | <set> | <unset>) (1..n)

Attributes

No attributes for this element.

Example

Use the <change> element to capture the selected label and value from an input.

<form>
<label>Use tokens with input choices to capture input labels and values</label>
<fieldset submitButton="false">
<input type="radio" token="period_tok">
<label>Select a time range</label>
<choice value="-24h@h">Last 24 Hours</choice>
<choice value="-7d@d">Last 7 Days</choice>
<choice value="-30d@d">Last 30 Days</choice>
<default>Last 24 Hours</default>

<change>
<!-- use predefined input tokens to set -->
<!-- tokens for the selected label and value -->
<set token="date_label">$label$</set>
<set token="earliest_tok">$value$</set>
</change>

</input>
</fieldset>

<row>
<panel>
<title>Conditional Inputs</title>
<chart>
<!-- Display selected label in the title -->
<title>Source Type by $date_label$</title>

<search>
<query>index = _internal | timechart count by sourcetype</query>
<!-- use the value of earliest_tok -->
<!-- to set the time range -->
<earliest>$earliest_tok$</earliest>
<latest>now</latest>
</search>

<option name="charting.axisY.scale">log</option>
<option name="charting.axisTitleX.text">Time period</option>

197
 <option name="charting.axisTitleY.text">Events</option>
</chart>
</panel>
</row>
</form>

condition (input)

Specifies the scope of actions based on input choices. If the parent element <change> is not present, then the actions
apply to all choices. The <condition> element is not available for multiselect inputs.

Note: The <condition> element applies to both input elements and drilldown elements. See <condition> (drilldown) for
details.

Attributes

Name Type Default Description

Drilldown context only. Specifies the search field on which to implement the drilldown, or to set or unset a token.
field text *
See <condition> (drilldown).

Specifies the input <label> element to which the condition applies.

label text *
'*' applies the condition to all input <label> elements.
Specifies a job property-based condition to evaluate for a match.
match= text * For example, you can use <condition match="'job.resultCount' == 0"> to specify a condition to apply
when a search returns no results.

Specifies the input <value> element to which the condition applies.

value text *
'*' applies the condition to all input <value> elements.
Parent element

<change>

<condition>
(<link> | <set> | <unset>) (1..n)

198
Example

Use conditional inputs to select preset time ranges for a search.

The token for the selected choice appears in the title for the chart. The conditional token for the selected value drives the
data for the chart.

<form>
<label>Use tokens with conditional input choices</label>
<fieldset submitButton="false">
<input type="radio" token="period_tok">
<label>Select a time range</label>
<choice value="-24h@h">Last 24 Hours</choice>
<choice value="-7d@h">Last 7 Days</choice>
<choice value="-30d@h">Last 30 Days</choice>
<default>Last 24 Hours</default>

<!-- set condition based on the label defined by <choice> -->

<!-- Within each condition, specify a custom label for display -->
<!-- Capture the selected value in the token, earliest_tok -->
<change>
<condition label="Last 24 Hours">
<set token="date_label">Yesterday</set>
<set token="earliest_tok">$value$</set>
</condition>
<condition label="Last 7 Days">
<set token="date_label">Last week</set>
<set token="earliest_tok">$value$</set>
</condition>
<condition label="Last 30 Days">
<set token="date_label">Last month</set>
<set token="earliest_tok">$value$</set>
</condition>
</change>
</input>
</fieldset>
<row>
<panel>
<title>Conditional Inputs</title>
<chart>

<!-- Display selected label in the title -->

<title>$date_label$</title>

<search>
<query>index = _internal | timechart count by sourcetype</query>
<!-- use the value of earliest_tok -->
<!-- to set the time range -->
<earliest>$earliest_tok$</earliest>
<latest>now</latest>
</search>

<option name="charting.axisY.scale">log</option>
<option name="charting.axisTitleX.text">Time periods</option>
<option name="charting.axisTitleY.text">Events</option>
</chart>
</panel>
</row>

199
</form>

Panel visualization elements

chart

A panel displaying search data in chart format. The search driving the panel can be an inline search or a saved report,
which contains chart formatting parameters. For more information on saving reports, see Create and edit reports.

When you load a saved report in the chart panel, your saved report format also loads. However, you can override chart
formatting inline using the chart options.

Charts use named options to specify chart-specific properties. This reference lists the basic panel options for charts. See
the Chart Configuration Reference for a complete list of chart options.

Attributes

Name Type Default Description

All tokens from the list of tokens must be defined to render this row or panel.
Comma-separated
depends
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
id Text (minimum two Identifier for the visualization.
characters)
Only alphanumeric and underscore characters are valid. Cannot begin with a
number or the underscore character.

The following terms are reserved for internal use and cannot be used for an
id.

• dashboard
• search
• default
• submitted
• footer

200
 Name Type Default Description
• url
• header

Prevent visualization rendering if one or more tokens in this list are defined.
Comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
Parent elements

<row>
<panel>

<chart>
<title> (0..1)
<search> (0..1)
<earliest> (0..1)
<latest> (0..1)
<drilldown> (0..n)
<selection> (0..n, for charts of type area, line, and column only)
<option name="[property]"> (0..n)

Options

property Type Default Description

(area | bar | column |
fillerGauge | line |
charting.chart column Set the chart type.
markerGauge | pie |
radialGauge | scatter)

(top | left | bottom | right |

charting.legend.placement right Indicates the placement of the legend.
none)

All of the formatting options supported for chart. See

charting.* — —
the Custom Chart Reference for details.

height Number between 100-10000 250 Height, in pixels, of the chart.

Show the Export button at the bottom of the panel.

(See
link.exportResults.visible Boolean
description)
Default value: The value of link.visible.
Show the Inspect button at the bottom of the panel.
(See
link.inspectSearch.visible Boolean
description)
Default value: The value of link.visible.
Show the Open in Pivot button at the bottom of the
(See panel.
link.openPivot.visible Boolean
description)
Default value: The value of link.visible.
The alternative search to use for the Open in Search
link.openSearch.search search string —
button.

link.openSearch.searchEarliestTime (time modifier) (See The earliest time to use for the alternative search
description) specified by link.openSearch.search.

201
 property Type Default Description
Default value: The earliest time used by the
panel.

Specify the time using time modifiers. See

Specify time modifiers in your search for
information on specifying time modifiers.
The latest time to use for the alternative search
specified by link.openSearch.search.

Default value: The latest time used by the

(See panel.
link.openSearch.searchLatestTime (time modifier)
description)

Specify the time using time modifiers. See

Specify time modifiers in your search for
information on specifying time modifiers.
Open in
link.openSearch.text text The label to use for the Open in Search button.
Search

link.openSearch.viewTarget View name Search The target view for the Open in Search button.

Show the Open in Search button at the bottom of the

(See panel.
link.openSearch.visible Boolean
description)
Default value: The value of link.visible
link.visible Boolean true Show link buttons at the bottom of the panel.

Deprecated. Use the refresh attribute to specify a

refresh.auto.interval (Deprecated) Number 0
dashboard or search refresh interval.

refresh.time.visible Boolean true Display the refresh time indicator in the panel.

refresh.link.visible Boolean true Display the refresh link in the panel.

Example

Example line chart panel using an inline search. It limits results to a specified time window and provides labels for the X
and Y axes:

<dashboard>
<label>Top source types in the last week</label>
<row>
<panel>
<title>Chart example</title>
<chart>
<title>Top sourcetypes in the last week</title>
<search>
<query>
index=_internal source="*metrics.log" group=per_sourcetype_thruput
| timechart sum(kb) by series
</query>
<earliest>-1w</earliest>
<latest>now</latest>
</search>
<option name="height">200</option>
<option name="charting.chart">line</option>

202
 <option name="charting.axisY.scale">log</option>
<option name="charting.chart.nullValueMode">connect</option>
</chart>
</panel>
. . .
</row>
</dashboard>

event

A panel displaying search results as individual events.

Attributes

Name Type Default Description

All tokens from the list of tokens must be defined to render this panel.
Comma-separated
depends
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
Identifier for the visualization.

Only alphanumeric and underscore characters are valid. Cannot begin with a
number or the underscore character.

The following terms are reserved for internal use and cannot be used for an
Text (minimum two id.
id
characters)
• dashboard
• search
• default
• submitted
• footer
• url
• header

Prevent visualization rendering if one or more tokens in this list are defined.
Comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.

203
Parent elements

<row>
<panel>

<event>
<title> (0..1)
<search> (0..1)
<earliest> (0..1)
<latest> (0..1)
<fields> (0..1)
<option name="[property]"> (0..n)

Options

property Type Default Description

count Integer The maximum number of rows to display.

(Deprecated) Use the attribute rowNumbers

displayRowNumbers Boolean False
Toggle display of row numbers.
Deprecated. Enables (or disables) all type-specific drilldowns
(list.drilldown, table.drilldown, raw.drilldown).

Type-specific drilldown options override what is set

drilldown (all | none) all
here.

all: Drilldown is enabled.

none: Drilldown is disabled.
Deprecated. Toggle whether to show events or results.

entityName (events | results) events

Events are individual events, while results are created
by statistical operators.
Show the Export button at the bottom of the panel.
(See
link.exportResults.visible Boolean
description)
Default value: The value of link.visible.
Show the Inspect button at the bottom of the panel.
(See
link.inspectSearch.visible Boolean
description)
Default value: The value of link.visible.
Show the Open in Pivot button at the bottom of the panel.
(See
link.openPivot.visible Boolean
description)
Default value: The value of link.visible.
link.openSearch.search search string — The alternative search to use for the Open in Search button.

link.openSearch.searchEarliestTime (time modifier) (See The earliest time to use for the alternative search specified by
description) link.openSearch.search.

Default value: The earliest time used by the panel.

Specify the time using time modifiers.

204
 property Type Default Description
See Specify time modifiers in your search for
information on specifying time modifiers.
The latest time to use for the alternative search specified by
link.openSearch.search.

(See Default value: The latest time used by the panel.

link.openSearch.searchLatestTime (time modifier)
description)
Specify the time using time modifiers.
See Specify time modifiers in your search for
information on specifying time modifiers.
Open in
link.openSearch.text text The label to use for the Open in Search button.
Search

link.openSearch.viewTarget View name Search The target view for the Open in Search button.

Show the Open in Search button at the bottom of the panel.

(See
link.openSearch.visible Boolean
description)
Default value: The value of link.visible
link.visible Boolean true Show link buttons at the bottom of the panel.

Specifies how drilldown operates in the event listing:

full: Enables the entire entry for drilldown.

inner: Enables inner elements of the event listing for

(full | inner | outer
list.drilldown full drilldown.
| none)

outer: Enables outer elements of the event listing for

drilldown.

none: Disables drilldown.

list.wrap Boolean true Indicates whether to wrap the contents of the event listing.

maxLines Integer The maximum number of lines to display for each result/event.

Specifies how drilldown operates in the raw event listing:

full: Enables the entire entry for drilldown.

inner: Enables inner elements of the event listing for

(full | inner | outer
raw.drilldown full drilldown.
| none)

outer: Enables outer elements of the event listing for

drilldown.

none: Disables drilldown.

Deprecated. Use the refresh attribute to specify a dashboard or
refresh.auto.interval (Deprecated) Number 0
search refresh interval.

refresh.time.visible Boolean true Display the refresh time indicator in the panel.

205
 property Type Default Description
refresh.link.visible Boolean true Display the refresh link in the panel.

rowNumbers Boolean False Indicates whether to display row numbers.

Deprecated: Use list.drilldown or raw.drilldown instead.

Sets the segmentation of events displayed.

(none | inner | This affects what you can click on within the event.
segmentation none
outer | full)
If you specify segmentation together with either
list.drilldown or raw.drilldown,
the value of segmentation is ignored.
showPager Boolean True Toggle pagination on or off.

Deprecated. Enables wrapping of events. Replaced with

softWrap Boolean
list.wrap and table.wrap.

table.sortColumn text Specifies the column on which to sort for the table.

table.sortDirection (asc | desc) asc Indicates the sort direction for items in the table.

Indicates whether drilldown functionality is enabled for the table.

table.drilldown (all | none) all

all: Drilldown is enabled.
none: Drilldown is disabled.
table.wrap Boolean True Indicates whether text in the table wraps.

type (list | raw | table) list Indicates the format for displaying events.
Example

<dashboard>
<label>Event listing by size</label>
<row>
<panel>
<title>Event example</title>
<event>
<title>Event view</title>
<search>
<query>
index = _internal current_size_kb < 1
</query>
<earliest>-1w</earliest>
<latest>now</latest>
</search>
<option name="showPager">true</option>
<option name="count">4</option>
<option name="rowNumbers">false</option>
</event>
</panel>
</row>
</dashboard>

206
html

The HTML panel displays inline HTML. The panel interprets the entire contents between the HTML tags literally,
displaying HTML formatted text in the panel.

Any relative link references, such as images, are relative to the current view location. The HTML panel does not accept
any options.

Attributes

Name Type Default Description

All tokens from the list of tokens must be defined to render this panel.
Comma-separated
depends
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
For internal use only. If true, the dashboard uses decoded text content instead of the XML
encoded boolean false
content.

Identifier for the visualization.

Only alphanumeric and underscore characters are valid. Cannot begin with a
number or the underscore character.

The following terms are reserved for internal use and cannot be used for an id.
Text (minimum two
id
characters)
• dashboard
• search
• default
• submitted
• footer
• url
• header

Prevent visualization rendering if one or more tokens in this list are defined.
comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
src String

207
 Name Type Default Description
Put the contents of an HTML or image file into the <html> panel. Directory locations and Simple
XML syntax are different for HTML files and image files.

HTML file from the same app context

<html src="<file_name>.html">
</html>

HTML file from a different app context

<html src="<other_app_name>:<file_name>.html">
</html>

Image file

<html>
<img src="/static/app/<app_name>/images/<file_name>.png">
</img>
</html>

See the following instructions for details on where to save HTML and image files
and how to reference files from different app contexts.
tokens boolean true If false, disables token replacement for the <html> panel.

Use an HTML file in a dashboard panel

Steps

1. Put the HTML file in the following directory. $SPLUNK_HOME/etc/apps/<appname>/appserver/static

2. In the <html> panel, use this syntax to indicate a file from the current app context.
<html src="<file_name>.html">
</html>

If you are specifying an HTML file from another app context, use this syntax.

<html src="<other_app_name>:<file_name>.html">
</html>

Use an image file in a dashboard panel

Steps

1. Put the image file in the following directory. $SPLUNK_HOME/etc/apps/<appname>/appserver/static/images

If an /images directory does not already exist, create one and put the file in it.
2. Verify that the image file path is accessible by testing the following URL.
http://<host>:<port>/static/app/<app_name>/images/<image>

208
 For example, use this URL to verify that the my_image.png file is accessible.

http://localhost:8000/static/app/search/images/my_image.png
3. In the <html> panel, use this syntax to indicate a file from the current app context.

<html>
<img src="/static/app/search/images/<file_name>.png">
</img>
</html>

Example

<dashboard>
<label>test_db</label>
<row>
<panel>
<html>
<!-- Use an image from the current app's /static/images directory -->
<img src="/static/app/search/images/my_image.png"></img>
</html>
</panel>
<panel>
<!-- Use an HTML file from the webhook app. -->
<html src="alert_webhook:my_html_file.html">
</html>
<!--Use an image from the webhook app static/images directory -->
<html>
<img src="/static/app/alert_webhook/images/my_other_image.png"></img>
</html>
</panel>
</row>
</dashboard>
Parent elements

<row>
<panel>

<html>

Example

HTML panel showing how to reference a local image:

<dashboard>
<label>Dashboard with HTML content</label>
<row>
<panel>
<title>HTML panel</title>
<html>
<h1>Example HTML</h1>
<p>The HTML panel displays inline HTML.</p>
<p>
The panel interpets the entire contents between the HTML tags literally, displaying
HTML formatted text in the panel. The HTML panel does not accept any options.
</p>
<p>

209
 Any relative link references, such as images,
are relative to the current view location.
</p>
<p>
For the following image in the Search app: <img src="/static/app/search/appIcon.png"/>
</p>
<p>Path to the image in your Splunk instance:
<pre>$SPLUNK_HOME/etc/apps/search/appserver/static/appIcon.png</pre>
Access the image with the following HTML source code:
<pre><img src="/static/app/search/appIcon.png" /></pre>
</p>
</html>
</panel>
<panel>
<title>HTML from source file</title>
<html src="Test_for_html_panel.html" />
</panel>
</row>
</dashboard>

map

Provides for mapping geographic coordinates as interactive markers on a world map. This visualization depends on
results from the geostats search command.

See "geostats" in the Search Reference for details on implementing a geostats search.

You can create choropleth maps with the <map> element. See Choropleth maps. For choropleth map simple XML options,
see Choropleth map options.

Attributes

Name Type Default Description

All tokens from the list of tokens must be defined to render this panel.
Comma-separated
depends
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
id Identifier for the visualization.

210
 Name Type Default Description
Text (minimum two Only alphanumeric and underscore characters are valid. Cannot begin with a
characters) number or the underscore character.

The following terms are reserved for internal use and cannot be used for an
id.

• dashboard
• search
• default
• submitted
• footer
• url
• header

Prevent visualization rendering if one or more tokens in this list are defined.
comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
Parent elements

<row>
<panel>

<map>
<title> (0..1)
<search> (0..1)
<earliest> (0..1)
<latest> (0..1)
<option name="[property]"> (0..n)

Options

property Type Default Description

all: Drilldown is enabled.
drilldown (all | none) all
none: Drilldown is disabled.
The height in pixels of the map element.
height integer 400
Minimum value is 200.
Show the Export button at the bottom of the panel.
(See
link.exportResults.visible Boolean
description)
Default value: The value of link.visible.
Show the Inspect button at the bottom of the panel.
(See
link.inspectSearch.visible Boolean
description)
Default value: The value of link.visible.
link.openSearch.search search string — The alternative search to use for the Open in Search button.

link.openSearch.searchEarliestTime (time modifier) (See The earliest time to use for the alternative search specified by
description) link.openSearch.search.

211
 property Type Default Description
Default value: The earliest time used by the panel.

Specify the time using time modifiers. See Specify time

modifiers in your search for information on specifying
time modifiers.
The latest time to use for the alternative search specified by
link.openSearch.search.

(See Default value: The latest time used by the panel.

link.openSearch.searchLatestTime (time modifier)
description)
Specify the time using time modifiers. See Specify time
modifiers in your search for information on specifying
time modifiers.
Open in
link.openSearch.text text The label to use for the Open in Search button.
Search

link.openSearch.viewTarget View name Search The target view for the Open in Search button.

Show the Open in Search button at the bottom of the panel.

(See
link.openSearch.visible Boolean
description)
Default value: The value of link.visible
link.visible Boolean true Show link buttons at the bottom of the panel.

The maximum number of clusters to render.

mapping.data.maxClusters Integer 100 Caution: Setting this option to a large number of

clusters can significantly degrade performance. Splunk
recommends values below 1000.
field:hexvalue, A comma-separated map of field names to hexadecimal color
mapping.fieldColors
... values (0xRRGGBB) to define colors for specific series.

The initial center point of the map. Latitude values can range from
-85 to 85, with values outside of this range being clipped. Longitude
mapping.map.center (lat,long)
values can range from -180 to 180, with values outside of this range
being wrapped to fall within it.

mapping.map.scrollZoom Boolean false Indicates whether the map zooms when a user scrolls the map.

mapping.map.panning Boolean true Indicates whether the map pans when dragged.

mapping.map.zoom Number 2 The initial zoom level of the map.

The initial bounds to fit within the map view area. Latitude values
can range from -85 to 85, with values outside of this range being
clipped.

(south-lat,
west-long, Longitude values can range from -180 to 180, with
mapping.map.fitBounds values outside of this range being wrapped to fall within
north-lat,
east-long) it.

Values assigned to this property effectively override any

values assigned to the center or zoom properties.
mapping.markerLayer.markerOpacity Number 0.8

212
 property Type Default Description
The opacity of the markers. Values can range from 0 (transparent)
to 1 (opaque).

mapping.markerLayer.markerMinSize Number 10 The minimum size of the markers, in pixels.

mapping.markerLayer.markerMaxSize Number 50 The maximum size of the markers, in pixels.

A list of hexadecimal color values (0xRRGGBB) from which to

mapping.seriesColors hexvalue, . . . Default* sample colors for series with no specific colors assigned using the
fieldColors property.

mapping.showTiles boolean true Determines whether the map tiles are shown.

Specifies the opacity of the tiles. Values can range from 0

mapping.tileLayer.tileOpacity text 1
(transparent) to 1 (opaque).

The URL to use for requesting tiles, based on the following

See template:
mapping.tileLayer.url URL template
description
http://(s).tile.openstreetmap.org/(z)/(x)/(y).png
A list of subdomains to distribute tile requests over. More
subdomains allows more tiles to be requested simultaneously.
mapping.tileLayer.subdomains [string,. . .] [a,b,c]

See example below.

mapping.tileLayer.minZoom Integer 0 The minimum zoom level of the tileset.

The maximum zoom level of the tileset.

mapping.tileLayer.maxZoom Integer 7
Use any non-negative integer to specify the maximum
zoom level.
Whether to invert the y coordinate for tile requests. TMS servers use
mapping.tileLayer.invertY Boolean False
inverse y-axis numbering.

A copyright attribution to be displayed in the bottom right corner of

the map. The default value:
See
mapping.tileLayer.attribution String
description
Map data (c) 2012 OpenStreetMap contributors,
CC-BY-SA. See example below.
("marker" | See The type of map to render. Allowed values are "marker" and
mapping.type
"choropleth") description "choropleth". Default is "marker".

Deprecated. Use the refresh attribute to specify a dashboard or

refresh.auto.interval (Deprecated) Number 0
search refresh interval.

refresh.time.visible Boolean true Display the refresh time indicator in the panel.

refresh.link.visible Boolean true Display the refresh link in the panel.

* Default value for mapping.seriesColors:

[0x6CB8CA,0xFAC61D,0xD85E3D,0x956E96,0xF7912C,0x9AC23C,0x5479AF,0x999755,0xDD87B0,0x65AA82,
0xA7D4DF,0xFCDD77,0xE89E8B,0xBFA8C0,0xFABD80,0xC2DA8A,0x98AFCF,0xC2C199,0xEBB7D0,0xA3CCB4,
0x416E79,0x967711,0x823825,0x59425A,0x94571A,0x5C7424,0x324969,0x5C5B33,0x85516A,0x3D664E]

213
Choropleth map options

Name Type Default Description

mapping.choroplethLayer.colorBins integer 5 Specifies the number of color bins to use.

Specifies the color mode to use for the choropleth

"sequential" | "divergent" |
mapping.choroplethLayer.colorMode 'auto' shapes. Possible modes are 'sequential',
"categorical")
'divergent', or 'categorical'.

Specifies the color to use for the highest value

mapping.choroplethLayer.maximumColor text DB5800
shapes.

Only used when the color mode is divergent. The

mapping.choroplethLayer.minimumColor text 2F25BA
color to use for the lowest value shapes.

Only used when the color mode is divergent. The

mapping.choroplethLayer.neutralPoint text 0 value where the color palette should switch from
using the minimum color to the maximum color.

Specifies the opacity of the

mapping.choroplethLayer.shapeOpacity shapes. Values can range from 0 text 0.75
(transparent) to 1 (opaque).

Specifies whether to show borders around each

mapping.choroplethLayer.showBorder Boolean true
shape.

mapping.showTiles Boolean true Determines whether the map tiles are shown.

Specifies the opacity of the tiles. Values can

mapping.tileLayer.tileOpacity text 1
range from 0 (transparent) to 1 (opaque).
mapping.data.maxClusters example

The following example sets the maximum number of clusters to 250:

<map>
<option name="mapping.data.maxClusters">250</option>
</map>
mapping.fieldColors and mapping.seriesColors example

The following example configures the "foo" and "bar" fields to be red (0xFF0000) and green (0x00FF00), respectively, and
configures all other fields to be blue (0x0000FF):

<map>
<option name="mapping.fieldColors">{foo:0xFF0000,bar:0x00FF00}</option>
<option name="mapping.seriesColors">[0x0000FF]</option>
</map>
mapping.map.fitBounds example

The following example initializes the map view to a boundary around San Francisco:

<map>
<option name="mapping.map.fitBounds">
(37.5,-123,38,-122)
</option>
</map>

214
mapping.tileLayer.* example

The following example configures the client to request tiles from openstreetmap.org (this is the default configuration):

<map>
<option name="mapping.tileLayer.url">http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png</option>
<option name="mapping.tileLayer.subdomains">[a,b,c]</option>
<option name="mapping.tileLayer.maxZoom">18</option>
<option name="mapping.tileLayer.attribution">
Map data (c) 2012 OpenStreetMap contributors, CC-BY-SA.
</option>
</map>
map example, using foursquare data

This example assumes you are indexing foursquare data as source foursquare. It produces the map depicted below.

<map>
<title>Roma</title>
<search>
sourcetype=foursquare
| geostats latfield=checkin.geolat longfield=checkin.geolong count by checkin.user.gender
</search>
<option name="mapping.data.maxClusters">500</option>
<option name="mapping.markerLayer.markerMaxSize">20</option>
<option name="mapping.map.fitBounds">(41.3,12.7,41.5,12.8)</option>
<option name="mapping.seriesColors">[0x0060DD]</option>
<option name="mapping.map.zoom">4</option>
</map>

215
single

Element for a single value visualization. This visualization type shows results for a search returning a single discrete
value.

If you specify a search that returns multiple values, the single value panel displays the value from either the first row or
first column of returned search data.

Attributes

Name Type Default Description

All tokens from the list of tokens must be defined to render this panel.
Comma-separated
depends
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
Identifier for the visualization.

Only alphanumeric and underscore characters are valid. Cannot begin with a
number or the underscore character.

The following terms are reserved for internal use and cannot be used for an
Text (minimum two id.
id
characters)
• dashboard
• search
• default
• submitted
• footer
• url
• header

Prevent visualization rendering if one or more tokens in this list are defined.
Comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
Parent elements

• <row>
♦ <panel>

Element structure

<single>
<title> (0..1)
<search> (0..1)
<earliest> (0..1)
<latest> (0..1)
<option name="[property]"> (0..n)

Options

Property Type Default Description

216
 Deprecated. Use the Format menu in Splunk Web to
additionalClass CSS class name configure single value visualization ranges and color
mapping.

afterLabel string Deprecated. Use underLabel for a descriptive caption.

beforeLabel string Deprecated. Use underLabel for a descriptive caption.

(classname | severe | Deprecated. Use the Format menu in Splunk Web or

classField high | elevated | combine the colorBy, rangeValues, and rangeColors
guarded | low | None) Simple XML options to configure ranges and colors.

Specifies whether all single value components are

colored by delta value's color ("trend"), or by value's
severity color ("value"). The only available colors are red,
green, and black. By default, or if
colorBy ("trend" | "value") '"value" trendColorInterpretation is set to "standard", a positive
trend color is green, a 0 trend value is black, and a
negative trend value is red. If trendColorInterpretation is
set to "inverse", then a positive trend is red, negative is
green.

Specifies what part of the visualization shows range

color.

block: Background displays the range color

colorMode ("block" | "none") "none"
with white text.

none: White background. Text displays the

range color.
all: Drilldown enabled.
none: Drilldown disabled.

drilldown (all | none) none

This option applies to the <drilldown> element
to implement dynamic drilldown for single
values.
field field name First field returned The field to display

height integer 115 Determines the single value's height in pixels.

Show the Export button at the bottom of the panel.

link.exportResults.visible boolean (See description)
Default value: The value of link.visible.
Show the Inspect button at the bottom of the panel.
link.inspectSearch.visible boolean (See description)
Default value: The value of link.visible.
Show the Open in Pivot button at the bottom of the
panel.
link.openPivot.visible boolean (See description)

Default value: The value of link.visible.

Indicate a non-default search string to use when users
link.openSearch.search search string —
click the "Open in Search" button.

link.openSearch.searchEarliestTime (time modifier) (See description) The earliest time to use for the alternative search
specified by link.openSearch.search.

217
 elevated: yellow |
guarded: blue | low: rangeValues appear dark gray if metric falls within that
green) range.

You can specify any number of colors.

A numeric array that specifies the range limits for viz
coloring. If there are more rangeColor hex values than
ranges, excess rangeColor values at end of array will be
Property Type Default Description
ignored. If there are more rangeValues than
rangeValues numeric array no default rangeColors, then excess rangeValues appear dark gray
if metric falls within that range.

Use the rangeColors attribute to customize

severity levels and colors.
Deprecated. Use the refresh attribute to specify a
refresh.auto.interval integer 0
dashboard or search refresh interval.

refresh.time.visible boolean true Display the refresh time indicator in the panel.

refresh.link.visible boolean false Display the refresh link in the panel.

Specifies whether the single value hides its sparkline, if

available.

showSparkline boolean true

A sparkline is available for searches that use
the timechart search command for the search
results.
Specifies whether the single value hides its delta value, if
showTrendIndicator boolean true
available.

("standard" | Specifies whether a field value greater than 0 is a

trendColorInterpretation "standard"
"inverse") positive (standard) or negative (inverse) development.

("percent" | Specifies whether the delta amount is displayed as a

trendDisplayMode "absolute"
"absolute") percentage or an absolute count.

Specifies time range in the past from which to calculate a

delta from the most recent data point in the same metric.
trendInterval text "auto" Use the search syntax for time modifiers to indicate the
range. For more information, see Specify time modifiers
in your search in the Search Manual.

underLabel string Caption for the visualization.

Measurement unit for the single value. Use a short
unit string string, such as "$" or "days". Use underLabel to add a
descriptive caption.

Position for the unit, relative to the single value. Use

unitPosition before or after either before or after to place the unit before or after
the single value.

Specifies whether all single value components are

useColors boolean false colored. Must be set to true for text coloring and color
options availability.

Specifies whether to format the result value with

useThousandSeparators boolean true
thousand separators.
table

A panel displaying search data as a table.

Attributes

Name Type Default Description

depends All tokens from the list of tokens must be defined to render this panel.

218
 Name Type Default Description
Comma-separated Tokens can be from the context of form inputs or from the context of in-page
list of tokens drilldown.
Identifier for the visualization.

Only alphanumeric and underscore characters are valid. Cannot begin with a
number or the underscore character.

The following terms are reserved for internal use and cannot be used for an
Text (minimum two id.
id
characters)
• dashboard
• search
• default
• submitted
• footer
• url
• header

Prevent visualization rendering if one or more tokens in this list are defined.
comma-separated
rejects
list of tokens Tokens can be from the context of form inputs or from the context of in-page
drilldown.
Parent elements

<row>
<panel>

<table>
<title> (0..1)
<search> (0..1)
<earliest> (0..1)
<latest> (0..1)
<fields> (0..1)
<drilldown> (0..n)
<format type="sparkline" field="[field name]"> (0..n)
<option name="[property]"> (0..n)

Child element

element Type Default Description

A set of formatting options that determines how sparklines display in tables.
<format> text
See Sparkline options for details.
Options

property Type Default Description

count Integer 10 The maximum number of rows to display.

(heatmap |
dataOverlayMode None Indicates which type of overlay to display.
highlow)

219
 property Type Default Description
displayRowNumbers Boolean True (Deprecated) Use the rowNumbers attribute.

Enables drilldown on row or cell level, or disables drilldown.

all, cell: Enables drilldown. These two values are

equivalent. Enables drilldown on the cell level.
(all | cell | row |
drilldown cell
none | off) row: Enables drilldown for a row.

none: Disables drilldown but preserves hypertext styling.

off: Disables drilldown and removes hypertext styling

Show the Export button at the bottom of the panel.
(See
link.exportResults.visible Boolean
description)
Default value: The value of link.visible.
Show the Inspect button at the bottom of the panel.
(See
link.inspectSearch.visible Boolean
description)
Default value: The value of link.visible.
Show the open in Pivot button at the bottom of the panel.
(See
link.openPivot.visible Boolean
description)
Default value: The value of link.visible.
link.openSearch.search search string — The alternative search to use for the Open in Search button.

The earliest time to use for the alternative search specified by

link.openSearch.search.

(See Default value: The earliest time used by the panel.

link.openSearch.searchEarliestTime (time modifier)
description)
Specify the time using time modifiers. See Specify time
modifiers in your search for information on specifying
time modifiers.
The latest time to use for the alternative search specified by
link.openSearch.search.

(See Default value: The latest time used by the panel.

link.openSearch.searchLatestTime (time modifier)
description)
Specify the time using time modifiers. See Specify time
modifiers in your search for information on specifying
time modifiers.
Open in
link.openSearch.text text The label to use for the Open in Search button.
Search

link.openSearch.viewTarget View name Search The target view for the Open in Search button.

Show the Open in Search button at the bottom of the panel.

(See
link.openSearch.visible Boolean
description)
Default value: The value of link.visible
link.visible Boolean true Show link buttons at the bottom of the panel.

percentagesRow Boolean false Add a percentages summary row to the table.

220
 property Type Default Description

*Note: This option is deprecated.

previewResults Boolean True
Enable preview of results before the search is complete.

Deprecated. Use the refresh attribute to specify a dashboard or

refresh.auto.interval (Deprecated) Number 0
search refresh interval.

refresh.time.visible Boolean true Display the refresh time indicator in the panel.

refresh.link.visible Boolean true Display the refresh link in the panel.

rowNumbers Boolean False Toggle display of row numbers.

showPager Boolean True Toggle pagination on or off.

totalsRow Boolean false Add a column totals summary row to the table.

wrap Boolean True Enable wrapping of text in the results table.

Example

Example of a table panel using an inline search, displaying five rows, and disabling row numbers:

<dashboard>
<label>Dashboard with Table</label>
<row>
<panel>
<table>
<title>Top source types in the last 24 hours</title>
<search>
<query>
index=_internal group=per_sourcetype_thruput
| chart sum(kb) by series | sort -sum(kb)
</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<option name="count">5</option>
<option name="rowNumbers">0</option>
</table>
</panel>
</row>
</dashboard>

221
title

Specifies text for the title of a <panel> element or the title for visualization elements.

Attributes

No attributes for <title>

Parent elements

<panel>

<chart> | <event> | <html> | <map> | <single> | <table>

<panel>
<title> (0..1) <!-- Title at panel level -->
<chart> | <event> | <html> | <map> | <single> | <table> (1..n)
<title> (0..1) <!-- Title at visualization level -->

Examples

Specify a title for the <panel> containing a <table> visualization:

<panel>
<title>Top sourcetypes in the last 24 hours</title>
<table>
<search>
<query>
index=_internal group=per_sourcetype_thruput
| chart su(kb) by series | sort -sum(kb)
</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<option name="count">5</option>
<option name="rowNumbers">0</option>
</table>
</panel>
Specify a title for the <table> visualization:

<panel>
<table>
<title>Top sourcetypes in the last 24 hours</title>
<search>
<query>
index=_internal group=per_sourcetype_thruput
| chart su(kb) by series | sort -sum(kb)
</query>
<earliest>-24h</earliest>
<latest>now</latest>
</search>
<option name="count">5</option>
<option name="rowNumbers">0</option>
</table>
</panel>

222
Sparkline options

Note: for sparklines with single value visualizations, see the "<single>" subheading in this topic.

<format type="sparkline" field="[field name]">

Attributes

Name Type Default Description

field Field name Required. Specifies the field to which the sparkline is applied.

type String sparkline Required. sparkline is the only type supported. Specifies that a sparkline is being formated.
A set of formatting options that determines how sparklines display in tables. Sparkline options are only applicable to the
<table> element. Specify a sparkline option using the <format> element within a <table> element.

Do not confuse the sparkline options here, which format a sparkline, with the sparkline function to the chart or stats
search command. The formatting options listed here require a search that uses the sparkline() function. See Add
sparklines to search results for information on implementing sparklines.

Caution: The sparkline options listed in this reference do not render when generating a PDF of a dashboard. Only the
sparkline itself renders.

Parent elements

<table>

<table>
<format type="sparkline" field=["field name]"> (0..n)
<option name="[property name]"> (0..n)

Common options

Property Type Default Description

chartRangeMax Number n/a Specify an alternate maximum sparkline range value.

chartRangeMin Number n/a Specify an alternate minimum sparkline range value.

height CSS style auto Height of the chart. Specify any valid CSS width (for example, 1.5em, 20px).

tooltipPrefix text Text to place before each field displayed in a tooltip.

223
 Property Type Default Description
tooltipSuffix text Text to append to each field displayed in a tooltip.

type (bar | discrete | line) line Specifies the type of sparkline

Options for bar charts

Property Type Default Description

barSpacing Number Space between each bar, in pixels.

barWidth Number Width of each bar, in pixels.

colorMap See description Range map to map specific values to selected colors.
For example if you want all values of -2 to appear yellow, use colorMap: { '-2': '#ff0' }.

You can pass an array of values here instead of a mapping to specifiy a color for each individual bar. For example if your
chart has three values 1,3,1 you can set colorMap=["red", "green", "blue"].

Options for discrete charts

Property Type Default Description

Used by line and discrete charts to specify the color of the line drawn as a CSS values
lineColor CSS style
string

lineHeight Number 30% of graph height Height of each line, in pixels.

thresholdColor CSS color CSS color to use in combination with thresholdValue.

thresholdValue CSS color Draw values less than this using thresholdColor instead of lineColor
Options for line charts

Property Type Default Description

CSS color |
fillColor Specify the color to fill the area under the graph as a CSS value. Set to false to disable fill.
false

CSS color for the vertical line that appears through a value when moused over.
highlightLineColor CSS color #f22
Set to null to disable.
Color for the spot that appears on a value when moused over.
highlightSpotColor CSS color #f5f
Set to null to disable.
Used by line and discrete charts to specify the color of the line drawn as a CSS values
lineColor CSS style
string

lineWidth Number 1 line width, In pixels.

CSS color of the marker displayed for the maximum value.

maxSpotColor CSS color
Set to false or an empty string to hide it.
CSS color of the marker displayed for the minimum value.
minSpotColor CSS color
Set to false or an empty string to hide it.

224
 Property Type Default Description
With normalRangeMin, threshold values between which to draw a bar to denote the
"normal" or expected range of values.
range (see
normalRangeMax
description) For example the green (normal) bar in this range
80,85,84,88,98,114,116,104,95,85,84 might denote a normal operating
temperature range.
With normalRangeMax, threshold values between which to draw a bar to denote the
"normal" or expected range of values.
range (see
normalRangeMin
description) For example the green (normal) bar in this range
80,85,84,88,98,114,116,104,95,85,84 might denote a normal operating
temperature range.
CSS color of the final value marker.
spotColor CSS color
Set to false or an empty string to hide it.
spotRadius Number 1.5 Radius, in pixels, of all spot markers.

Points on which to draw spots, and with which color. Accepts a range.
range (see
valueSpots
description) For example, to render green spots on all values less than 50 and red on
values higher use {':49': 'green, '50:': 'red'}
Width of the chart. Specify any valid CSS width (for example, 1.5em, 20px). This option
width CSS style auto
does apply to bar and tristate type sparklines.
Example

Sparkline of type bar with a color map:

<dashboard>
<label>Sparkline Example</label>
<row>
<panel>
<table>
<title>Basic Sparkline Bar w/ Color Map</title>
<!-- Set span for each sparkline datapoint to be 1 hour -->
<search>
<query>
index=_internal | chart count sparkline(count, 1h) as trend by sourcetype | sort -count
</query>
<earliest>-24h@h</earliest>
<latest>now</latest>
</search>
<option name="count">3</option>

<!-- Set sparkline options here; make sure that field matches field name of the search results -->

<format type="sparkline" field="trend">

<option name="type">bar</option>
<option name="height">40</option>
<!-- Use colorMap to map specific values to selected colors -->
<option name="colorMap">
<option name="2000:">#5379AF</option>
<option name=":1999">#9ac23c</option>
</option>

225
 <option name="barWidth">5px</option>
</format>
</table>
</panel>
</row>
</dashboard>

fields

Comma-separated list of fields. Use the <fields> element to restrict searches to these fields.

Fields determine the columns in a table. Field names and values appear with each event in a list. The order of the fields in
the comma-separated list determines the order of the columns in the table or event listing.

Parent elements

<event> <table>

<event> | <table>
<fields> (0..1)

Example

Restrict the results of the search to the following fields: _time, splunkd, splunk_web_access, splunk_web_service

<dashboard>
<label>Fields Example</label>
<row>
<panel>
<table>
<search>
<query>
index=_internal | timechart count by sourcetype
</query>
<earliest>-7d@d</earliest>
<latest>now</latest>
</search>
<fields>_time, splunkd, splunk_web_access, splunk_web_service</fields>
<option name="rowNumbers">0</option>
</table>

226
 </panel>
</row>
</dashboard>

option

The <option> tag applies a specific property to an element, such as a panel element. Use the name attribute to specify the
property.

Typically, named options apply to a specific panel. However some options can be applied to more than one panel.

Attributes

Name Type Default Description

Specifies the name of the specific property.
Property name
name
(Required) The allowed values for <option> depends on the named property. Refer to the
reference entry for each panel to see a list of named options and the allowed values.
Parent elements

<chart> <event> <single> <table>

<chart> | <event> | <html> | <single> | <table>

. . .
<option name="[property]">[option value]</option> (0..n)

Example

<table>
<title>Top sourcetypes in the last 24 hours</title>
<search>
index=_internal group=per_sourcetype_thruput | chart sum(kb) by series | sort -sum(kb)
</search>
<earliestTime>-1d</earliestTime>
<latestTime>now</latestTime>
<option name="count">5</option>
<option name="rowNumbers">0</option>

227
</table>
search element

Use the search element to create searches for <dashboard>, <form>, and panel visualization elements. You also use the
search element to populate choices for form inputs.

search

Defines a search for a dashboard, form, or panel. For form inputs, defines dynamic choices for the inputs.

• Inline search: A search specified in a visualization. Use the <query> element to specify an inline search.
• Reports: A search referenced from a report. Use the ref attribute to reference a report. The panel contains a
visualization that is based on both the search and visualization from the referenced report. You cannot modify the
search but you can change and configure the visualization for the search results. If the search in the report
changes, the panel based on that report updates to include the changes.
• Populating search for input: A search that populates choice for a form input. Use search as a child element of a
form input to populate choices for checkbox, dropdown, multiselect, and radio inputs. The populating search uses
the form input child elements, <fieldForLabel> and <fieldForValue>, to populate the choices. Do not use
real-time searches for populating searches. The input choices do not update correctly when using a real-time
search.
• Global searches: A search from the <dashboard> or <form> context is a global search. Use a global search as the
base search for post-process searches. A global search should always have an id attribute that a post-process
search can reference.
• Post-process searches: A search that further modifies results from a base search. Use the base and id
attributes to implement post-process searches. A post-process search uses the base attribute to reference the id
attribute of the base search. The base search can be a global search or a search at the panel level. Specify
<earliest> and <latest> elements with the base search. The post-process search ignores <earliest> and
<latest> elements that are child elements to the post-process search.

Caution: Passing a large number of search results from a base search can cause a server time out. In this
scenario, consider reducing the following.

◊ The number of results and fields returned from the base search.
◊ The complexity of the post-process operations on these results.

For more information on post-process searches, see Post-process searches in this manual.

Attributes

Name Type Default Description

The name of an app.

app text
Use the app attribute with the ref attribute to reference a report that is not in the
current app.
A reference to a base search by a post-process search.

base text
Reference a base search in the current dashboard by the id attribute of the
search.
id Text (minimum two Identifier for a search. A post-process search references a base search by this identifier.
characters)

228
Name Type Default Description
Only alphanumeric and underscore characters are valid. Cannot begin with a
number or the underscore character.

The following terms are reserved for internal use and cannot be used for an id:

• dashboard
• default
• footer
• header
• search
• submitted
• url

Reference to a report containing a search.

ref text
If you are referencing a report in another app, use the app attribute to specify the
app.
Parent elements

<form> <dashboard> <panel> <chart> <event> <map> <single> <table>

Child elements

Element Type Default Description

For saved searches,
use one of the • true: Always use the results from a preexisting saved search job when
following values. possible.
• false: Never use results from preexisting saved search jobs.
<cache> scheduled
• true • scheduled: Reuse any previously run scheduled saved search jobs.
• false • [integer]: The number of seconds indicating the maximum saved
• scheduled search job results age. Only results that are newer than this number of
• [integer] seconds are used.

<cancelled> N/A N/A Execute actions when a search is cancelled.

Execute actions based on finished search events. Includes job properties and first
<done> N/A N/A
result row.

<error> N/A N/A Execute actions when there is a search error event, such as an invalid query.

Optional time expressions that specify the earliest and latest time parameters for a
search.

Post-process searches ignore child <earliest> and <latest> elements. Instead,

the <earliest> and <latest> elements from the base search are used.

<earliest> and You can specify the time as relative time or absolute time. For relative time, use
text
<latest> relative time modifiers, as described in Specify relative time ranges in your search in
the Search Manual. For absolute time, specify the time in UNIX epoch time format.

Note: UNIX epoch time format for absolute time in Simple XML is
different from the SPL absolute time format used in queries.
Execute an action on search progress events. Access job properties and the first
<progress>
results row.

229
 Element Type Default Description
<query> text Search string for the query.

Indicate a delay or interval time for inline or saved searches. This setting does not
apply to post-process searches, which refresh automatically when their base search
refreshes.

Integers are handled as seconds. Use SPL syntax for relative time expressions. For
Integer or relative time example, 1h5m or 5m.
<refresh> No refresh
expression
Use the <refreshType> setting to specify refresh behavior in relation to search
completion or dispatch.

You can use the <refresh.display> setting in a visualization to specify a refresh

progress indicator.

Indicate the starting time for counting down to a refresh. Use delay to start counting
when the search is done.
<refreshType> interval or delay delay
Use interval to count down when the search is dispatched. If the runtime of the
search is longer than the configured time, the search job is cancelled and a new job
is dispatched.

Event sampling ratio. To learn more, see Event sampling with reports and
<sampleRatio> number
dashboard panels in the Search Manual.
Base search from inline search

<search id=[base ID]>

<query>[search string]</query> (1)
<earliest> (0..1)
<latest> (0..1)

Base search from report

<search id=[base ID] [ref=[report name]]>

<earliest> (0..1)
<latest> (0..1)

Post-process search

<search base=[base ID]> (0..n)

<query>[post-process search string]</query> (1)

Examples

• Dashboard with base search and two post-process searches.*

<dashboard>
<label>Dashboard with post-process search</label>
<description></description>
<!-- Example uses stats transforming command -->
<!-- This limits events passed to post-process search -->
<search id="baseSearch">
<query>
index=_internal source=*splunkd.log | stats count by component, log_level

230
 </query>
<earliest>-30d</earliest>
<latest>now</latest>
</search>
<row>
<panel>
<chart>
<title>Event count by log level</title>
<!-- post-process search -->
<search base="baseSearch">
<query>
stats sum(count) AS count by log_level
</query>
</search>
</chart>
</panel>
<panel>
<chart>
<title>Error count by component</title>
<!-- post-process search -->
<search base="baseSearch">
<query>
search log_level=error | stats sum(count) AS count by component
</query>
</search>
<option name="charting.chart">bar</option>
</chart>
</panel>
</row>
</dashboard>

• Dashboard with empty post-process search.*

<dashboard>
<label>Dashboard with empty post-process search</label>
<description></description>
<!-- Example uses stats transforming command -->
<!-- This limits events passed to post-process search -->
<search id="baseSearch">
<query>index=_internal source=*splunkd.log | stats count by component, log_level</query>
<earliest>-30d</earliest>
<latest>now</latest>
</search>
<row>
<panel>
<chart>
<title>Count by component, log level (from post-process search)</title>

231
 <!-- post-process search -->
<search base="baseSearch">
<query>stats sum(count) AS count by log_level</query>
</search>
<option name="charting.axisY.scale">log</option>
</chart>
</panel>
<panel>
<chart>
<title>Count by component (from base search)</title>
<!-- empty post-process search -->
<search base="baseSearch" />
<option name="charting.chart">bar</option>
</chart>
</panel>
</row>
</dashboard>

Drilldown elements

drilldown

Define custom destinations to link to when a user clicks on fields in a dashboard or form.

• Specify a path to the destination using the <link> tag.

• Set or unset tokens using the <set> or <unset> tags.
• Specify a condition for setting or unsetting tokens.

Note: You can specify one or more actions (<link>, <set>, <unset>) or conditions (<condition>) directly within
<drilldown>, but you cannot specify both actions and conditions.

For details see Dynamic drilldown in dashboards and forms.

Attributes

Name Type Default Description

target text — Corresponds to the target attribute of the <a> HTTP tag.

Specify "_blank" to open the drilldown in a new window.

Specify "_self" to open the drilldown in the same window.

232
 Name Type Default Description
Specify an arbitrary string to open the drilldown in a new window. Subsequent references to this
target open in this window.
Parent elements

<chart> <event> <map> <single> <table>

<drilldown>
( <link> | <set> | <unset> ) (1..n) | <condition> (1..n)

Example 1: Pass a value to a form

<table>
<search>index=_internal</search>

<!-- Pass the clicked row's 'count'-column value -->

<!-- to populate a destination form's 'foo' token. -->
<drilldown>
<link>
/app/search/simple_xml_form?form.foo=$row.count$
</link>
</drilldown>
</table>
Example 2: Pass parameters to a form

<table>
<search>index=_internal</search>

<!-- Pass the clicked cell's value, earliest time, -->

<!-- and latest time to a destination form's -->
<!-- token ('foo') and search parameters -->
<drilldown>
<link>
<![CDATA[
/app/search/simple_xml_form?form.foo=$click.value2$&earliest=$earliest$&latest=$latest$
]]>
</link>
</drilldown>
</table>
Example 3: Pass a value from a chart to a website

<chart>
<search>
index=_internal | chart count by sourcetype
</search>
<option name="charting.chart">column</option>

<!-- $click.value$ captures the value clicked by the user -->

<!-- From the x-axis of a column chart and passes -->
<!-- it to the website as a query parameter -->
<drilldown>
<link>
http://splunk-base.splunk.com/integrated_search/?q=$click.value$
</link>
</drilldown>

233
</chart>
condition (drilldown)

Limits the scope of drilldown actions to clicks on specific fields. If the <condition> element is not present, then drilldown
actions apply to all fields.

Note: The <condition> element applies to both input elements and drilldown elements. See <condition> (input) for
details.

Parent element

<drilldown>

<condition>
(<link> | <set> | <unset>) (1..n)

Attributes

Name Type Default Description

field text * Specifies the search field on which to implement the drilldown, or to set or unset a token.

Input context only. Specifies the input <label> element to which the condition applies.
label text *
'*' applies the condition to all input <label> elements. See <condition> (input).
Input context only. Specifies the input <value> element to which the condition applies.
value text *
'*' applies the condition to all input <value> elements. See <condition> (input).
Example

See the example for <set> for using the <condition> tag to set a token for in-page drilldown.

See the example for <unset> for using multiple <condition> tags.

selection

Sets the time window for the pan and zoom feature of charts. You can also use tokens to set other values, such as the
numerical values of the x-axis in a chart.

Only applies to charts of type area, column, or line.

See Chart controls for details on the pan and zoom feature of charts.

Parent elements

<chart>
<option name="charting.chart">area</option>
| <option name="charting.chart">column</option>
| <option name="charting.chart">line</option>

234
Use pre-defined tokens to capture the earliest and latest time of the time window and the earliest and latest values within
that time window for a field.

For example:

<selection>
<set token="selection.earliest">$start$</set>
<set token="selection.latest">$end$</set>
<set token="start.[fieldname]">$start.[fieldname]$</set>
<set token="end.[fieldname]">$end.[fieldname]$</set>
</selection>

Can also be used to set a drilldown link.

<selection>
<link>

Attributes

No attributes for this element.

Example

A selection on the left chart zooms into the right chart with details for the selected area.

<dashboard>
<label>Pan and Zoom</label>
<row>
<panel>
<chart>
<title>Pan and Zoom (All source types)</title>
<search>
<query>
index=_internal | timechart count by sourcetype
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<option name="charting.axisX.scale">linear</option>
<option name="charting.axisY.scale">log</option>
<option name="charting.chart">line</option>
<selection>
<set token="selection.earliest">$start$</set>
<set token="selection.latest">$end$</set>
<set token="start.splunk_web_access">$start.splunk_web_access$</set>
<set token="end.splunk_web_access">$end.splunk_web_access$</set>
</selection>
<option name="charting.axisTitleX.text">Last 7 Days</option>
</chart>
</panel>
<panel>
<chart>
<title>Pan and Zoom (Web access source type)</title>
<search>
<query>
index=_internal sourcetype=splunk_web_access

235
 | timechart count by sourcetype
</query>
<earliest>$selection.earliest$</earliest>
<latest>$selection.latest$</latest>
</search>
<option name="charting.chart">column</option>
<option name="charting.legend.placement">none</option>
<option name="charting.legend.masterLegend">null</option>
<option name="charting.axisX.scale">linear</option>
<option name="charting.axisY.scale">log</option>
<option name="charting.axisTitleX.text">Selected Time Range</option>
</chart>
</panel>
</row>
<row>
<panel>
<html>
<h3>Token values for the splunk_web_access selection</h3>
<table border="0" cellpadding="12" cellspacing="0">
<tr>
<td>
<p><b>Time range (epoch time)</b></p>
<p>
<b>$$selection.earliest$$</b>: $selection.earliest$<br/>
<b>$$selection.latest$$</b>: $selection.latest$
</p>
</td>
<td>
<p><b>Count at the begining and end of time range.</b></p>
<p>
<b>$$start.splunk_web_access$$</b>: $start.splunk_web_access$<br/>
<b>$$end.splunk_web_access$$</b>: $end.splunk_web_access$</p>
</td>
</tr>
</table>
</html>
</panel>
</row>
</dashboard>

236
Drilldown event tokens

For dynamic drilldown, these are the event tokens, and their values, that are available for each type of visualization.

• Chart event tokens

• Event event tokens
• Map event tokens
• Single event tokens
• Table event tokens

chart (event tokens)

The clicked field name is the name of the field or series for the y-Axis if present (similar to click.name2). If the name of the
field or series is not available the field or category for the x-axis is used (click.name).

Data Property Description

click.name Name of the field or category for the x-axis. Not available when the legend has been clicked.

click.value Value of the field or category for the x-axis. Not available when the legend has been clicked.

click.name2 Name of the field or series for the y-axis.

click.value2 Value of the field or series for the y-axis. Not available when the legend has been clicked.

Any field values along the y-axis at the same point as the click on the x-axis. Not available when the legend has been
row.<fieldname>
clicked.

row.<x-axis-name> Value of the x-axis. Not available when the legend has been clicked.

earliest/latest Time range of the clicked chart segment, or if not applicable, the time range of the search.

event (event tokens)

The value for click.name depends on the context of the click, as described below:

Data Property Description

The field name associated with the click.

For cases in the event viewer where the field name is ambiguous:
click.name • Click a term in the raw event: Sets _raw as the field name.
• Click the event timestamp: Sets _time as the field name.
• Click a tag: Sets a field name according to the tag name, as follows:
tag::<field>
(for example, when host is tagged, tag::host)

click.value Value associated with the click.

click.name2 Identical to click.name.

click.value2 Identical to click.value.

row.<fieldname> Exposes each field value as row.<fieldname>.

earliest/latest Time range of the clicked event, which is:

237
 Data Property Description
earliest: _time
latest: (_time + 1 second)

map (event tokens)

The field for the <condition> tag in dynamic drilldown always corresponds to click.name.

Data Property Description

click.name Name of the first, or only field, that displays the marker.

click.value Value of the first, or only field, that displays the marker.

click.name2 Same as click.name.

click.value2 Same as click.value

click.lat.name For cluster maps: latitude field name for the clicked location.

click.lat.value For cluster maps: latitude field value for the clicked location.

click.lon.name For cluster maps: longitude field name for the clicked location.

click.lon.value For cluster maps: longitude field value for the clicked location.

For cluster maps: south, west, north, or east outer boundary for the clicked location. For example, use
click.bounds.<orientation>
$click.bounds.east$ to get the eastern outer boundary.

row.<fieldname> Each field value of the clicked marker is exposed in this form.

earliest/latest Time range of the search driving the map visualization.

single (event tokens)

The field for the <condition> tag in dynamic drilldown always corresponds to click.name.

Data Property Description

click.name Name of the field that is displayed by the single value visualization.

click.value Value that is displayed by the single value visualization.

click.name2 Same as click.name.

click.value2 Same as click.value.

row.<fieldname> Exposes each field in the same result row from which the single value is taken.

earliest/latest Time range of the search driving the single value visualization.
table (event tokens)

The field for the <condition> tag in dynamic drilldown always corresponds to click.name2.

Data Property Description

click.name Name of the leftmost field that is displayed in the table. This is always _time, if present.

238
 Data Property Description

click.value Value of the left-most column in the clicked row.

click.name2 Name of the clicked column.

click.value2 Value of the clicked column.

row.<fieldname> All field values for the clicked table row, including those fields that are not displayed.

earliest/latest Time range of the clicked table row, or if not applicable, the time range of the search.

Eval, Link, Set, and Unset

Set or update token values to create dynamic content or behavior changes. See also Token usage in dashboards to learn
about using the <init> element to set tokens on page load.

eval

Add custom logic to a dashboard. See Custom logic for dashboard eval expressions for more information.

Parent elements

<drilldown><condition> <search><condition> <change><condition>

<drilldown>
<eval token="[token_name]">

<drilldown>
<condition>
<eval token="[token_name]">

<change>
<eval token="[token_name]">

<change>
<condition>
<eval token="[token_name]">

<search>
<condition>
<eval token="[token_name]">

<search>
<eval token="[token_name]">

Attributes

Name Type Default Description

Token whose value is the result of the <eval> expression. In an <eval> expression, you can use either $...$
delimiters or single quote delimiters for tokens. For example, both of the following options are valid.
token text None
$my_token$
'my_token'
Example This example uses <eval> to compute and display job duration in the dashboard.

239
<dashboard stylesheet="eval_tokens.css">
<label>Eval Tokens</label>
<row>
<panel>
<title></title>
<search id="search_logic">
<query>index=_internal | top sourcetype</query>
<earliest>0</earliest>
<latest>now</latest>
<progress>
<eval token="duration">tostring(tonumber($job.runDuration$),"duration")</eval>
</progress>
</search>
<chart>
<title>Top sourcetypes for index=_internal</title>
<search base="search_logic" />
<option name="charting.chart">bar</option>
</chart>
<html>
<h3>Duration</h3>
<div class="custom-result-value">$duration$</div>
</html>
</panel>
</row>
</dashboard>

link

Specifies a link to a destination for drilldown or for a selected input choice.

<link> can be a child tag of <change>, <drilldown>, search, or <condition>.

Use <link> as a child tag of <condition> when you want to configure distinct drilldown actions for specific fields or inputs.
Otherwise, use <link> as a child tag of <change> or <drilldown>.

There are various ways to specify a destination for the drilldown using relative paths or a URL, as described below.

Parent elements

<drilldown><condition> <search><condition> <change><condition>

240
<drilldown>
<link>

<drilldown>
<condition>
<link>

<change>
<link>

<change>
<condition>
<link>

<search>
<condition>
<link>

<search>
<link>

Attributes

Name Type Default Description

Deprecated. Use <condition field="[field]"...>

(<drilldown> only) Specifies which values to capture in a table from the specified column or
Field
field row. Cannot be specified together with the series attribute.
name

Although the field attribute is supported, Splunk recommends that you specify fields with the
<condition> tag.
Deprecated. Use <condition field="[field]"...>

(<drilldown> only) Specifies which values to capture in a chart from the specified series.
Series
series Cannot be specified together with the field attribute.
name

Although the series attribute is supported, Splunk recommends that you specify series with
the <condition> tag.
Corresponds to the target attribute of the <a> HTTP tag. Specifying target for the <link> element overrides
the value of target specified in the <drilldown> element.

Specify "_blank" to open the drilldown in a new window.

target text —
Specify "_self" to open the drilldown in the same window.

Specify an arbitrary string to open the drilldown in a new window. Subsequent references to
this target open in this window.
Parent element

<drilldown><condition>

1) <link> [viewname] </link>

241
2) <link> [path/viewname] </link>
3) <link> [path/viewname?form.token=$dest_value$] </link>
4) <link> [path/viewname?form.token=$dest_value$&earliest=$earliest$&latest=$latest$] </link>
5) <link> [URL?q=$dest_value$] </link>

1. Use the specified view, which must be in the same path as the current dashboard.
2. Relative path to connect to a dashboard.
3. Relative path to connect to a form, passing in a token to populate the form.
4. Pass in the earliest and latest time range from the original search.
(Requires use of CDATA to escape special characters.)
5. URL and query argument to pass a value to the destination page.

Path values Description

A path to the destination view from the current view. Typically, you specify path as: /app/app_name/

path
However, you can also specify a relative path, based on the app context of the source and destination
views.
viewname The name of the Splunk view you are using for a destination.

$dest_value$ Specifies how to capture a value from a visualization. See Drilldown event tokens for details on each visualizaion.

URL Specify a URL to a web page. Use the full address, including the protocol. For example: http://.

q When specifying a URL, use q to specify the value of dest_value in a query string to a web resource.
Example

Use <link> with conditional inputs to open a new page.

<form>
. . .
<fieldset>
<input type="dropdown" token="openNewPageToken">
<label></label>
<default>Select a page to open</default>
<choice value="">Select a page to open</choice>
<choice value="manager_page">View prebuilt panels</choice>
<choice value="splk_page">Open Splunk home page</choice>
<change>
<condition value="manager_page">
<link target="_blank">
/manager/search/data/ui/panels?ns=-&pwnr=-&search=&count=25
</link>
</condition>
<condition value="splk_page">
<link target="_blank">
http://splunk.com
</link>
</condition>
</change>
</input>
</fieldset>
. . .
</form>

242
set

Allows you to publish new global tokens that can be consumed by any other element or search within the dashboard. You
typically publish tokens when using form inputs or when using drilldown.

For form inputs, specify tokens for actions to take for specific inputs.

For drilldown, specify the value to capture when clicked. The value can be set dynamically using a token.

For form inputs, <set> can be a child tag of <change> or <condition>. For drilldown, <set> can be a child tag of
<drilldown> or <condition>.

Use <set> as a child tag of <condition> when you want to configure distinct actions for specific inputs or for fields for
drilldown. Otherwise, use <set> as a child tag of <change> or <drilldown> to specify an action for all inputs or for all fields.

Parent elements

<change> <drilldown> <condition>

There are two ways to set a value of a token.

1. Use a template to combine input tokens and static portions to form the new token value. Templates let you reference
multiple tokens when setting the value, and also specify quotes for the value using the |s token filter.

<set token="Token Name">sourcetype=$click.value|s$</set>

2. Use the prefix and suffix attributes to specify static portions for the input token. The following is equivalent to the
template example above.

<set token="Token Name" prefix="sourcetype=&quot;" suffix="&quot;">$click.value$</set>

Attributes

Name Type Default Description

token Token name Required The name of the token to be consumed by the target visualization on the same page.

243
 Name Type Default Description
prefix text String to place before the value of the token.

suffix text String to append to the value of the token.

Example

A click on the table sets a token which is consumed by the search of the chart visualization.

<dashboard>
<label>In-page Drilldown</label>
<row>
<panel>
<table>
<title>Set sourcetype token on click</title>
<search>
<query>
index=_internal | stats count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
<drilldown>
<condition field="sourcetype">
<set token="sourcetype">$click.value2$</set>
</condition>
</drilldown>
</table>
<chart>
<title>Chart for $sourcetype$</title>
<search>
<query>
index=_internal sourcetype=$sourcetype$ | timechart count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
</chart>
</panel>
</row>
</dashboard>
unset

Use <unset> to remove a token that was previously set.

Parent element

<change> <condition>

<drilldown> <condition>

<change>

<drilldown>

<unset token="Token Name">

244
Attributes

Name Type Default Description

token Token name Required The name of a token that was previously set, but to be ignored.
Example

Use <set> and <unset> to define the visualization to use.

Use token definitions to hide a panel.

<dashboard>
<label>Example for <set> and <unset></label>
<row>
<panel>
<table>
<title>Set sourcetype token</title>
<search>
<query>
index=_internal | stats count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
<drilldown>
<!-- For the sourcetype field clicked: -->
<!-- Set token to display a chart -->
<!-- Unset token to display a table -->
<condition field="sourcetype">
<set token="sourcetype">$row.sourcetype$</set>
<set token="showChart">foo</set>
<unset token="showTable"></unset>
</condition>
<!-- For any other field clicked: -->
<!-- Set token to display a table -->
<!-- Unset token to display a chart -->
<condition field="*">
<set token="sourcetype">$row.sourcetype$</set>
<set token="showTable">foo</set>
<unset token="showChart"></unset>
</condition>
</drilldown>
</table>
</panel>

<!-- Hide the html panel when either token is present -->
<!-- Click in the original table to set either token -->
<panel>
<html rejects="$showTable$, $showChart$">
<h2>Details</h2>
<div style="padding: 50px; margin: 0 auto; width: 350px;">
<div class="alert alert-warning">
<i class="icon-alert"/>
Click on a row in the table on the left to show details.
</div>
</div>
</html>
<!-- if showChart token is set, display results here -->
<chart depends="$showChart$">

245
 <title>Details for $submitted:sourcetype|s$</title>
<search>
<query>
index=_internal sourcetype=$sourcetype|s$
| timechart count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
</chart>
<!-- if showCTable token is set, display results here -->
<table depends="$showTable$">
<title>Details for $submitted:sourcetype|s$</title>
<search>
<query>
index=_internal sourcetype=$sourcetype|s$
| timechart bins=10 count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
<option name="wrap">true</option>
<option name="rowNumbers">false</option>
<option name="dataOverlayMode">none</option>
<option name="drilldown">cell</option>
<option name="count">10</option>
</table>
</panel>
</row>
</dashboard>
Deprecations and removals

Check the Deprecated features list in the Release Notes for information on deprecated or removed elements.

Chart configuration reference

Chart overview

The <chart> element is a panel visualization that is highly configurable.

<chart>
A panel that displays search data in a chart. Saved reports contain chart formatting parameters. Saved searches do not.
For more information, see "Save reports and share them with others."

When you load a saved report in the chart panel, your saved report format is also loaded. However, chart formatting can
be overridden inline using the chart options.

Charts use named options to specify chart-specific properties. This reference contains sections on all configurable
properties of charts.
Parent elements

<row>
<panel>

246
 <chart>

<chart>
<title> (0..1)
<search> (0..1)
<earliest> (0..1)
<latest> (0..1)
<drilldown> (0..n)
<selection> (0..n, for charts of type area, line, and column only)
<option name="[property]"> (0..n)

General chart properties

These are properties that apply to all charts.

Property Type Default Description

charting.backgroundColor Hex color value. Chart background color.

(area | bar | bubble |

column | fillerGauge
charting.chart column Set the chart type.
| line | markerGauge | pie
| radialGauge | scatter)

The number of results to retrieve. Set to 0 to get all

results.
charting.data.count Number 10000
Caution: Setting to 0 to retrieve all results
can have a significant performance impact.
The order in which to apply the fieldShowList and
charting.data.fieldListMode (show_hide | hide_show) hide_show
fieldHideList filters.

charting.data.fieldShowList array of fields — The list of fields to explicitly show in the results.

charting.data.fieldHideList array of fields — The list of fields to explicitly hide from the results.

all: Drilldown is enabled.

charting.drilldown (all | none) all
none: Drilldown is disabled.
charting.fieldColors Map of hex colors. — The map of hexadecimal color values to use for
each field.
See description.
A map is a comma-delimited list of
key/value pairs, enclosed in curly braces.

Keys are separated from their values by a

colon.

Example:

{"foo\: bar": 0xffff00, foo: 0xff0000,

"foobar": 0x000000}

Escape the following special characters in a

key or string value with double quotes:

247
 Property Type Default Description
[]{}(),:"

Escape existing double quotes or

backslashes or colons with a preceding
backslash.

See Specify custom colors for fields in

charts for an example.
charting.fontColor Hex color value. Chart font color.

charting.foregroundColor Hex color value. Chart foreground color.

charting.legend.labels CSV of labels — A list of labels with which to pre-populate the legend.

Determines how to display labels that overflow

layout bounds by replacing elided text with an
ellipsis (...).

ellipsisStart: Elides text at the start.

(ellipsisEnd | ellipsisMiddle ellipsisMiddle: Elides text in the middle of

charting.legend.labelStyle.overflowMode ellipsisMiddle the line.
| ellipsisNone | ellipsisStart)

ellipsisEnd: Elides text at the layout

boundary.

ellipsisNone: Disables text truncation

entirely.
If attribute is present, disables legend color
synchronization with other panels in the dashboard.

charting.legend.masterLegend n/a
Note: The only valid value is an empty tag.
If a value is specified, the attribute is
ignored.
Use an array of hexadecimal values to define the
colors of chart series.

charting.seriesColors List of hex colors See below*

Note: To apply static colors to specific
fields use the charting.fieldColors
property.
Height, in pixels, of the chart.

height Number —
Default value is 250, must be between 100
and 10000.
*Default value for charting.seriesColors:

[0x1e93c6, 0xf2b827, 0xd6563c, 0x6a5c9e, 0x31a35f, 0xed8440, 0x3863a0, 0xa2cc3e, 0xcc5068,

0x73427f, 0x11a88b, 0xea9600, 0x0e776d, 0xffb380, 0xaa3977, 0x91af27, 0x4453aa, 0x99712b, 0x553577,
0x97bc71, 0xd35c2d, 0x314d5b, 0x99962b, 0x844539, 0x00b290, 0xe2c188, 0xa34a41, 0x44416d, 0xe29847,
0x8c8910, 0x0b416d, 0x774772, 0x3d9988, 0xbdbd5e, 0x5f7396, 0x844539]

248
General Chart Properties: selected examples

<dashboard>
<label>Selected chart examples</label>
<row>
<panel>
<chart>
<title>A line chart</title>
<search>
<query>
index=_internal source="*metrics.log"
group=per_sourcetype_thruput
| timechart sum(kb) by series
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
<option name="charting.chart">line</option>
</chart>
</panel>

<panel>
<chart>
<title>Show only splunkd_access and splunkd fields</title>
<search>
<query>
index=_internal source="*metrics.log"
group=per_sourcetype_thruput
| timechart sum(kb) by series
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
<option name="charting.data.fieldShowList">
["splunkd_access", "splunkd"]
</option>
<option name="charting.chart">line</option>
</chart>
</panel>
</row>

<row>
<panel>
<chart>
<title>Show all fields except splunk_web_service, splunkd_access, and splunkd</title>
<search>
<query>
index=_internal source="*metrics.log"
group=per_sourcetype_thruput
| timechart sum(kb) by series
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
<option name="charting.data.fieldHideList">
["splunk_web_service", "splunkd_access", "splunkd"]
</option>
<option name="charting.chart">line</option>
</chart>

249
 </panel>

<panel>
<html>
Use the <tt>eval</tt> function in the search to transpose
the value of the <tt>log_level</tt> field into individual
fields for <tt>charting.fieldcolors</tt>.
</html>
<chart>
<title>Field colors example</title>
<search>
<query>
index = _internal log_level=* | stats
count(eval(log_level="ERROR")) as ERROR
count(eval(log_level="WARN")) as WARN
count(eval(log_level="INFO")) as INFO
by sourcetype
</query>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<option name="charting.axisY.scale">log</option>
<option name="charting.chart">column</option>
<option name="charting.fieldColors">
{"ERROR": 0xFF0000, "WARN": 0xFF9900, "INFO":0x0066FF, "NULL":0xC4C4C0}
</option>
<option name="charting.legend.placement">right</option>
</chart>
</panel>
</row>
</dashboard>

250
Area, Bubble, Bar, Column, Line, and Scatter charts

Properties specific to line, area, column, scatter, bubble, and bar charts, all of which contain an x-axis and y-axis.

Property Type Default Description

Indicates whether or not the axis line is visible.
charting.axisLabelsX.axisVisibility Depends on
(show | hide) For numeric axes, defaults to hide. For all
charting.axisLabelsY.axisVisibility axis type
other axes, defaults to show.

Applies only to Area, Bar, Column, and Line

Depends on charts. Indicates whether or not the axis line is
charting.axisLabelsY2.axisVisibility (show | hide)
axis type visible. For numeric axes, defaults to hide. For
all other axes, defaults to show.

Indicates whether the range of the axis should

charting.axisLabelsX.extendsAxisRange
Boolean true be extended to snap to whole major tick
charting.axisLabelsY.extendsAxisRange
marks.

charting.axisLabelsX.integerUnits
Indicates whether the major unit is rounded to
charting.axisLabelsY.integerUnits Boolean false
the nearest integer.
charting.axisLabelsY2.integerUnits

(ellipsisMiddle | Indicates whether the axis label is ellipsized to

charting.axisLabelsX.majorLabelStyle.overflowMode ellipsisNone
ellipsisNone) the tick spacing.

Axis label rotation, in degrees.

(-90 | -45 | 0 | 45 | 90
charting.axisLabelsX.majorLabelStyle.rotation 0 Positive values rotate clockwise.
)
Negative values rotate
counterclockwise
charting.axisLabelsX.majorLabelVisibility (auto | show | hide) auto *Note:
charting.axisLabelsY.majorLabelVisibility charting.axisLabelsY.majorLabelVisibility
charting.axisLabelsY2.majorLabelVisibility is deprecated.
Controls the visibility of major tick mark labels.

Set to show to always show labels,

even when a large number of results
are displayed.

251
 Property Type Default Description
auto: Shows or hides individual major
labels to maintain readability in the
available space without overlapping

show: Show all major labels, even if

overlapping occurs.

hide: Hide all major labels.

Note: charting.axisLabelsY.majorTickSize is
charting.axisLabelsX.majorTickSize
number 6 deprecated'.
charting.axisLabelsY.majorTickSize
The size, in pixels of the major tick marks.

charting.axisLabelsX.minorTickSize
charting.axisLabelsY.minorTickSize Number 6 The size, in pixels of the minor tick marks.
charting.axisLabelsY2.minorTickSize

Indicates whether major tick marks are visible.

auto: For numerical axes, ticks are

hidden by default. Otherwise, shows a
major tick only if the corresponding
charting.axisLabelsX.majorTickVisibility
(auto | show | hide) auto label is visible.
charting.axisLabelsY.majorTickVisibility

show: Force all major ticks to be

visible, regardless of label visibility

hide:Hide all major ticks.

Applies only to Area, Bar, Column, and Line
charts. Indicates whether major tick marks are
visible.

auto: For numerical axes, ticks are

hidden by default. Otherwise, shows a
depends on major tick only if the corresponding
charting.axisLabelsY2.majorTickVisibility (auto | show | hide)
axis type
label is visible.

show: Force all major ticks to be

visible, regardless of label visibility

hide:Hide all major ticks.

The spacing unit at which to place major tick
marks along the numeric axis.
charting.axisLabelsX.majorUnit
(Positive integer |
charting.axisLabelsY.majorUnit auto
auto) By default, this value is automatically
charting.axisLabelsY2.majorUnit
calculated based on the scale of the
related axis.
charting.axisLabelsX.minorTickVisibility (auto | show | hide) auto Indicates whether minor tick marks are visible.
charting.axisLabelsY.minorTickVisibility
auto: Shows a minor tick only if the
corresponding label is visible

252
 Property Type Default Description
show: Force all minor ticks to be
visible, regardless of label visibility

hide:Hide all minor ticks.

Applies only to Area, Bar, Column, and Line
charting.axisLabelsY2.majorTickSize Number 6 charts. The size, in pixels of the major tick
marks.

charting.axisX.includeZero Indicates whether the axis range includes

Boolean false
charting.axisY.includeZero zero.

charting.axisX.maximumNumber
Number auto Sets the maximum number for the axis range.
charting.axisY.maximumNumber

charting.axisX.minimumNumber
Number auto Sets the minimum number for the axis range.
charting.axisY.minimumNumber

Use a linear or logarithmic scale.

charting.axisX.scale
(linear | log) linear Only the bubble and scatter charts
charting.axisY.scale
support a logarithmic scale for the
x-axis.
charting.axisTitleX.text
charting.axisTitleY.text Text — Specifies the title of the axis.
charting.axisTitleY2.text

charting.axisTitleX.visibility Indicates whether to show the title of the x-axis

(visible | collapsed) visible
charting.axisTitleY.visibility or y-axis.

Applies only to Area, Bar, Column, and Line

charting.axisTitleY2.visibility (visible | collapsed) collapsed charts. Indicates whether to show the
secondary axis title when an overlay is used.

Override default limits for the number of data

charting.chart.resultTruncationLimit Number 50000
points rendered in a chart.

Indicates whether major grid lines on X-axis

charting.gridLinesX.showMajorLines Boolean false
are visible.

Indicates whether major grid lines on Y-axis

charting.gridLinesY.showMajorLines Boolean true
are visible.

Applies only to Area, Bar, Column, and Line

charting.gridLinesY2.showMajorLines Boolean false charts. Indicates whether major grid lines on
the second Y-axis are visible.

charting.gridLinesX.showMinorLines Applies only to Area, Bar, Column, and Line

charting.gridLinesY.showMinorLines Boolean False charts. Indicates whether minor grid lines are
charting.gridLinesY2.showMinorLines visible.

Applies only to Area, Bar, Column, and Line

charts.Splits a multi-series chart into separate
charting.layout.splitSeries Boolean False
charts that are stacked from top to bottom, one
for each series.

Applies only to Area, Bar, Column, and Line

charting.layout.splitSeries.allowIndependentYRanges Boolean False charts. When set to True, allows each series
to have its own Y-range.

charting.legend.placement right Where to place the legend.

253
 Property Type Default Description
(top | left | bottom |
right | none)
Area chart properties

Property Type Default Description

Configures the opacity of an area chart.

charting.areaFillOpacity 0 - 1.0 .75

1.0 means the area chart is solid. 0 indicates the area
chart is transparent.
charting.axisY2.enabled boolean false Enables a second y-axis for chart overlays.

charting.axisY2.fields comma delimited list — Fields to be mapped to a second y-axis for chart overlays.

Indicates whether to include zero in the second y-axis range for

charting.axisY2.includeZero boolean false
chart overlays.

Sets the maximum number for the y-axis range for chart
charting.axisY2.maximumNumber Number auto
overlays.

charting.axisY2.minimumNumber Number auto Sets the minimum number for the y-axis range for chart overlays.

Scale to use for a second y-axis for chart overlays.

charting.axisY2.scale (inherit | linear | log) inherit

Inherit from the first y-axis, or use a linear or
logarithmic scale.
charting.chart.overlayFields comma-delimited list — List of fields to use for a chart overlay.

Indicates how to display labels in the chart:

all: Display all labels

charting.chart.showDataLabels (all | minmax | none) none
minmax: Display labels only for the lowest and
highest values.

none: Do not display labels.

charting.chart.nullValueMode (gaps | zero | connect) gaps Determines how to handle null values.

charting.chart.showLines Boolean true Indicates whether to show lines in area charts.

(default | stacked |
charting.chart.stackMode default Set up stacked area charts.
stacked100)
Bar chart properties

Property Type Default Description

charting.chart.barSpacing Number 1 Specifies, in pixels, the spacing between bars in a bar chart.

Specifies, in pixels, the spacing between clustered series in a bar

charting.chart.seriesSpacing Number —
chart.

charting.chart.showDataLabels (all | minmax | none) none Indicates how to display labels in the chart:

all: Display all labels

254
 Property Type Default Description
minmax: Display labels only for the lowest and highest
values.

none: Do not display labels.

(default | stacked |
charting.chart.stackMode default Sets up stacked bar charts.
stacked100)
Bubble chart properties

Property Type Default Description

charting.chart.bubbleMaximumSize Number 50 Specifies, in pixels, the maximum size of each bubble.

charting.chart.bubbleMinimumSize Number 10 Specifies, in pixels, the minimum size of each bubble.

charting.chart.bubbleSizeBy (area | diameter) area Determines whether the area or the diameter determine the bubble size.
Column chart properties

Property Type Default Description

charting.axisY2.enabled boolean false Enables a second y-axis for chart overlays.

charting.axisY2.fields comma delimited list — Fields to be mapped to a second y-axis for chart overlays.

Indicates whether to include zero in the second y-axis range for

charting.axisY2.includeZero boolean false
chart overlays.

Sets the maximum number for the y-axis range for chart
charting.axisY2.maximumNumber Number auto
overlays.

Sets the minimum number for the y-axis range for chart
charting.axisY2.minimumNumber Number auto
overlays.

Scale to use for a second y-axis for chart overlays.

charting.axisY2.scale (inherit | linear | log) inherit

Inherit from the first y-axis, or use a linear or
logarithmic scale.
charting.chart.columnSpacing Number 1 Specifies, in pixels, the spacing between columns.

charting.chart.overlayFields comma-delimited list — List of fields to use for a chart overlay.

Specifies, in pixels, the spacing between clustered series in a

charting.chart.seriesSpacing Number —
column chart.

Indicates how to display labels in the chart:

all: Display all labels

charting.chart.showDataLabels (all | minmax | none) none
minmax: Display labels only for the lowest and
highest values.

none: Do not display labels.

(default | stacked |
charting.chart.stackMode default Sets up stacked column charts.
stacked100)

255
Line chart properties

Property Type Default Description

Enables a second y-axis for chart
charting.axisY2.enabled boolean false
overlays.

Fields to be mapped to a second

charting.axisY2.fields comma delimited list —
y-axis for chart overlays.

Indicates whether to include zero in

charting.axisY2.includeZero boolean false the second y-axis range for chart
overlays.

Sets the maximum number for the

charting.axisY2.maximumNumber Number auto
y-axis range for chart overlays.

Sets the minimum number for the

charting.axisY2.minimumNumber Number auto
y-axis range for chart overlays.

Scale to use for a second y-axis for

chart overlays.

charting.axisY2.scale (inherit | linear | log) inherit

Inherit from the first y-axis, or
use a linear or logarithmic
scale.
Determines how to handle null
charting.chart.nullValueMode (gaps | zero | connect) gaps
values.

List of fields to use for a chart

charting.chart.overlayFields comma-delimited list —
overlay.

Indicates how to display labels in

the chart:

all: Display all labels

charting.chart.showDataLabels (all | minmax | none) none
minmax: Display labels only
for the lowest and highest
values.

none: Do not display labels.

Indicates whether to draw markers
charting.chart.showMarkers Boolean false
in line charts.

charting.chart.stackMode (default | stacked | stacked100) default Set up stacked line charts.

(dash |dashDot | dot | longDash | longDashDot |

Specifies the dash style for all line
charting.lineDashStyle longDashDotDot | shortDash | dashDot |shortDot | solid
series in a chart.
shortDashDot | shortDashDotDot | solid)
Scatter chart properties

Property Type Default Description

charting.chart.markerSize Number 4 Indicates, in pixels, the size of markers.

256
Gauge charts

Properties specific to gauge charts:

Property Type Default Description

An array of hexadecimal color values from which the range band colors are
generated.

Colors display in the order indicated in the array.

For example, you can reverse the default green-yellow-red

[0x84E900, sequence by changing the gaugeColors value to:
charting.gaugeColors [Hex,...] 0xFFE800,
0xBF3030] [0xBF3030,0xFFE800,0x84E900]

You can specify any number of colors. If the gauge has more or
less range intervals than the number of rangeColors, colors are
interpolated as necessary. This interpolation occurs regardless
of whether you specify the range interval in the search language
or the rangeValues parameter.
charting.chart.majorUnit Number auto Specifies, in pixels, the spacing of major tick marks.

A numeric array that represents the overall numerical range represented by

the gauge, and the relative size of the color-coded subranges within that
overall range.

For example, a range of:

[0,30,70,100]

array of indicates that the gauge starts at zero, ends at 100, and has
charting.chart.rangeValues —
number three subranges that are each identified by another filler color. If
the search returns a value of 71, the filler rises to that value on
the gauge and takes on the color assigned to the top range,
which is 71-100.

Note: When you specify range values in simple XML, they

override range values that are specified through the search
upon which the dashboard panel is based.
charting.chart.showLabels Boolean True Indicates whether to display labels.

257
 Property Type Default Description
charting.chart.showMajorTicks Boolean True Indicates whether to display major tick marks.

See Indicates whether to display minor tick marks. Defaults to False for radial
charting.chart.showMinorTicks Boolean
description gauge and True for filler and marker gauges

charting.chart.showValue Boolean True Indicates whether the gauge displays its value.

Specify the display style of the gauge.

(minimal shiny: A graphically stylized version of the gauge with chrome,

charting.chart.style shiny
| shiny) shading, and other features to mimic a real world gauge.

minimal: A "just the basics" version of the gauge.

charting.chart.usePercentageRange Boolean False Indicates whether to format the range values as percentages.

charting.chart.usePercentageValue Boolean False Indicates whether to format the gauge values as percentages.
Filler gauge specific properties

Property Type Default Description

Sets the orientation of the gauge.

charting.chart.orientation (x | y) y x: horizontal

y: vertical
Marker gauge specific properties

Property Type Default Description

Sets the orientation of the gauge.

charting.chart.orientation (x | y) y x: horizontal

y: vertical
Indicates whether to show the color ranges as a band on the left side of the marker
charting.chart.showRangeBand boolean true
gauge.
Radial gauge specific properties

Property Type Default Description

The length of the range arc, in degrees.
charting.chart.rangeArcAngle Number 270
Positive values are clockwise. Negative values are counterclockwise.
The angle, in degrees, to begin drawing the range arc. The range arc is clockwise and
charting.chart.rangeStartAngle Number 45
starts from the bottom of the gauge.

charting.chart.showRangeBand boolean true Indicates whether to show the color ranges as a band at the top of the radial gauge.

258
Pie charts

Properties specific to pie charts:

Property Type Default Description

charting.chart.sliceCollapsingLabel Text Other The label for the consolidated slice.

The threshold at which smaller slices collapse into a consolidated slice.

Valid values are between 0 and 1.

charting.chart.sliceCollapsingThreshold Number 0.01 0 indicates no collapsing. 1 indicates all slices collapse into a
single pie.

The default value, 0.01, collapses slices smaller than 1% of the

whole pie.
charting.chart.showLabels Boolean true Indicates whether to display labels.

charting.chart.showPercent Boolean false Indicates whether to display percentage values with the labels.

Event handler reference

Form input event handlers

Event handlers are available to the following form input elements:

• <checkbox>
• <dropdown>
• <link>
• <multiselect>
• <radio>
• <text>
• <time>

Form input event tokens

Form input event handlers use predefined tokens to access the label and value of the selected <choice> element of an
input.

Token Description

259
label Access the label of the selected <choice> element of an input.

value Access the value of the selected <choice> element of an input.

change

<change>
Lets you set tokens based on a selected choice for a form input. Use with the <condition> element to define conditional
actions based on a selected choice.

The <change> element is not available for multiselect inputs.

Parent element

<input type="checkbox">
<input type="dropdown">
<input type="link">
<input type="radio">
<input type="text">
<input type="time">

<change>
<condition [label="foo" | value="foo" | match="(dashboard eval expression)"]>(0..n)
(<eval> | <link> | <set> | <unset>) (1..n)

Attributes

No attributes for this element.

Example

Use the <change> element to capture the selected label and value from an input.

<form>
<label>Use tokens with input choices to capture input labels and values</label>
<fieldset submitButton="false">
<input type="radio" token="period_tok">
<label>Select a time range</label>
<choice value="-24h@h">Last 24 Hours</choice>
<choice value="-7d@d">Last 7 Days</choice>
<choice value="-30d@d">Last 30 Days</choice>
<default>Last 24 Hours</default>

<change>
<!-- use predefined input tokens to set -->
<!-- tokens for the selected label and value -->
<set token="date_label">$label$</set>
<set token="earliest_tok">$value$</set>
</change>

</input>
</fieldset>

<row>
<panel>
<title>Conditional Inputs</title>

260
 <change>
<chart>
<!-- Display selected label in the title -->
<title>Source Type by $date_label$</title>

<search>
<query>index = _internal | timechart count by sourcetype</query>
<!-- use the value of earliest_tok -->
<!-- to set the time range -->
<earliest>$earliest_tok$</earliest>
<latest>now</latest>
</search>

<option name="charting.axisY.scale">log</option>
<option name="charting.axisTitleX.text">Time period</option>
<option name="charting.axisTitleY.text">Events</option>
</chart>
</panel>
</row>
</form>

Search event handlers

Search event handlers allow you to enable event actions based on search results or search properties. Actions include
linking to a page, setting or unsetting tokens, and executing an eval function.

Search event tokens

Search event handlers use predefined tokens to access the search results and search properties. The tokens available to
each handler vary. In some cases, the event handler does not access a predefined token to enable an action.

Token Description
job.property Access the value of the named job property or one of its secondary properties. For example, use
$job.request.earliest_time$ and $job.request.latest_time$ to access information about the search
time range.

261
 Token Description
You can also view properties for a search from the Search Job Inspector. From the Search Page, after
running a search select Job > Inspect Job.

See View search job properties in the Search Manual for a list of properties available.

result.field Access the value of the named field. The token accesses the value from the first row of returned results.

Search element syntax

<done | error | fail | cancelled | progress>
<condition match=(dashboard eval expression)>(0..n)
(<eval> | <link> | <set> | <unset>) (1..n)
For detailed information on search event tokens, see Define search tokens.

cancelled

<cancelled>
Execute actions when a search is cancelled.

Parent element

<search>

<cancelled>
<condition match="(dashboard eval expression)">(0..n)
(<eval> | <link> | <set> | <unset>) (1..n)

Tokens available

No tokens for this element.

Example

<cancelled>
<unset token="sourcetype_count" />
</cancelled>
error

<error>
Execute actions when there is a search error event, such as an invalid query.

Parent element

<search>

<error>
<condition match="(dashboard eval expression)">(0..n)
(<eval> | <link> | <set> | <unset>) (1..n)

262
 <error>

Tokens available

No tokens for this element.

Example

<search>
<error>
<set token="error_message">$message$</set>
</error>
</search>
fail

<fail>
Execute an action when a search fails while running.

Parent element

<search>

<fail>
<condition match="(dashboard eval expression)">(0..n)
(<eval> | <link> | <set> | <unset>) (1..n)

Tokens available

No tokens for this element. Only the failure message is available.

Example

<search>
<fail>
<set token="fail_message">$message$</set>
</fail>
</search>
progress

<progress>
Execute an action on search progress events. Access job properties and the first results row.

Parent element

<search>

<progress>
<condition match="(dashboard eval expression)">(0..n)
(<eval> | <link> | <set> | <unset>) (1..n)

Tokens available

job.property
result.field

263
 <progress>
Example

<progress>
<condition match=" 'job.resultCount' == 0">
<set token="show_html">true</set>
</condition>
<condition>
<unset token="show_html"/>
</condition>
<progress>
done

<done>
Execute actions based on finished search events.

Parent element

<search>

<done>
<condition match="(dashboard eval expression)">(0..n)
(<eval> | <link> | <set> | <unset>) (1..n)

Tokens available

job.property
result.field

Example

<done>
<condition match=" 'job.resultCount' == 0">
<set token="show_html">true</set>
</condition>
<condition>
<unset token="show_html"/>
</condition>
</done>

Visualization event handlers

<[Visualization]>
Event handlers apply to the following visualization types:

• chart
• event
• map
• single
• table

<[Visualization]>
<drilldown> (0..n)
<condition [label="foo" | value="foo" | match=(dashboard eval expression)]>(0..n)
(<eval> | <link> | <set> | <unset>) (1..n)
<selection> (0..n, for charts of type area, line, and column only)

264
 <[Visualization]>
(<eval> | <link> | <set> | <unset>) (1..n)

Child elements
element Type Default Description

Event
<drilldown> — Actions to take for drilldown behavior.
actions

Applies to charts of type area, column, or line.

<selection> <set> —
Use the <set> element to define tokens for the time window used in the pan and
zoom feature of charts.

Example

Example line chart panel using an inline search. It limits results to a specified time window and provides labels for the X
and Y axes:

<dashboard>
<label>Top source types in the last week</label>
<row>
<panel>
<title>Chart example</title>
<chart>
<title>Top sourcetypes in the last week</title>
<search>
<query>
index=_internal source="*metrics.log" group=per_sourcetype_thruput
| timechart sum(kb) by series
</query>
<earliest>-1w</earliest>
<latest>now</latest>
</search>
<option name="height">200px</option>
<option name="charting.chart">line</option>
<option name="charting.axisY.scale">log</option>
<option name="charting.chart.nullValueMode">connect</option>
</chart>
</panel>
. . .
</row>
</dashboard>

265
 <[Visualization]>

Drilldown event tokens

For dynamic drilldown, there are predefined tokens available for each type of visualization. The value of a predefined
token can vary, depending on the visualization.

• Chart event tokens

• Event event tokens
• Map event tokens
• Single event tokens
• Table event tokens

chart (event tokens)

The clicked field name is the name of the field or series for the y-Axis if present (similar to click.name2). If the name of the
field or series is not available the field or category for the x-axis is used (click.name).

Data Property Description

click.name Name of the field or category for the x-axis. Not available when the legend has been clicked.

click.value Value of the field or category for the x-axis. Not available when the legend has been clicked.

click.name2 Name of the field or series for the y-axis.

click.value2 Value of the field or series for the y-axis. Not available when the legend has been clicked.

Any field values along the y-axis at the same point as the click on the x-axis. Not available when the legend has been
row.<fieldname>
clicked.

row.<x-axis-name> Value of the x-axis. Not available when the legend has been clicked.

earliest/latest Time range of the clicked chart segment, or if not applicable, the time range of the search.

event (event tokens)

The value for click.name depends on the context of the click, as described below:

Data Property Description

266
 Data Property Description
The field name associated with the click.

For cases in the event viewer where the field name is ambiguous:
click.name • Click a term in the raw event: Sets _raw as the field name.
• Click the event timestamp: Sets _time as the field name.
• Click a tag: Sets a field name according to the tag name, as follows:
tag::<field>
(for example, when host is tagged, tag::host)

click.value Value associated with the click.

click.name2 Identical to click.name.

click.value2 Identical to click.value.

row.<fieldname> Exposes each field value as row.<fieldname>.

Time range of the clicked event, which is:

earliest/latest
earliest: _time
latest: (_time + 1 second)

map (event tokens)

The field for the <condition> tag in dynamic drilldown always corresponds to click.name.

Data Property Description

click.name Name of the first, or only field, that displays the marker.

click.value Value of the first, or only field, that displays the marker.

click.name2 Same as click.name.

click.value2 Same as click.value

click.lat.name Name of the latitude field that determines the location of the marker.

click.lat.value Latitude value of the geo location of the marker.

click.lon.name Name of the longitude field that determines the location of the marker.

click.lon.value Longitude value of the geo location of the marker.

Outer boundaries of all clustered locations that the marker represents.

click.bounds.<orientation>
Orientation: south, west, north, east
row.<fieldname> Each field value of the clicked marker is exposed in this form.

earliest/latest Time range of the search driving the map visualization.

267
single (event tokens)

The field for the <condition> tag in dynamic drilldown always corresponds to click.name.

Data Property Description

click.name Name of the field that is displayed by the single value visualization.

click.value Value that is displayed by the single value visualization.

click.name2 Same as click.name.

click.value2 Same as click.value.

row.<fieldname> Exposes each field in the same result row from which the single value is taken.

earliest/latest Time range of the search driving the single value visualization.
table (event tokens)

The field for the <condition> tag in dynamic drilldown always corresponds to click.name2.

Data Property Description

click.name Name of the leftmost field that is displayed in the table. This is always _time, if present.

click.value Value of the left-most column in the clicked row.

click.name2 Name of the clicked column.

click.value2 Value of the clicked column.

row.<fieldname> All field values for the clicked table row, including those fields that are not displayed.

earliest/latest Time range of the clicked table row, or if not applicable, the time range of the search.

drilldown

<drilldown>

Define custom destinations to link to when a user clicks on fields in a dashboard or form.

Specify a path to the destination using the <link> tag.

Set or unset tokens using the <set> or <unset> tags.
Specify a condition to specify fields for setting or unsetting tokens.

Note: You can specify one or more actions (<eval>, <link>, <set>, <unset>) or conditions (<condition>) directly within
<drilldown>, but you cannot specify both actions and conditions.

For details see Dynamic drilldown in dashboards and forms.

Attributes
Name Type Default Description

target text — Corresponds to the target attribute of the <a> HTTP tag.

Specify "_blank" to open the drilldown in a new window.

268
 <drilldown>

Name Type Default Description

Specify "_self" to open the drilldown in the same window.

Specify an arbitrary string to open the drilldown in a new window. Subsequent references to this
target open in this window.

Parent elements

<chart> <event> <map> <single> <table>

<drilldown>
( <eval> | <link> | <set> | <unset> ) (1..n) | <condition> (1..n)

Example 1: Pass a value to a form

<table>
<searchString>index=_internal</searchString>

<!-- Pass the clicked row's 'count'-column value -->

<!-- to populate a destination form's 'foo' token. -->
<drilldown>
<link>
/app/search/simple_xml_form?form.foo=$row.count$
</link>
</drilldown>
</table>

Example 2: Pass parameters to a form

<table>
<searchString>index=_internal</searchString>

<!-- Pass the clicked cell's value, earliest time, -->

<!-- and latest time to a destination form's -->
<!-- token ('foo') and search parameters -->
<drilldown>
<link>
<![CDATA[
/app/search/simple_xml_form?form.foo=$click.value2$&earliest=$earliest$&latest=$latest$
]]>
</link>
</drilldown>
</table>

Example 3: Pass a value from a chart to a website

<chart>
<searchString>
index=_internal | chart count by sourcetype
</searchString>
<option name="charting.chart">column</option>

<!-- $click.value$ captures the value clicked by the user -->

<!-- From the x-axis of a column chart and passes -->
<!-- it to the website as a query parameter -->
<drilldown>
<link>
http://splunk-base.splunk.com/integrated_search/?q=$click.value$
</link>
</drilldown>
</chart>

269
 <drilldown>

selection

<selection>
Sets the time window for the pan and zoom feature of charts. You can also use tokens to set other values, such as the numerical values of the
x-axis in a chart.

Only applies to charts of type area, column, or line.

See Chart controls for details on the pan and zoom feature of charts.
Parent elements

<chart>
<option name="charting.chart">area</option>
| <option name="charting.chart">column</option>
| <option name="charting.chart">line</option>

Use pre-defined tokens to capture the earliest and latest time of the time window and the earliest and latest values within that time window for a
field.

For example:

<selection>
<set token="selection.earliest">$start$</set>
<set token="selection.latest">$end$</set>
<set token="start.[fieldname]">$start.[fieldname]$</set>
<set token="end.[fieldname]">$end.[fieldname]$</set>
</selection>

Can also be used to set a drilldown link.

<selection>
<link>

Attributes

No attributes for this element.

Example

A selection on the left chart zooms into the right chart with details for the selected area.

<dashboard>
<label>Pan and Zoom</label>
<row>
<panel>
<chart>
<title>Pan and Zoom (All source types)</title>
<search>
<query>
index=_internal | timechart count by sourcetype
</query>

270
 <selection>
<earliest>-7d@h</earliest>
<latest>now</latest>
</search>
<option name="charting.axisX.scale">linear</option>
<option name="charting.axisY.scale">log</option>
<option name="charting.chart">line</option>
<selection>
<set token="selection.earliest">$start$</set>
<set token="selection.latest">$end$</set>
<set token="start.splunk_web_access">$start.splunk_web_access$</set>
<set token="end.splunk_web_access">$end.splunk_web_access$</set>
</selection>
<option name="charting.axisTitleX.text">Last 7 Days</option>
</chart>
</panel>
<panel>
<chart>
<title>Pan and Zoom (Web access source type)</title>
<search>
<query>
index=_internal sourcetype=splunk_web_access
| timechart count by sourcetype
</query>
<earliest>$selection.earliest$</earliest>
<latest>$selection.latest$</latest>
</search>
<option name="charting.chart">column</option>
<option name="charting.legend.placement">none</option>
<option name="charting.legend.masterLegend">null</option>
<option name="charting.axisX.scale">linear</option>
<option name="charting.axisY.scale">log</option>
<option name="charting.axisTitleX.text">Selected Time Range</option>
</chart>
</panel>
</row>
<row>
<panel>
<html>
<h3>Token values for the splunk_web_access selection</h3>
<table border="0" cellpadding="12" cellspacing="0">
<tr>
<td>
<p><b>Time range (epoch time)</b></p>
<p>
<b>$$selection.earliest$$</b>: $selection.earliest$<br/>
<b>$$selection.latest$$</b>: $selection.latest$
</p>
</td>
<td>
<p><b>Count at the begining and end of time range.</b></p>
<p>
<b>$$start.splunk_web_access$$</b>: $start.splunk_web_access$<br/>
<b>$$end.splunk_web_access$$</b>: $end.splunk_web_access$</p>
</td>
</tr>
</table>
</html>
</panel>
</row>

271
 <selection>
</dashboard>

Condition element

The <condition> element specifies the scope of actions based on one more conditions. The available conditions on which
to base actions differ, depending on the parent element. The attributes available to the condition element vary, depending
on the parent element.

• Condition (input)
• Condition (search)
• Condition (drilldown)

Condition (input)

<condition>
Specifies the scope of actions based on input choices. If the parent element <change> is not present, then the actions
apply to all choices. The <condition> element is not available for multiselect inputs.
Parent element

<input>
<change>

<condition>
(<eval> | <link> | <set> | <unset>) (1..n)

Attributes
Name Type Default Description

Specifies the input <label> element to which the condition applies.

label text *
'*' applies the condition to all input <label> elements.
match eval expression — An eval expression that defines the conditions needed for actions to be executed.

value text * Specifies the input <value> element to which the condition applies.

272
 <condition>

Name Type Default Description

'*' applies the condition to all input <value> elements.

Example

Use conditional inputs to select preset time ranges for a search.

The token for the selected choice appears in the title for the chart. The conditional token for the selected value drives the
data for the chart.

<form>
<label>Use tokens with conditional input choices</label>
<fieldset submitButton="false">
<input type="radio" token="period_tok">
<label>Select a time range</label>
<choice value="-24h@h">Last 24 Hours</choice>
<choice value="-7d@h">Last 7 Days</choice>
<choice value="-30d@h">Last 30 Days</choice>
<default>Last 24 Hours</default>

<!-- set condition based on the label defined by <choice> -->

<!-- Within each condition, specify a custom label for display -->
<!-- Capture the selected value in the token, earliest_tok -->
<change>
<condition label="Last 24 Hours">
<set token="date_label">Yesterday</set>
<set token="earliest_tok">$value$</set>
</condition>
<condition label="Last 7 Days">
<set token="date_label">Last week</set>
<set token="earliest_tok">$value$</set>
</condition>
<condition label="Last 30 Days">
<set token="date_label">Last month</set>
<set token="earliest_tok">$value$</set>
</condition>
</change>
</input>
</fieldset>
<row>
<panel>
<title>Conditional Inputs</title>
<chart>

<!-- Display selected label in the title -->

<title>$date_label$</title>

<search>
<query>index = _internal | timechart count by sourcetype</query>
<!-- use the value of earliest_tok -->
<!-- to set the time range -->
<earliest>$earliest_tok$</earliest>
<latest>now</latest>
</search>

<option name="charting.axisY.scale">log</option>

273
 <condition>
<option name="charting.axisTitleX.text">Time periods</option>
<option name="charting.axisTitleY.text">Events</option>
</chart>
</panel>
</row>
</form>

Condition (search)

<condition>
Specifies a condition and behavior for when the condition is met.

Parent elements

<cancelled> | <done> | <error> | <fail> | <progress>

<condition [match=[eval statement]]>

(<eval> | <link> | <set> | <unset>) (1..n)

Attributes
Name Type Default Description

An eval expression that defines the conditions needed for actions to be

match eval expression —
executed.

Example

<condition match=" 'job.resultCount' == 0">

    <set token="show_table_query">true</set>
</condition>
Condition (drilldown)

<condition>
Limits the scope of drilldown actions to clicks on specific fields. If the <condition> element is not present, then drilldown
actions apply to all fields.

274
 <condition>
Note: The <condition> element applies to both input elements and drilldown elements. See <condition> (input) for
details.
Parent element

<drilldown>

<condition>
(<eval> | <link> | <set> | <unset>) (1..n)

Attributes
Name Type Default Description

field text * Specifies the search field on which to implement the drilldown, or to set or unset a token.

Example

See the example for <set> for using the <condition> tag to set a token for in-page drilldown.

See the example for <unset> for using multiple <condition> tags.
Event actions

eval

<eval>
Executes an eval statement. An eval statement evaluates an expression and puts the results into a field. <eval> for dashboards works similarly,
with some exceptions, to the SPL eval command. For more details, see eval in the Search Reference.

Parent elements

<drilldown><condition>
<search><condition>
<change><condition>

<drilldown>
<eval token="[token_name]">

<drilldown>
<condition>
<eval token="[token_name]">

<change>
<eval token="[token_name]">

<change>
<condition>
<eval token="[token_name]">

<search>
<condition>
<eval token="[token_name]">

<search>
<eval token="[token_name]">

275
 <eval>

Attributes
Name Type Default Description

Token whose value is the result of the eval expression. In an <eval> expression, you can use either $...$
delimiters or single quote delimiters for tokens. For example, both of the following options are valid.
token text
$my_token$
'my_token'

Example

<eval token="new_token">[eval expression]</eval>

link

<link>
Specifies a link to a destination for drilldown or for a selected input choice.

<link> can be a child tag of <change>, <drilldown>, <search>, or <condition>.

Use <link> as a child tag of <condition> when you want to configure distinct drilldown actions for specific fields or inputs.
Otherwise, use <link> as a child tag of <change> or <drilldown>.

There are various ways to specify a destination for the drilldown using relative paths or a URL, as described below
Parent elements

<drilldown><condition>
<search><condition>
<change><condition>

<drilldown>
<link>

<drilldown>
<condition>
<link>

<change>
<link>

<change>
<condition>
<link>

<search>
<condition>
<link>

<search>
<link>

276
 <link>
Attributes
Name Type Default Description

Deprecated. Use <condition field="[field]"...>

(<drilldown> only) Specifies which values to capture in a table from the specified column or
Field
field row. Cannot be specified together with the series attribute.
name

Although the field attribute is supported, Splunk recommends that you specify fields with the
<condition> tag.
Deprecated. Use <condition field="[field]"...>

(<drilldown> only) Specifies which values to capture in a chart from the specified series.
Series
series Cannot be specified together with the field attribute.
name

Although the series attribute is supported, Splunk recommends that you specify series with
the <condition> tag.
Corresponds to the target attribute of the <a> HTTP tag. Specifying target for the <link> element overrides
the value of target specified in the <drilldown> element.

Specify "_blank" to open the drilldown in a new window.

target text —
Specify "_self" to open the drilldown in the same window.

Specify an arbitrary string to open the drilldown in a new window. Subsequent references to
this target open in this window.

Parent element

<drilldown><condition>

1) <link> [viewname] </link>

2) <link> [path/viewname] </link>
3) <link> [path/viewname?form.token=$dest_value$] </link>
4) <link> [path/viewname?form.token=$dest_value$&earliest=$earliest$&latest=$latest$] </link>
5) <link> [URL?q=$dest_value$] </link>

1. Use the specified view, which must be in the same path as the current dashboard.
2. Relative path to connect to a dashboard.
3. Relative path to connect to a form, passing in a token to populate the form.
4. Pass in the earliest and latest time range from the original search.
(Requires use of CDATA to escape special characters.)
5. URL and query argument to pass a value to the destination page.

Path values Description

A path to the destination view from the current view. Typically, you specify path as: /app/app_name/

path
However, you can also specify a relative path, based on the app context of the source and destination
views.
viewname The name of the Splunk view you are using for a destination.

277
 <link>

Path values Description

$dest_value$ Specifies how to capture a value from a visualization. See Drilldown event tokens for details on each visualizaion.

URL Specify a URL to a web page. Use the full address, including the protocol. For example: http://.

q When specifying a URL, use q to specify the value of dest_value in a query string to a web resource.

Example

Use <link> with conditional inputs to open a new page.

<form>
. . .
<fieldset>
<input type="dropdown" token="openNewPageToken">
<label></label>
<default>Select a page to open</default>
<choice value="">Select a page to open</choice>
<choice value="manager_page">View prebuilt panels</choice>
<choice value="splk_page">Open Splunk home page</choice>
<change>
<condition value="manager_page">
<link target="_blank">
<![CDATA[/manager/search/data/ui/panels?ns=-&pwnr= -&search=&count=25]]>
</link>
</condition>
<condition value="splk_page">
<link target="_blank">
http://splunk.com
</link>
</condition>
</change>
</input>
</fieldset>
. . .
</form>

278
 <link>

set

<set>
Allows you to publish new global tokens that can be consumed by any other element or search within the dashboard.
You typically publish tokens when using form inputs or when using drilldown.

For form inputs, specify tokens for actions to take for specific inputs.

For drilldown, specify the value to capture when clicked. The value can be set dynamically using a token.

For form inputs, <set> can be a child tag of <change> or <condition>.

For drilldown, <set> can be a child tag of <drilldown> or <condition>.

Use <set> as a child tag of <condition> when you want to configure distinct actions for specific inputs or for fields for
drilldown. Otherwise, use <set> as a child tag of <change> or <drilldown> to specify an action for all inputs or for all
fields.
Parent elements

<change>
<condition>

<drilldown >
<condition>

<change>

<drilldown>

There are two ways to set a value of a token.

1. Use a template to combine input tokens and static portions to form the new token value. Templates let you reference
multiple tokens when setting the value, and also specify quotes for the value using the |s token filter.

<set token="Token Name">sourcetype=$click.value|s$</set>

279
 <set>
2. Use the prefix and suffix attributes to specify static portions for the input token. The following is equivalent to the
template example above.

<set token="Token Name" prefix="sourcetype=&quot;" suffix="&quot;">$click.value$</set>

Attributes
Name Type Default Description

token Token name Required The name of the token to be consumed by the target visualization on the same page.

prefix text String to place before the value of the token.

suffix text String to append to the value of the token.

Example

A click on the table sets a token which is consumed by the search of the chart visualization.

<dashboard>
<label>In-page Drilldown</label>
<row>
<panel>
<table>
<title>Set sourcetype token on click</title>
<search>
<query>
index=_internal | stats count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
<drilldown>
<condition field="sourcetype">
<set token="sourcetype">$click.value2$</set>
</condition>
</drilldown>
</table>
<chart>
<title>Chart for $sourcetype$</title>
<search>
<query>
index=_internal sourcetype=$sourcetype$ | timechart count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
</chart>
</panel>
</row>
</dashboard>
unset

<unset>
Use <unset> to remove a token that was previously set.
Parent element

280
 <unset>
<change>
<condition>

<drilldown>
<condition>

<change>

<drilldown>

<unset token="''Token Name''">

Attributes
Name Type Default Description

token Token name Required The name of a token that was previously set, but to be ignored.

Example

Use <set> and <unset> to define the visualization to use.

Use token definitions to hide a panel.

<dashboard>
<label>Example for <set> and <unset></label>
<row>
<panel>
<table>
<title>Set sourcetype token</title>
<search>
<query>
index=_internal | stats count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
<drilldown>
<!-- For the sourcetype field clicked: -->
<!-- Set token to display a chart -->
<!-- Unset token to display a table -->
<condition field="sourcetype">
<set token="sourcetype">$row.sourcetype$</set>
<set token="showChart">foo</set>
<unset token="showTable"></unset>
</condition>
<!-- For any other field clicked: -->
<!-- Set token to display a table -->
<!-- Unset token to display a chart -->
<condition field="*">
<set token="sourcetype">$row.sourcetype$</set>
<set token="showTable">foo</set>
<unset token="showChart"></unset>
</condition>
</drilldown>
</table>
</panel>

281
 <unset>

<!-- Hide the html panel when either token is present -->
<!-- Click in the original table to set either token -->
<panel>
<html rejects="$showTable$, $showChart$">
<h2>Details</h2>
<div style="padding: 50px; margin: 0 auto; width: 350px;">
<div class="alert alert-warning">
<i class="icon-alert"/>
Click on a row in the table on the left to show details.
</div>
</div>
</html>
<!-- if showChart token is set, display results here -->
<chart depends="$showChart$">
<title>Details for $submitted:sourcetype|s$</title>
<search>
<query>
index=_internal sourcetype=$sourcetype|s$
| timechart count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
</chart>
<!-- if showTable token is set, display results here -->
<table depends="$showTable$">
<title>Details for $submitted:sourcetype|s$</title>
<search>
<query>
index=_internal sourcetype=$sourcetype|s$
| timechart bins=10 count by sourcetype
</query>
<earliest>-1h</earliest>
<latest>now</latest>
</search>
<option name="wrap">true</option>
<option name="rowNumbers">false</option>
<option name="dataOverlayMode">none</option>
<option name="drilldown">cell</option>
<option name="count">10</option>
</table>
</panel>
</row>
</dashboard>

Token reference
Tokens are a type of variable that can be used to pass values in a simple XML dashboard. This reference lists the types
of tokens available for various scenarios.

See Token usage in dashboards for further details on token usage.

Token Type Elements Description

Form input <input> User defined input for referencing the value selected from an input.

282
 Token Type Elements Description
See Define tokens for form inputs.

Form input example

Optional user defined input token to associate two or more time pickers with multiple panels in a
dashboard.

Contains the earliest and latest modifiers to capture the time range.
Time picker input <input type="time">

See Define tokens for time inputs.

Time input example

Predefined tokens to capture the value from a click in a chart. Dynamic drilldown operations use the
captured value from the source chart when accessing the drilldown target.

Drilldown event <drilldown>

See Drilldown event tokens for a list of the predefined tokens.

See Define tokens for drilldown.

Predefined tokens to capture a range of values for a pan and zoom operation. The token values
apply to a user selection on the chart. The context of the tokens is only for the chart. Copy the token
values into user defined tokens to access the values in the dashboard.

start and end capture the values of the X-axis of a chart for the beginning and end
of the selected area. For example, a selection in a time chart captures the starting
and ending time of the selection.
Pan and zoom
<selection> start.<field>and end.field capture the values of the Y-axis of a chart at the
event
beginning and end of the selected area. For example, a selection in a time chart
captures the number of events for the series specified by <field>.

See Define tokens for pan and zoom chart controls.

Define tokens for pan and zoom chart controls contains an example using a time
chart.
User defined token within a condition element to configure conditional operations. Conditional
operations include:

<drilldown> • Set token values based on the condition.

Conditional <condition> • Select a value for a multivalue fields in a visualization.
drilldown action <link> • Select a view to open based on a token value.
<set>|<unset> • Hide or show panels based on conditions.

See Define tokens for conditional operations with the <drilldown> element.
User defined token within a condition element to modify searches or select which visualization to
<input> display based on the conditional value of a token.
<change>
Conditional form
<condition>
input action See Define tokens for conditional operations with form inputs.
<link>
<set>|<unset>
Conditional operations with form inputs example

283
 Token Type Elements Description
Set and unset tokens to specify a target page to open.
<input>|<drilldown>
Set destination <condition>
Can be used with the <input> element or <drilldown> element. The <condition>
action <link>
<set>|<unset> element defines the condition for the action. The <link> element consumes the
token to open the target destination.

Customize Simple XML

Splunk Enterprise users can extend Simple XML to incorporate custom CSS and JavaScript into a dashboard.

For more information, see Modify dashboards using Simple XML on the Splunk developer portal.

284