Developing Dashboards, Views, and Apps for Splunk Web

 


Build a dashboard using Advanced XML

NOTE - Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

Build a dashboard using Advanced XML

Use Advanced XML to add features to dashboards that are not available using Simplified XML. This topic provides an example of building a dashboard using AdvancedXML.

Splunk recommends that you start building a dashboard with Simplified XML, and then convert to Advanced XML to add advanced features. However, this example shows how to create a dashboard using Advanced XML only within the file system.

Here's a general overview of how to build a dashboard:

  1. Decide how to visualize and display your data. For example, you may want to showcase your search results in a graph or you may want to present a list of links to search results.
  2. Construct searches and optionally save them.
  3. Build panels for each search.
  4. Construct a dashboard from the panels.
  5. Finally, lay out the dashboard panels.

Begin your dashboard

In an XML editor, create a minimal dashboard file, listed below in the following directory:

$SPLUNK_HOME/etc/apps/<your_app>/default/data/ui/views/

Minimal XML file:

<view template="dashboard.html">
. . .
</view>

Dashboard views always specify dashboard.html for the dashboard template. Dashboard views use a different Mako template than the default template used by search views, so you must specify this template at the beginning of your dashboard's XML file.

You can set the refresh rate for a dashboard using the refresh=<seconds> attribute, as indicated below. This attribute specifies how often to rerun HiddenSearches or get any new HiddenSavedSearch results.

This example sets the dashboard to refresh every 30 minutes:

<view refresh="1800" template="dashboard.html">
. . .

Name a dashboard

Use the <label> tag to provide a name to a dashboard:

<view template="dashboard.html">
  <label>My Dashboard</label>
  . . .

Add chrome

Add chrome to define how the appearance of the dashboard.

For each module, specify a layoutPanel to specify the chrome. The top-level module requires a layout panel. A nested module can optionally specify a layout panel. If you don't specify a layout panel for a nested module, it inherits the layout module from its parent. For the most control, it is a good idea to specify a layout panel for each module.

<view template="dashboard.html">
  <label>My Dashboard</label>
  <module name="AccountBar" layoutPanel="appHeader"/>
  <module name="AppBar" layoutPanel="navigationHeader"/>
  <module name="Message" layoutPanel="messaging">
    <param name="filter">*</param>
    <param name="clearOnJobDispatch">False</param>
    <param name="maxSize">1</param>
  </module>
Note: To see how the default Search dashboard specifies layout panels for its modules, go to:
http://localhost:8000/en-US/app/search/dashboard_live?showsource=true
Scroll to the XML source to view the implementation.

Chrome layout panels

Here are the available layout panels:

Module Description
messaging Use this layoutPanel for messaging modules.
appHeader appHeader contains all the overall links for Splunk AccountBar.
navigationHeader Use this layoutPanel for the AppBar module, which contains all the navigation for the App.
viewHeader viewHeader is a header panel for your view, where you can put a title for your page.

Add panels

A panel typically displays results of a search as a table, event listing, or other visualization such as a chart or graph. When building a dashboard, decide how you want to showcase your data with the available modules. The results modules are the most useful modules to display search results.

Here's an example panel:

Panel.jpg

And here's the XML behind this panel:

  <module name="HiddenSearch" layoutPanel="panel_row1_col1"
       group="Messages per minute last hour" autoRun="True">
    <param name="search">
       search index=_internal eps group=per_source_thruput NOT filetracker Metrics 
       | eval events=eps*kb/kbps | timechart sum(events)
    </param>
    <param name="earliest">-1h</param>

    <module name="ResultsHeader">
      <param name="entityName">scanned</param>
      <param name="entityLabel">Events</param>

      <module name="FlashChart">
        <param name="height">180px</param>
        <param name="width">100%</param>
      </module>

    </module>
  </module>

Each panel typically has only one search associated with it, usually with the HiddenSearch or HiddenSavedSearch module. Display results from the search in a results module, such as a chart or a link list. The panel from the previous example has three modules: HiddenSearch, ResultsHeader and FlashChart. HiddenSearch generates the search results while FlashChart displays them. ResultsHeader displays a header showing the amount of events searched by HiddenSearch.

HiddenSearch is the parent module and therefor specifies the layoutPanel, group, and autoRun settings. LayoutPanel denotes where to place the panel on the dashboard. Group is a header for the panel. AutoRun indicates that the search in the panel should be run upon loading the page. Typically, you set autoRun = true.

Searches and dashboard panels

A search for a panel can be either a saved search or an inline search.

Saved search: Create the search, save it and run it on a schedule. Then reference the search results from your dashboard with the HiddenSavedSearch module. Saved searches are best for dashboards that are accessed by many users or the search is a long-running search.

Inline search: Specify the search query directly in the dashboard panel with the HiddenSearch module. The HiddenSearch module runs the search every time the dashboard loads. Inline searches are best for dashboards that have only a few users and the search results return quickly.

Lay out your panels

Panels in a dashboards use a coordinate system to specify their position on the dashboard. The parent module in a panel specifies what coordinate to use. Coordinates specify the row and column position using the layoutPanel attribute to a <module> tag. For example:

<module layoutPanel="panel_rowX_rowY">
   . . .

You can specify any number of rows, but you can only specify three columns. For example, here are two parent modules of panels in a dashboard:

<view>
. . .
  <module name="HiddenSearch" 
      layoutPanel="panel_row1_col1" 
      group="Messages per minute last hour"
      autoRun="True">
   . . .
   <module name="HiddenSearch" 
       layoutPanel="panel_row1_col2" 
       group="KBps indexed per hour last 2 hours"
       autoRun="True">
   . . .

You can also set up a group of panels within a larger panel using a single parent module. The following example uses StaticContentSample to set a header for the entire group of panels. Each panel has one parent module to specify the layoutPanel with the addition of the grp attribute for placement within a group.

<module name="StaticContentSample" 
    layoutPanel="panel_row2_col1" 
    group="All Indexed Data" 
    autoRun="True">
    <param name="text">
      This will show you all of the data you have loaded 
       into index=main over all time.
      </param>
  <module name="GenericHeader" 
      layoutPanel="panel_row2_col1_grp1">
     <param name="label">Sources</param>
  . . .
  <module name="GenericHeader" 
       layoutPanel="panel_row2_col1_grp2">
       <param name="label">Sourcetypes</param>
  . . .
  <module name="GenericHeader" 
       layoutPanel="panel_row2_col1_grp3">
       <param name="label">Hosts</param>
. . .

Add a search bar

You can add a search bar to a dashboard using the same panels you use for the search bar in a search view:

Module Description
splSearchControls-inline Aligns search modules next to each other in columns. The first module expands to occupy space not occupied by the other modules.
mainSearchControls Aligns search controls one after another, typically using a vertical alignment.

The following example shows a search bar with a ViewRedirector module to launch searches in a different view.

 <module name="SearchBar" layoutPanel="mainSearchControls">
    <param name="useAssistant">true</param>
    <param name="useTypeahead">true</param>
    <module name="TimeRangePicker">
      <param name="selected">This month</param>
      <module name="ViewRedirector">
        <param name="viewTarget">simple_search_view</param>
      </module> <!-- End ViewRedirector-->
    </module> <!-- End TimeRangePicker-->
 </module> <!-- End SearchBar-->

This documentation applies to the following versions of Splunk: 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 4.3.7 View the Article History for its revisions.


Comments

In the Add a search bar section, splSearchControls-inline and mainSearchControls are not modules, they are layoutpanels

It would be really great if there were a place in the documentation that identified all the layout panels in one section; if there is one I haven't found it. :)

Khodges splunk, Splunker
April 26, 2012

You must be logged into splunk.com in order to post comments. Log in now.

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!