Splunk 4.3.

4
Developing Dashboards, Views, and Apps for Splunk Web
Generated: 9/10/2012 12:21 pm

Copyright 2012 Splunk, Inc. All Rights Reserved

Table of Contents
Overview...............................................................................................................1 What's in this manual................................................................................1 Use cases for this manual.........................................................................1 Build dashboards .................................................................................................4 Dashboards: An introduction.....................................................................4 Saved searches and dashboards ..............................................................6 Step 1: Create a dashboard......................................................................9 Step 2: Add rows.....................................................................................13 Step 3: Add panels..................................................................................14 Add a chart..............................................................................................18 Add a table...............................................................................................20 Add a list.................................................................................................21 Add HTML...............................................................................................22 Add a single value and gauges...............................................................23 Add an event listing.................................................................................26 Build a real-time dashboard....................................................................27 Dashboard example................................................................................28 Build forms.........................................................................................................32 Forms: An introduction............................................................................32 Create a simple form search...................................................................36 Define inputs to a form............................................................................40 Display form search results.....................................................................43 Create a dynamic form search with radio buttons...................................46 Create a dynamic form search using drop-downs ...................................48 Drive multiple panels in a form................................................................50 Form search examples ............................................................................53 Build advanced views ........................................................................................59 About Advanced XML.............................................................................59 Build a search view using Advanced XML..............................................64 Build a dashboard using Advanced XML................................................69 Build a form search using Advanced XML..............................................75 Use XML schemas..................................................................................80 Advanced charting options......................................................................81 Customize drilldown options...................................................................90 Build a real-time dashboard....................................................................96 Turn off autopause..................................................................................98
i

Table of Contents
Build advanced views Switcher modules....................................................................................98 Lister modules.......................................................................................102 Use lookups with a view........................................................................106 Use one search for a whole dashboard................................................108 Customize Splunk Web...................................................................................113 Customization options...........................................................................113 Customize the login screen...................................................................114 Customize the login screen...................................................................114 Embed Splunk dashboard elements in third party software..................114 Customize event display.......................................................................117 Add Web resources to your view..........................................................121 Customize CSS.....................................................................................125 Translate Splunk...................................................................................128 Plot search results on a map .................................................................131 Build apps .........................................................................................................137 Apps and add-ons: an introduction.......................................................137 Step 1: Getting started..........................................................................142 Step 2: Create your app........................................................................145 Step 3: Add configurations....................................................................146 Step 4: Add objects...............................................................................148 Step 5: Set permissions........................................................................150 Step 6: Build navigation for your app....................................................152 Step 7: Configure a setup screen ..........................................................159 Step 8: Package your app or add-on....................................................167 Files and directories for apps and add-ons...........................................172 Setup screen example..........................................................................178 Setup screen example using a custom endpoint..................................182 Setup screen example with user credentials .........................................186 How to migrate 3.X apps to 4.1.X.........................................................188 What's changed for app developers in 4.2............................................190 How to restrict your users to one app...................................................195 Build scripted inputs.......................................................................................197 Scripted inputs overview.......................................................................197 Setting up a scripted input ....................................................................198 . Writing reliable scripts............................................................................201
ii

Table of Contents
Build scripted inputs Example script that polls a database....................................................207 Extend Splunk..................................................................................................212 Extend Splunk.......................................................................................212 Splunk SDKs..........................................................................................212 Custom search commands...................................................................213 Splunk's API is RESTful........................................................................219 View reference material...................................................................................221 Panel reference for Simplified XML .......................................................221 Module Reference..................................................................................228 setup.xml...............................................................................................300 Custom charting configuration reference.....................................................305 Overview of the custom chart configuration reference..........................305 Chart and legend properties ..................................................................308 Axis and grid line properties..................................................................341 Tooltip properties..................................................................................353 Font, color, brush, shape and related palette properties .......................355 Advanced configuration - Layout and data table properties..................405 Advanced configuration - textBlock, layoutSprite, and sprite properties...............................................................................................411

iii

Overview
What's in this manual
Prior to Splunk 4.3, this manual was titled Splunk Developer Manual. However, with the introduction of the Splunk Developer Portal , which covers material related to development on Splunk using the Splunk SDKs and the Splunk App Framework, the Splunk Developer Manual is now more accurately titled Developing Dashboards, Views, and Apps for Splunk Web. The content of this manual for Splunk 4.2.5 or earlier remains the same. The change in title does not affect any links or bookmarks to previous content. For Splunk 4.3, the manual contains updated content to reflect new features introduced with that release. This manual contains information for building dashboards, forms, and advanced views. It also provides an introduction to building apps and add-ons for Splunk Web. This manual no longer covers leveraging Splunk SDKs in your applications. Developers who want to use the Splunk SDKs or build and customize apps using the Splunk App Framework should visit the Splunk Developer Portal.

Use cases for this manual

Here's an overview of the topics in this manual and why you'd want to use them.

Build dashboards
A dashboard is a view within Splunk Web that allows you to customize the visualization of data returned from searches. Using Splunk access control features, you can specify permissions to target specific dashboards for specific users. You can create simple dashboards interactively from the editing tools available with Splunk Web. For details on using the Splunk Dashboard Editor, Search Editor, and Visualization Editor, see "Create and edit simple dashboards" and "Edit dashboard panel visualizations" in the Splunk User Manual. You can add additional functionality to a dashboard by editing the XML upon which the
1

dashboard is configured. This manual shows how to create and edit dashboards by editing the XML upon which a dashboard is based.

Build forms
A form is a view within Splunk Web that guides a user to enter specific data for a search. You can think of a form as a simplified version of Splunk's default search interface. Forms can contain multiple text inputs, drop-down menus, and radio buttons that specify the search. You can use forms to hide search terms that a user doesn't need to see, thus simplifying the user interface. For example, consider a helpdesk team that always searches for serial numbers in a specific index on a given host. You can present a simplified interface that searches for a serial number selected from a drop-down list within a timeframe also selected from drop-down lists. You cannot create forms from the Splunk interactive dashboard editing tools. This manual shows how to create and edit the XML code that implements forms.

Build advanced views

Splunk's uses its own Simplified XML syntax to create basic dashboards, views, and forms. Simplified XML is a layer that sits on top of an Advanced XML implementation. Many advanced features in views are based on modules that require Advanced XML syntax. The Splunk module reference lists all modules available for building advanced views. This manual describes how to start out with Simplified XML syntax for dashboards, forms, and views, and then convert them to Advanced XML syntax to implement the more advanced features. It discusses some of the most commonly used modules with examples.

Customize Splunk Web

There are many ways to customize views in Splunk Web. This manual discusses: Customizing the Splunk Web login screen Embedding Splunk dashboard elements into a Web application using IFrame Customizing event display using HTML and JavaScript Using CSS to customize the look of a view or app Localizing text using GetText technology
2

The Splunk Developer Portal provides additional information on extending and creating Splunk modules.

Build apps
A Splunk app is a collection of configurations, objects, and knowledge built within Splunk's app framework. A user installs an app either from a file or directly from Splunkbase (assuming the app has been made available from Splunkbase by the app author). Splunk Web provides App Builder, which you can use to create apps that are based on Splunk app templates. This manual walks you through creating an app using App Builder. It also shows you how to prepare your app for uploading to Splunkbase. Splunk also provides SDKs which you can use to create apps in third party software. Refer to Overview of the Splunk SDKs at the Splunk Developer Portal for information on creating apps using the Splunk SDKs.

Build scripted inputs

You can use scripts to feed data to Splunk for indexing, or to prepare data from a non-standard source so Splunk can properly parse events and extract fields. This manual shows how you can set up and write reliable scripts to input data.

Extend Splunk using the REST API and Splunk SDKs

Splunk provides a REST API that provides access to Splunk from other applications. Any application that can make an HTTP request can configure and manage a Splunk instance, and also create and run searches and access the results returned. Splunk provides various SDKs that use the REST API for access to a Splunk instance. This allows developers access to a Splunk instance using a programming language familiar to them. Refer to Overview of the Splunk SDKs at the Splunk Developer Portal for details on using the Splunk SDKs. The Splunk REST API Reference lists all publicly available endpoints with examples of return values. It also contains examples and conceptual information to help you get started.

Build dashboards
Dashboards: An introduction
A dashboard is a view containing one or more panels that display visualizations of data, such as tables, charts, and graphs. Dashboard panels typically retrieve data from an inline search or a saved search. Dashboards live within apps, which means you can set permissions on a dashboard the same way you can with a saved search, event type, or other object. Once you build a dashboard you can navigate directly to it. For example,
http://localhost:8000/en-US/<app>/<app_name>/<dashboard_name>

Why build a dashboard?

Dashboards are useful for customizing the display of data to a user. You can use dashboards to highlight interesting and useful aspects of your data, link to important searches, and display common reports. For example, you can create a console for network operations console that provides an overview of the entire network, highlights which machines are down, and sends notifications of firewall violations.

How to build a dashboard

A dashboard contains panels organized by rows. Each row can contain one, two, or three panels. Each panel contains a search and a visual summary of that search. Splunk provides tooling that lets you interactively create and edit basic dashboards without having to write a single line of XML code upon which the dashboard is based. Use the Splunk Dashboard Editor to create a dashboard and layout its panels. Use the Search Editor to specify the search for each panel. Use the Visualization Editor to modify how to display the data in a panel. "Create and edit simple dashboards" and "Edit dashboard panel visualizations", both in the Splunk User manual, describe how to interactively create a dashboard.

Searches and dashboards Panels within a dashboard are based on searches and reports. Much of the work in building a dashboard is designing searches and reports that highlight interesting data for your users. You can specify a saved search or an inline search for a panel. If you specify a saved search, Splunk uses the most recent results from that search. If you set up a search to run on a schedule, the panel displays cached results form the search. Use saved searches if you have many long running searches or you expect many users to use the dashboard simultaneously. Use an inline search to display results in real time. You specify an inline searches directly in the implementation of a panel. To learn more about using saved searches in dashboards, read the next section: Saved searches and dashboards. Create and edit dashboards using Simplified XML Often you need to edit the underlying Simplified XML to go beyond the basic dashboards created with the editing tools. Splunk provides an XML editor to help you edit the underlying XML. You can also use any XML editor of your choice. Here are a few reasons you may want to go beyond basic dashboard implementation to edit the underlying Simplified XML: Specify color values for Single Values Customize the appearance of charts, tables, lists, and other visualizations Add radio buttons, drop-down menus, and other UI items You can also create a dashboard from scratch, coding the implementation using Simplified XML. Panels available for dashboards With Simplified XML, you can specify the type of visualization to display in a panel. The visualizations available include the following: Charts Tables Lists Single button
5

 Events HTML The panel reference lists all visualizations plus includes examples of the underlying Simplified XML. Advanced XML Most of the documentation in this manual describes creating and editing dashboards using Simplified XML. Simplified XML sits on top of Splunk's Advanced XML implementation. Complex dashboards and apps might need to leverage functionality only available from Advanced XML. For example, if you want to create a single search that is used by all panels in a dashboard, you have to implement the dashboard in Advanced XML. You can always convert Simplified XML to Advanced XML. However, you cannot later go back to Simplified XML. Splunk recommends that you start advanced projects in Simplified XML, and then convert them later to Advanced XML to add the more complex features. "Introduction to advanced views" in this manual provides details on editing Advanced XML. For example, if you want to create a single search for a whole dashboard, you can implement postProcess search in Advanced XML, as described in How to use one search for a whole dashboard. To convert Simplified XML to Advanced XML use the showsource URI:
http://localhost:8000/en-US/app/<app_name>/<dashboard_name>?showsource=true

Saved searches and dashboards

Before building a dashboard, you may want to create some saved searches. Familiarize yourself with Splunk's search language, create some searches that highlight the important aspects of your data, and then integrate them into dashboards. Dashboards allow you to then visualize data returned from searches in the form of charts, graphs and links. If you are creating Dashboards with Splunk's Dashboard Editor tools, you can run a search to see the results before you save it to the panel you are editing.

Resources for creating searches

If you've never worked with Splunk's search language before, read the User Manual section "Search and investigate." Create searches to highlight the most relevant aspects of your data and support your user's goals. The Search Reference Manual provides additional information on searching with Splunk, including a section on "Best practices", a "Search command cheat sheet", and a complete "Reference to Splunk search commands."

Saved searches and permissions

You can save searches a number of ways: Splunk Web Splunk Manager Search Editor (for saving inline searches using Splunk's Dashboard Editor tools) savedsearches.conf in your app or user directory After saving a search, make sure permissions for the search allow access by users of the dashboard. You can specify the following for a search: Private Only you have access to the search Available in an app The search is available only from the app in which it was created Available in all apps' Essentially, the search is public. You can also specify Read and Write permissions, based on user roles. Save searches from Splunk Web When saving the search from Splunk Web, specify permissions for the search. You can keep the search private or share the search with other users of the app.

Save searches from Splunk Manager When creating searches with Splunk Manager, by default the search is private. After creating the search, in Splunk Manager, edit the permissions so users accessing your dashboard can run the search. 1. Select Manager > Searches and reports > New. 2. In the Add new screen, create your search and select Save. 3. In the list of searches, find your newly created search and select Permissions. 4. Specify the following: Specify: Private Available in the app in which it was created Available in all apps Also specify Read and Write permissions for user roles.

5. Click Save.

Save searches from the Search Editor "Create and edit simple dashboards" in the Splunk User Manual describes how to add panels and searches to a dashboard. You can select either a saved search or an inline search for a panel in a dashboard. If you select an inline search, edit permissions for the dashboard to set permissions for the search. See "Change dashboard permissions" in the User Manual for details. Saved searches configuration file When you save a search, Splunk writes information about the search to the savedsearches.conf file. For private searches, Splunk places savedsearches.conf in your user directory:
$SPLUNK_HOME/etc/users/<user_name>/search/local/savedsearches.conf

For searches saved to an app, Splunk places savedsearches.conf in the following app directory:
$SPLUNK_HOME/etc/apps/<app_name>/local/savedsearches.conf)

Step 1: Create a dashboard

There are several ways to create a Splunk dashboard: Use the Splunk Dashboard Editor to interactively create a dashboard (recommended) Use the Splunk Manager to create a dashboard from a new view Use the Splunk Manager to clone an existing dashboard which you can then modify Create a dashboard from an XML file All three of these options leverage Splunk's Simplified XML. Once you create a dashboard, you can always edit the Simplified XML upon which the dashboard is based.
9

Dashboard owners and permissions

Splunk dashboards are either private to a user, available to users of an app, or available to all users. Splunk places private dashboards in the following location:
$SPLUNK_HOME/etc/users/<user>/<app>/local/data/ui/views/<dashboard_name.xml>

Splunk places dashboards available to users of an app (or available to all users) in the following location:
$SPLUNK_HOME/etc/<app>/local/data/ui/views/<dashboard_name.xml>

You can change the read and write permissions to a dashboard for users, based on their Splunk user roles.

Splunk Dashboard Editor

Use the Splunk Dashboard Editor to interactively create and edit dashboards. From the Dashboard Editor you add panels, create and edit searches for each panel, modify the visualizations representing the returned data, and specify permissions for the dashboard. When using the Dashboard Editor, you do not have to edit any XML code. However, to enhance the dashboard you can always edit the Simplified XML upon which the dashboard is based. To read more about the Dashboard Editor, see "Create and edit simple dashboards" and "Edit dashboard visualizations", both in the User Manual.

Use Splunk Manager to create a dashboard

You can create a dashboard directly from Splunk Manager. 1. Go to Manager > User interface > Views. 2. Click New and specify the following: Destination app Select an app from the dropdown list of all available apps in your Splunk instance.

10

 View name Specify a name for the dashboard. The name you specify becomes a node in the path to the dashboard. Only alphanumeric characters and '-' and '_' can be used. View XML Specify the Simplified XML to create your dashboard. The following is the minimal XML to create a blank dashboard:

<?xml version='1.0' encoding='utf-8'?> <dashboard> <label>Minimal Dashboard</label> </dashboard>

Click Save. 3. (Optional) Modify permissions. By default, the dashboard you create from Splunk Manager is private. In the Views page of Splunk manager, click Permissions for your dashboard to specify an app (or all apps) for the dashboard and to set permissions for users of the dashboard.

Create a dashboard from an XML file

You can create dashboards directly in an XML file and place the file in the appropriate directory in your Splunk installation. Use Simplified XML as described in this chapter. See "Dashboard owner and permissions" in this manual for the location of source dashboard files. After copying the dashboard file to the appropriate directory, refresh Splunk as follows: Go to the following URL and click EAI object refresh. Then refresh the app page from which your dashboard is available. The new dashboard then appears from the Dashboard & Views menu.
http://<Splunk Host>:<Splunk User Port>/info

OR Restart Splunk

11

Splunk's Simplified XML syntax

Splunk's Simplified XML syntax allows you to create basic dashboards. The following sections of this chapter walk you through the steps of developing a dashboard using Simplified XML. However, here are some of the basics of Simplified XML: <dashboard> is the base tag of a dashboard. XML files implementing dashboards are wrapped in these tags. Use the refresh attribute to set how frequently, in seconds, to refresh the dashboard. For example, <dashboard refresh="30"> sets the refresh rate to 30 seconds. <label> is a child tag of <dashboard>. It specifies the display name of the dashboard. Dashboards present panels in rows, designated by the <row> tag. Each row can contain up to three panels. Each panel is a visualization of data returned by the panel's search. Here are common visualizations for panels:
<event>: <table>: <chart>:

Displays a list of events. Displays data in a table. Displays returned data in a chart. <option> tags define the type and layout of the chart. Child tags to a panel include:
<searchName>: specifies a saved search. <searchString>: specifies an inline search specific to that panel. <title>: Display name for the panel. <earliestTime>, <latestTime>: specifies the time range for the search.

<option> tags to a panel that define the type and properties of the panel visualization. For example:
<option name="charting.chart"></option>

defines the type of

visualization, such as pie or radialGuage <option name="count"></option> defines the number of rows to display.

12

See the Splunk Panel Reference for details on specifying visualizations for panels. Use HTML entities for special characters Simplified XML does not support the following five characters. Use HTML entities to display these characters: Character " ' < > & HTML Entitiy
&quot; &apos; &lt; &gt; &amp;

Step 2: Add rows

Dashboards contain rows. Each row can contain up to three panels. Each panel typically contains a single search and displays a visualization of that search. However, you can group two or more panel visualizations into a single column within a row. This step shows how to add rows and also how to add rows that contain panel groups. "Step 3: Add Panels" shows how to add panels to the rows.

Add rows to a dashboard

Add two rows to a dashboard using the <row> tag. Rows can accommodate up to three panels.

<dashboard> <label>My dashboard</label> <row> . . . . . . </row> <row> . . .

13

. . . </row> </dashboard>

Create a panel group for a row

Group panels together within a row by adding a grouping attribute to the <row> tag. The following example groups two panels into a single column:

<dashboard> <label>My dashboard</label> <row grouping="2"> . . . . . . </row> </dashboard>

You can group panels into columns on the left or right sides within a single row. The following example creates a single row of panels, separated into two columns, with 3 panels grouped in the left column and 2 panels grouped in the right column:

<dashboard> <label>My dashboard</label> <row grouping="3,2"> . . . . . . </row> </dashboard>

Note: Panel groups affect the Splunk Dashboard Editor. The Dashboard Editor cannot add or edit panels for a dashboard containing grouped panels. All additional edits must be done in the underlying XML code.

Step 3: Add panels

Each row in a dashboard can contain up to three panels. Each panel contains a search (a saved search or an inline search specific to that panel) and a visualization of the results returned from that search. There's no limit to how many rows you can have in a dashboard. The visualization can be any of the following:
14

 A table An event listing A list A chart A single value A gauge representing a single value Panels can also display information coded for HTML. These panels do not have searches and visualizations associated with them. See Visualization Reference, available in the Splunk User Manual, for details on tables, charts, single values, and gauges that you can use in a panel. See Panel Reference for Simplified XML for details on implementation of various panels.

Add panels to rows

To add a panel to a row in a dashboard, add the tags defining the type of panel. The following example adds three panels: an event listing, a table, and a chart.

<dashboard> <label>My dashboard</label> <row> <event> . . . </event> <table> . . . </table> <chart> . . . </chart> </row> </dashboard>

Configure panels
Configure panels by specifying the following: Search for the panel Properties available to all panels Properties specific to types of panels

15

Add a search Searches can be a saved search or an inline search specific to that panel. Saved searches run on the schedule for the search. Inline searches run when the panel loads. Saved search Use the <searchName> tag to specify a saved search. Saved searches must be shared with all users and roles who access the dashboard. Any saved search for a panel must contain an entry in savedsearches.conf in the app's default or local directory, or the search must be shared globally with all apps. Inline search Use the <searchString> tag to specify an inline search. Inline searches run every time the dashboard is accessed. If you have a long running search, or there are many users accessing a dashboard, an inline search may create a high load on your Splunk instance. For inline searches you can optionally specify a time range for the search. The following example shows a dashboard with two panels showing a saved search and an inline search. The inline search displays results from the last week. "Build a real-time dashboard" shows how to build a search with a real-time dashboard.

<dashboard> <label>My dashboard</label> <row> <chart> <searchName>My saved report</searchName> </chart> <chart> <searchString>host=production | top users</searchString> <earliestTime>-7d</earliestTime> <latestTime>now</latestTime> </chart> </row> </dashboard>

Properties available to all panels Simplified XML provides a set of tags that define properties that can be applied to all panels. The following table summarizes some of these tags.

16

Tag
<title>title</title> <fields>comma separated list of fields</fields> <earliestTime>Splunk time format</earliestTime>

Description
Add a title to your panel, such as

Failed logins. This title display at the top of the panel.

Restrict your search results to specific fields. Restrict your search results to a specific time window, starting with the earliestTime. Specify "rt" to enable real-time searches. Restrict your search results to a specific time window, ending with the latestTime. Specify "rt" to enable real-time searches.

<latestTime>Splunk time format</latestTime>

The following example shows a panel with a chart visualization, a title, and an inline search. The search results are restricted to a 5 hour window and to three fields:

<dashboard> <label>My dashboard</label> <row> <chart> <title>Top users, five hours ago</title> <searchString>host=production | top users</searchString> <earliestTime>-10h</earliestTime> <latestTime>-5h</latestTime> <fields>host,ip,username</fields> </chart> </row> </dashboard>

Properties specific to types of panels Each type of panels has specific options that are only available to that panel. <option> tags define those properties, using the name attribute. For example, if you specify a panel with a table visualization, use the <option> tag to specify how many rows to display and whether to display row numbers. The following example specifies options for a <table> panel.

<dashboard> <label>My dashboard</label>

17

<row> <table> <searchName>Errors in the last 24 hours</searchName> <title>Errors in the last 24 hours</title> <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> </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> <chart> <searchString> sourcetype=access_* method=GET | timechart count by categoryId | fields _time BOUQUETS FLOWERS </searchString> <title>Views by product category, past week (Stacked)</title> <earliestTime>-7d</earliestTime> <latestTime>now</latestTime> <option name="charting.axisTitleX.text">Views</option> <option name="charting.axisTitleY.text">Date</option> <option name="charting.chart">column</option> </chart> </row> </dashboard>

Add a chart
Splunk provides a variety of chart visualizations, such as column, line, area, scatter, and pie charts. These visualizations require transforming searches (searches that use reporting commands) whose results involve one or more series. For more information on the chart visualizations available, see "Charts" in the Splunk User Manual.

18

Configure the chart panel

The following example displays information from an inline search as a column chart. The columns in the chart "stack" the data returned from the search.

<dashboard> <label>My dashboard</label> <row> <chart> <searchString> sourcetype=access_* method=GET | timechart count by categoryId | fields _time BOUQUETS FLOWERS </searchString> <title>Views by product category, past week (Stacked)</title> <earliestTime>-7d</earliestTime> <latestTime>now</latestTime> <option name="charting.chart">column</option> <option name="charting.axisTitleX.text">Views</option> <option name="charting.axisTitleY.text">Date</option> </chart> </row> </dashboard>

The inline search is based on a version of the Splunk tutorial. The search for this panel is a transforming search, using reporting commands. The <title> tag displays a title for the panel. The panel also restricts the time range for results reported. The three <option> tags specify the type of chart to display, and labels for the X and Y axes.

Set chart specific options For basic configuration of charts, refer to the "Chart panel entry" in the Panel reference for Simplified XML. There are many additional configurations you can make to customize the appearance of a chart. Refer to the Splunk Custom Chart Configuration Reference for details. Custom configuration options include: "Chart and legend properties"
19

 "Axes and grid line properties" "Tooltip properties" "Font, color, brush, shape, and related palette properties" "Layout and data table properties" "textBlock, layoutSprite, and sprite properties"

Add a table
The table panel displays search results in a sortable table. You can display results in a table from just about any search, but the most interesting tables are generated from searches that include transform operations. For example, a search that uses reporting commands such as stats, chart, timechart, top, or rare. Any fields you want to display in your table should be explicitly added to your search. For more information on table visualizations, refer to "Tables" in the Splunk Visualization Reference.

Configure the table panel

The following example displays information on processes with high CPU usage. It specifies a custom row count of 15, removes the display of row numbers, and includes a heat map overlay highlighting extreme values.

<dashboard> <label>My dashboard</label> <row> <table> <searchString> index="_internal" source="*metrics.log" group="pipeline" | chart sum(cpu_seconds) over processor | sort -sum(cpu_seconds) | rename sum(cpu_seconds) as "Total CPU Seconds" </searchString> <title>High CPU processors</title> <earliestTime>-60m</earliestTime> <latestTime>now</latestTime> <option name="count">15</option> <option name="dataOverlayMode">heatmap</option> <option name="displayRowNumbers">false</option> <option name="showPager">true</option> </table>

20

</row> </dashboard>

For basic configuration of charts, refer to the "Table panel entry" in the Panel reference for Simplified XML.

Add a list
The list panel displays search results in a list. It's particularly useful if you have a search that generates a set of fields you want to link to.

Configure the list panel

The following example creates a list of links for the to field in the Top recipients search. The <list> tag specifies a list visualization. You must also specify the field to generate labels for the list and the field to populate the values. Use the <option name="labelField"> to create a label for each item in the list and <option name="valueField"> to generate values for each item.

<dashboard> <label>My dashboard</label> <row> <list> <searchName>Top recipients</searchName> <option name="labelField">to</option> <option name="valueField">to</option> </list> </row> </dashboard>

This example references a saved search called Top recipients. Make sure this saved search is shared with all users and roles who access this dashboard. Any saved search referenced in searchName must exist in savedsearches.conf in the App's default or local directory or be set as global. Configure list specific options You can set other configuration options that are only available for list panels, such as the sort direction of the list and the search and view the list links to. For example, the following example sets the initial sort in descending order and links to another view from which to launch the search:

<dashboard> <label>My dashboard</label>

21

<row> <list> <title>Top users</title> <searchString>host=production | top users</searchString> <option name="labelField">users</option> <option name="valueField">users</option> <option name="initialSortDir">desc</option> <option name="labelFieldTarget">My custom search view</option> </list> </row> </dashboard>

For basic configuration of lists, refer to the "List panel entry" in the Panel reference for Simplified XML.

Add HTML
The HTML panel displays inline HTML. Splunk display the contents between the HTML tags according to any specified HTML formatting. The HTML panel is a great way to add documentation, links, images, and other Web content to your dashboard. Relative link references are relative to the current view location.

Configure the HTML panel

Here's an example of an HTML panel. To access the saved searches, the href attribute to the anchor tag uses the special Splunk locator, @go?s=.

<dashboard> <label>My dashboard</label> <row> <html> <p>This is an <i><b>HTML panel</b></i> providing links to saved searches.</p> <ul> <li><a href = "@go?s=Errors in the last 24 hours">Errors in the last 24 hours</a></li> <li><a href = "@go?s=My second search">Errors in the last hour</a></li> <li><a href = "@go?s=My second search">Splunk errors last 24 hours</a></li> </ul> </html> </row> </dashboard>

22

The HTML panel does not use any of the other general panel options and there are no specific options to set for HTML. All the configuration goes into the HTML itself. For basic configuration of HTML panels, refer to the "HTML panel entry in the Panel reference for Simplified XML.

Add a single value and gauges

The single value panel displays a single value from search data as text on button. If you base the visualization on a real-time search that returns a single value, the number displayed changes as the search interprets incoming data. You can also specify single values as gauges, as described below. Note: The single value visualization is best used with a search that returns a single value. If your search specifies multiple values, the single value visualization takes its number from the first row or first column of the search data. You can change the color of the button depending on the value of the number it displays, creating a green/yellow/red visualization.

Configure a single value panel

The following example shows how to add a single value to a dashboard, recording the total number of logging events. It also displays text before and after the displayed value.

<dashboard> <label>My dashboard</label> <row> <single> <searchString> 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 </searchString> <title>Log events</title> <earliestTime>-1d</earliestTime> <latestTime>now</latestTime> <option name="afterLabel">total logging events</option> <option name="beforeLabel">Found</option>

23

</single> </row> </dashboard>

Set the color of the panel You can change the background color of the single value panel depending on the values returned from the search. To change colors on your single results panel do the following: Set up your search to use the rangemap command. Add the classField option, setting the value to range. Here is the same single value panel in the previous example, but setting color ranges for green, yellow, and red.

<dashboard> <label>My dashboard</label> <row> <single> <searchString> 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 </searchString> <title>Log events</title> <earliestTime>-1d</earliestTime> <latestTime>now</latestTime> <option name="classField">range</option> <option name="afterLabel">total logging events</option> <option name="beforeLabel">Found</option> </single> </row> </dashboard>

Configure button specific options For basic configuration of single value panels, refer to the "Single value panel entry" in the Panel reference for Simplified XML.

Panels displaying gauges

Gauge visualizations map a single numerical value against a range of colors that may have particular business meaning or logic. As the value changes over time,
24

the gauge marker changes position within this range. Gauges provide a dynamic visualization for real-time searches the fluctuating returned values cause the gauge marker to visibly bounce back and forth within the range. Splunk provides three types of gauge visualizations: radial, filler, and marker. For more information, see "Gauges" in the Splunk Visualizaton Reference. Gauges are a type of chart visualization. You use the <option> tag to specify the type of gauge. Gauges by default are displayed with a rich set of graphics (shiny). You can specify a minimal version of a gauge, which uses less graphics. The following example illustrates all three gauges in a row on a dashboard. The first gauge is a radial gauge that displays minimal graphics. The others use the default shiny graphics. The gauges in this example use the same search for logging events that was used for a single value panel above. Typically, you use a real-time search for gauges.

<dashboard> <label>Gauges</label> <row> <chart> <option name="charting.chart">radialGauge</option> <option name="charting.chart.style">minimal</option> <option name="charting.chart.rangeValues">[0,100,300,500]</option> <option name="charting.gaugeColors">[0x84e900,0xffe800,0xbf3030]</option> <searchString> 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 </searchString> <title>Splunk server log events</title> <earliestTime>-1d</earliestTime> <latestTime>now</latestTime> </chart> <chart> <option name="charting.chart">fillerGauge</option> <option name="charting.chart.rangeValues">[0,100,300,500]</option> <option name="charting.gaugeColors">[0x84e900,0xffe800,0xbf3030]</option> <searchString> 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

25

</searchString> <title>Splunk server log events</title> <earliestTime>-1d</earliestTime> <latestTime>now</latestTime> </chart> <chart> <option name="charting.chart">markerGauge</option> <option name="charting.chart.rangeValues">[0,100,300,500]</option> <option name="charting.gaugeColors">[0x84e900,0xffe800,0xbf3030]</option> <searchString> 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 </searchString> <title>Splunk server log events</title> <earliestTime>-1d</earliestTime> <latestTime>now</latestTime> </chart> </row> </dashboard>

Add an event listing

An event visualization is essentially a raw list of events. You can get event visualizations from any search that does not include a transform operation. Transform operations use reporting commands such as stats, chart, timechart, top, or rare.

Configure the event listing panel

The following example displays access errors as a list of events. The search for the panel is from a saved search. This panel specifies the following: Display 15 rows of returned data Do not include the row numbers Include a maximum of 10 lines of data for each event Wrap long lines of returned data

<dashboard> <label>Event Listing Dashboard</label> <row>

26

<event> <searchName>Errors in the last 24 hours</searchName> <title>Errors in the last 24 hours</title> <option name="count">15</option> <option name="displayRowNumbers">false</option> <option name="maxLines">10</option> <option name="softWrap">true</option> </event> </row> </dashboard>

Configure event listing specific options For basic configuration of event listings, refer to the "Event panel entry" in the Panel reference for Simplified XML.

Build a real-time dashboard

You can build a real-time dashboard using the Splunk Dashboard Editor, coding the dashboard using Simplified XML, or using Splunk's Advanced XML. This topic provides an example of creating a real-time dashboard using Simplified XML. For information on building a dashboard using Advanced XML, see "How to build a real-time dashboard" in the Advanced Web customization section of this manual.

Enable real-time searching

Use the <earliestTime> and <latestTime> params to enable real-time searching. 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 that you need to care about</title> <searchName>Errors in the last 24 hours</searchName> <fields>host, source, errorNumber</fields> <earliestTime>rt</earliestTime> <latestTime>rt</latestTime> </table>

You can also set a window for your real-time dashboard. For example, if you want to show real-time events but only from the last 5 minutes.
27

<table> <title>Look here for errors that you need to care about</title> <searchName>Errors in the last 24 hours</searchName> <fields>host, source, errorNumber</fields> <earliestTime>rt-5m</earliestTime> <latestTime>rt</latestTime> </table>

For more information on setting a search window, see "The real-time search topic" in the User Manual.

Dashboard example
This dashboard example contains several rows illustrating various panels you can create with SimplifiedXML. Note: Because this dashboard illustrates grouping of panels, you cannot edit this dashboard in the Splunk Dashboard Editor.

First row
HTML panel Displays a basic message and lists a few links to saved searches. Table panel Displays high CPU usage in the past hour, specifying 10 rows of data, no row numbers, and overlaying a heat map to highlight high values. Event panel Displays results of a saved search as a listing of events. Displays 5 rows of results at a time, and wrapping of events is off.

<dashboard> <label>Dashboard example</label> <row> <html> <p>This is an <i><b>HTML panel</b></i> providing links to saved searches.</p> <ul> <li><a href = "@go?s=Errors in the last 24 hours">Errors in the last 24 hours</a></li> <li><a href = "@go?s=My second search">Errors in the last hour</a></li> <li><a href = "@go?s=My second search">Splunk errors last 24

28

hours</a></li> </ul> </html> <table> <title>High CPU processors in the last hour</title> <searchString> index="_internal" source="*metrics.log" group="pipeline" | chart sum(cpu_seconds) over processor | sort -sum(cpu_seconds) | rename sum(cpu_seconds) as "Total CPU Seconds" </searchString> <earliestTime>-60m</earliestTime> <latestTime>now</latestTime> <option name="count">10</option> <option name="dataOverlayMode">heatmap</option> <option name="displayRowNumbers">false</option> <option name="showPager">true</option> </table> <event> <searchName>Errors in the last 24 hours</searchName> <title>Errors in the last 24 hours</title> <option name="count">5</option> <option name="displayRowNumbers">true</option> <option name="maxLines">10</option> <option name="segmentation">outer</option> <option name="softWrap">false</option> </event> </row> . . .

Second row
Column chart panel Displays a chart as stacked columns, providing labels for the X and Y axes. The inline search is derived from a version of the Splunk tutorial. Pie chart panel Displays the same search as the column chart panel, but as a pie chart.

. . . <row> <chart> <searchString> sourcetype=access_* method=GET | timechart count by categoryId | fields _time BOUQUETS FLOWERS

29

</searchString> <title>Views by product category, past week (Stacked)</title> <earliestTime>-7d</earliestTime> <latestTime>now</latestTime> <option name="charting.axisTitleX.text">Views</option> <option name="charting.axisTitleY.text">Date</option> <option name="charting.chart">column</option> <option name="charting.primaryAxisTitle.text"></option> <option name="charting.secondaryAxisTitle.text"></option> <option name="count">10</option> <option name="displayRowNumbers">true</option> </chart> <chart> <searchString> sourcetype=access_* method=GET | timechart count by categoryId | fields _time BOUQUETS FLOWERS </searchString> <title>Views by product category, past week (Pie Chart)</title> <earliestTime>-7d</earliestTime> <latestTime>now</latestTime> <option name="charting.chart">pie</option> <option name="count">10</option> <option name="displayRowNumbers">true</option> </chart> </row> . . .

Third row
This row illustrates various ways to display single values, and provides an example of a panel grouping. Radial gauge panel Displays a radial gauge for an inline search checking all Splunk server log events. Single value button grouped with a marker gauge chart panel Uses the same search as the radial gauge. Note that specifying colors for a single value differs from the gauge charts.

. . . <row grouping="1,2" > <chart> <searchString> 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 </searchString> <title>Splunk server log events (Radial Gauge)</title> <earliestTime>-1d</earliestTime>

30

<latestTime>now</latestTime> <option name="charting.chart">radialGauge</option> <option name="charting.chart.rangeValues">[0,100,300,500]</option> <option name="charting.gaugeColors">[0x84e900,0xffe800,0xbf3030]</option> </chart> <single> <searchString> 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 </searchString> <title>Log events</title> <earliestTime>-1d</earliestTime> <latestTime>now</latestTime> <option name="classField">range</option> <option name="afterLabel">total logging events</option> <option name="beforeLabel">Found</option> </single> <chart> <searchString> 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 </searchString> <title>Splunk server log events</title> <earliestTime>-1d</earliestTime> <latestTime>now</latestTime> <option name="charting.chart">markerGauge</option> <option name="charting.chart.rangeValues">[0,100,300,500]</option> <option name="charting.gaugeColors">[0x84e900,0xffe800,0xbf3030]</option> </chart> </row> </dashboard>

31

Build forms
Forms: An introduction
A form is a Splunk view 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. For example, consider a help desk support team that searches on a serial number and user name for every support case. You can create a form search that shows a dropdown list for a serial number and a text box for a user name. A support engineer can then easily search for the relevant data for a support case. Forms live within apps, which means you can set permissions on a form the same way you can with a saved search, event type, or other object. Once you build a form you can navigate directly to it. For example,
http://localhost:8000/en-US/<app>/<app_name>/<form_name>

This section describes the various types of forms and how to build a form search. It includes basic examples that you can use to get started. You can find additional examples in the Sample app available from your Splunk installation and the UI Examples app available from [Splunkbase].

Form owners and permissions

Forms are either private to a user, available to users of an app, or available to all users. In this respect, they are much like dashboards. Splunk places private forms in the following location:
$SPLUNK_HOME/etc/users/<user>/<app>/local/data/ui/views/<form_name.xml>

Splunk places forms available to users of an app (or available to all users) in the following location:
$SPLUNK_HOME/etc/<app>/local/data/ui/views/<form_name.xml>

32

You can change the read and write permissions to a form for users, based on their Splunk user roles.

About form searches

Form searches are built on fields or other identifiable parts of your data. Typically, you first build a search that fits your data and use case. Then, identify the parts of this search that can be specified by the user. Finally, build a form search view (or embed your form search in a dashboard). Form searches use tokens for search fields that accept user data. When a user types in a search term of a form, the token is replaced with the user input. For example, the following form search provides a textbox to specify the value for series in a search. Here is the underlying search for this form:
index=_internal source=*metrics.log group="per_sourcetype_thruput" series=$series$ | fields eps, kb, kbps

Here is the Simplified XML implementing the form search. The token $series$ represents the text entered by the user in the text box. The form also includes the default Splunk TimePicker to allow the user to select a time range for the search.

<form> <label>Sample form</label>

<searchTemplate> index=_internal source=*metrics.log group="per_sourcetype_thruput"

33

series=$series$ | fields eps, kb, kbps </searchTemplate> <fieldset>

<input type="text" token="series"> <label>sourcetype</label> <default></default> <seed>splunkd</seed> <suffix>*</suffix> </input>

<input type="time" /> </fieldset> <row>

<table> <option name="showPager">true</option> <option name="count">20</option> </table> </row> </form>

The Splunk sample app contains several example form searches. An example similar to this example, plus two others that contain dynamically populated radio buttons and drop downs. The dynamic form search views present different options in the radio buttons and drop downs depending on your data. Adapt these examples to fit your use case.

Types of form search views

There are three different types of form views: Simple form search The most basic form, a simple form search contains one or more text input boxes. Simple form searches use Splunk's Simplified XML, which is also used to create dashboards described in the
34

previous section. Dynamic form search Form searches contain drop-down lists or radio buttons that display choices created by different searches. The available choices are dynamically populated from these searches. Use Simplified XML to create dynamic form searches. Advanced form search Use Splunk's Advanced XML to build complex form searches. The ExtendedFieldSearch module documentation describes features available in advanced form searches. Splunk recommends that you start with the Simplified XML and move on to the advanced only if there are options you cannot enable. To learn more about building an advanced form search, see the topic How to build an advanced form search. Simplified XML and Advanced XML Most of the documentation in this section describes creating and editing forms using Simplified XML. Simplified XML sits on top of Splunk's Advanced XML implementation. Complex forms might need to leverage functionality only available from Advanced XML. You can always convert Simplified XML to Advanced XML. However, you cannot later go back to Simplified XML. Splunk recommends that you start advanced projects in Simplified XML, and then convert them later to Advanced XML to add the more complex features. "Introduction to advanced views" in this manual provides details on editing Advanced XML. To convert Simplified XML to Advanced XML use the showsource URI:
http://localhost:8000/en-US/app/<app_name>/<dashboard_name>?showsource=true

Use HTML entities for special characters XML does not support the following five characters. Use HTML entities to display these characters: Character " ' HTML Entitiy
&quot; &apos;

35

< > &

&lt; &gt; &amp;

Create a simple form search

You create a simple form search much the same way you create a dashboard, as described in "Create a dashboard" earlier in this manual. You can do any of the following: Create a dashboard using the Splunk Dashboard Editor, then modify the XML to create a form search. Use the Splunk Manager to create a form search from a new view. Clone an existing form search and modify it. Create a form search from an XML file. Refer to "Create a dashboard from an XML file" for information on how to create a form search directly from an XML file. The process is the same. This topic first shows how to create and modify a dashboard to create a form search. It then shows how to create a form search using Splunk Manager. Subsequent topics show various steps for creating a form search using Simplified XML.

Modify a dashboard to create a form search

"Create and edit simple dashboards" in the Splunk User Manual details how to create dashboards using the Splunk Dashboard Editor. This topic walks you through creating a basic dashboard that you later convert to a form search. 1. In Splunk Web Search app, go to Dashboards & Views > Create dashboard. Provide an ID and Name for the dashboard. 2. Enable editing and click New panel. Specify the following: Title: My Form Search Search command: Inline search string Earliest time: -7d Latest time: now Search:
36

index=_internal source=*metrics.log group="per_sourcetype_thruput" | fields eps, kb, kbps

3. Click Save to view the new dashboard. The dashboard lists the results of the search. Use this search as the base result of a form search. This dashboard has a hardcoded search and a hardcoded time range for results. In the following steps, you convert the dashboard to a form search that uses the specified search as the base of a form search, with the user adding an additional search term to the search query. The user can also modify the time range by adding a TimePicker to the search. 4. Enable editing for dashboard and click Edit XML. This is the generated Simplified XML for the dashboard:

<dashboard> <label>Dashboard to convert to Form Search</label> <row> <table> <searchString> index=_internal source=*metrics.log group="per_sourcetype_thruput" | fields eps, kb, kbps </searchString> <title></title> <earliestTime>-7d</earliestTime> <latestTime>now</latestTime> </table> </row> </dashboard> 5. Change the <dashboard> tags to <form> tags. Move the search from a <searchString> element in the dashboard to a <searchTemplate> element

in the

form.

<form> <label>Dashboard to convert to Form Search</label> <searchTemplate> index=_internal source=*metrics.log group="per_sourcetype_thruput" | fields eps, kb, kbps </searchTemplate> <row> <table>

37

<title></title> <earliestTime>-7d</earliestTime> <latestTime>now</latestTime> </table> </row> </form>

6. Modify the search to include a series field token ($series$). Add a text box for the user to specify the series field. The field set in this example specifies a label for the text box, a seed value for the text box, and a suffix value to append to each user-supplied value.

<form> <label>Dashboard to convert to Form Search</label> <searchTemplate> index=_internal source=*metrics.log group="per_sourcetype_thruput" series=$series$ | fields eps, kb, kbps </searchTemplate> <fieldset> <input type="text" token="series"> <label>sourcetype</label> <default></default> <seed>splunkd</seed> <suffix>*</suffix> </input> </fieldset> <row> <table> <title></title> <earliestTime>-7d</earliestTime> <latestTime>now</latestTime> </table> </row> </form>

7. Remove the hardcoded time fields from the <table> element, and add the default Splunk TimePicker to the field set. Also, add the pager and count options to the table.

<form> <label>Dashboard to convert to Form Search</label> <searchTemplate> index=_internal source=*metrics.log group="per_sourcetype_thruput" series=$series$ | fields eps, kb, kbps </searchTemplate>

38

<fieldset> <input type="text" token="series"> <label>sourcetype</label> <default></default> <seed>splunkd</seed> <suffix>*</suffix> </input> <input type="time" /> </fieldset> <row> <table> <option name="showPager">true</option> <option name="count">20</option> </table> </row> </form>

Use Splunk Manager to create a form

This topic shows how to create a form search directly from a new view created in Splunk Manager. Subsequent topics illustrate the various steps in creating the form search. 1. Go to Manager > User interface > Views. 2. Click New and specify the following: Destination app Select an app from the dropdown list of all available apps in your Splunk instance. View name Specify a name for the dashboard. The name you specify becomes a node in the path to the dashboard. Only alphanumeric characters and '-' and '_' can be used. View XML Specify the Simplified XML to create your dashboard. The following is the minimal XML to create a form search. It specifies a sample search command with a token, uses a text field to specify values for the token, and displays the results in a table:

<form> <label>Sample form search</label> <searchTemplate>index=sample from="$from$"</searchTemplate> <fieldset> <input type="text" token="from" />

39

</fieldset> <row> <event> <title>Results</title> <option name="count">50</option> </event> </row> </form>

Click Save. 3. (Optional) Modify permissions. By default, the form you create from Splunk Manager is private. In the Views page of Splunk manager, click Permissions for your form to specify an app (or all apps) for the dashboard and to set permissions for users of the dashboard.

Form tags
Here is a description of the tags in the previous example that defines a form search. Tag
<form> <label> <fieldset> Required to define a form Optional, to display a title for the form. Required, defines the user input (<input. . .>) for the form. The example above uses a text box.

Description

Required, defines the visualization for the returned values. This example <row><event>. . . uses an event listing. You can specify any of the panel visualizations, as described in "Adding panels to a dashboard".

Define inputs to a form

The <fieldset> tag defines form inputs. This section describes how to modify elements within the <fieldset> tag to customize inputs.

<form> <label>Sample form search</label> <searchTemplate>index=sample from="$from$"</searchTemplate>

<fieldset> <input type="text" token="from" />

40

</fieldset> <row> <event> <title>Results</title> <option name="count">50</option> </event> </row> </form>

Specify a TimePicker with a default time range

If you do not specify a time range, the time range defaults to all time. You can add a TimePicker (a time range dropdown) with a default time setting. Set the default time range to any of the strings availalble from the time range dropdown. This example adds a time picker and sets the default time range to the last 30 days:

. . . <input type="time"> <default>Last 30 days</default> </input> . . .

Add a label
Use the <label> tag to add a descriptive label to the input. This example adds Enter a user name before a text input:

. . . <input type="text" token="username"> <label>Enter a user name</label> </input> . . .

Set a default search term

If the user does not fill in the text box when submitting values, the token defaults to an empty string. To set a default value for the token in a search, use the <default> tag. This example sets Cosmo as the default value for the token specifying a username:

41

. . . <input type="text" token="username"> <default>Cosmo</default> </input> . . .

Add a prefix or suffix

A search query often requires additional suffixes or prefixes. Use the <prefix> and <suffix> tags to add additional terms to a search query. The <prefix> and <suffix> tags are only used when a user enters a search in the text box. Set a prefix on the default value:

. . . <input type="text" token="username"> <prefix>username=</prefix> </input> . . .

Quote the default value:

. . . <input type="text" token="username"> <prefix>username="</prefix> <suffix>"</suffix> </input> . . .

Populate a form with data

Use the <seed> tag to populate a form with known data. This example populates a form with the username Jack:

. . . <input type="text" token="username"> <seed>Jack</seed> </input> . . .

Auto-run a form
You can automatically run a form when the page loads. Use the auto-run feature if you have set defaults from which you want your users to see results before specifying their own search.
42

Specify the following attributes to the <fieldset> tag.

autoRun="true" submitButton="false"

Make sure you also include a seed for the search. Setting a default time range is a good idea. Here's an example that runs the specified search on page load:

. . . <fieldset autoRun="true" submitButton="false"> <input token="sourcetype"> <seed>access_combined</seed> </input> <input type="time"> <default>Last 30 days</default> </input> </fieldset> . . .

Display form search results

To display results of a form search, add a row to the form much the same way you add rows to a dashboard. Then select a visualization for the results. You can use some of the same visualizations available for panels in dashboards. This section illustrates using an event listing, a table, and charts.

Display results in an event listing

To display results as a list of events, add a <row> element with an <event> node to your form search. The event listing displays the search results as individual events. The following example displays the last 100 login events over the past seven days for the username entered in the form:

<form> <label>Username</label> <searchTemplate>sourcetype=logins $username$</searchTemplate> <earliestTime>-7d</earliestTime> <latestTime>-0d</latestTime>

43

<fieldset> <input type="text" token="username" /> </fieldset> <row> <event> <option name="count">100</option> </event> </row> </form>

To learn more about event listing, see "Add an event listing" in the Build dashboards section of this manual. Also, refer to the "Event panel" section of the Simplified XML Panel Reference.

Display results in a table

To display results in a table, add a <row> element with a <table> node to your form search. The following example displays results returned by the form search in table. The table contains a pager, specifying 20 rows per page.

<form> <label>Username</label> <searchTemplate>sourcetype=logins $username$ </searchTemplate> <earliestTime>-7d</earliestTime> <latestTime>-0d</latestTime> <fieldset> <input type="text" token="username" /> </fieldset> <row> <table> <title>User logins</title> <option name="showPager">true</option> <option name="count">20</option> </table> </row> </form>

To learn more about displaying results in a table, see "Add a table" in the Build dashboards section of this manual. Also, refer to the "Table panel" section of the Simplified XML Panel Reference.

44

Display results in a chart

To display results in a chart, add a <row> element with a <chart> node to your form search. Use the chart's <option> tags to specify the type of chart and any chart properties. Chart types include bar, column, area, line, pie, scatter, and bubble. Charts require transforming searches (searches that use reporting commands) whose results involve one or more series. For more information on the chart visualizations available, see "Charts" in the Splunk User Manual. The following example creates a form search displaying results in a column chart The search has includes reporting commands (timechart count).

<form> <label>Username</label> <searchTemplate>sourcetype=logins $username$ | timechart count</searchTemplate> <earliestTime>-7d</earliestTime> <latestTime>-0d</latestTime> <fieldset> <input type="text" token="username" /> </fieldset> <row> <chart> <title>User logins, last 7 days</title> <option name="charting.chart">column</option> <option name="charting.primaryAxisTitle.text">User</option> <option name="charting.secondaryAxisTitle.text">Total logins</option> <option name="charting.legend.placement">none</option> </chart> </row> </form>

In this example, Splunk's chart formatting controls specify the axis titles and removes the chart legend (you really don't need a legend when only one series is displayed). The primaryAxisTitle and secondaryAxisTitle elements are similar to the axisTitleX and axisTitleY elements described in the charting controls documentation. For more information see the Custom chart configuration reference chapter in this manual. To learn more about charts, see "Add a chart" in the Build dashboards section of this manual.

45

Create a dynamic form search with radio buttons

You can create a dynamic form search that is populated using radio buttons. You specify a search to populate radio button choices. A user selects a radio button drive the search results.

Dynamic form search example

1. Use a simple form search to get started.

<form> <label>Username</label> <searchTemplate>sourcetype=logins $username$</searchTemplate> <fieldset> <input type="text" token="username" /> </fieldset> <row> <event> <option name="count">100</option> </event> </row> </form>

2. Change the input from a text box to radio buttons. Add a <populatingSearch> to generate the options for the radio buttons

. . . <input type="radio" token="username"> <label>Select Name</label> <populatingSearch fieldForValue="suser" fieldForLabel="suser"> <![CDATA[sourcetype=p4change | rex "user=(?<suser>\w+)@" | stats count by suser]]> </populatingSearch> </input> . . .

3. Display the results in a table. The following is the complete dynamic form search.

<form> <label>Username</label> <searchTemplate>sourcetype=logins $username$</searchTemplate> <fieldset> <input type="radio" token="username"> <label>Select Name</label>

46

<populatingSearch fieldForValue="suser" fieldForLabel="suser"> <![CDATA[sourcetype=p4change | rex "user=(?<suser>\w+)@" | stats count by suser]]> </populatingSearch> </input> </fieldset> <row> <table> <title>Users</title> <option name="showPager">true</option> </table> </row> </form>

Radio button configuration options

There are several configuration options available for <input type="radio">. Tag
<label>label</label> <default>option</default> <prefix>search terms</prefix> <suffix>search terms</suffix> <choice value="value">

Description
A label for the radio buttons. The default option to select. If the default option cannot be found, the first option is selected. Prefix the search query with the specified search terms. Place the specified search terms after the search query. Specify options for radio buttons. Options appear in the order they are defined, and before any options generated by a search specified by <populatingSearch>. A search that generates options for the radio buttons. Requires the attributes fieldForValue and fieldForLabel. fieldForValue is the field extracted from the populatingSearch and

<populatingSearch fieldForLabel="label" fieldForValue="value">

placed in the value of the generated radio button option. fieldForLabel is the field extracted from the populatingSearch and placed in the label of the generated radio buttons.
A saved search that generates options for the radio buttons. Requires the attributes fieldForValue and fieldForLabel. fieldForValue is the field extracted from the populatingSavedSearch and

<populatingSavedSearch fieldForLabel="label" fieldForValue="value">

placed in the value of the generated radio button option. fieldForLabel is the field
47

extracted from the populatingSavedSearch and placed in the label of the generated radio buttons.
<earliestTime>Splunk time format</earliestTime> <latestTime>Splunk time format</latestTime> Restrict your search results to a specific time window, starting with the earliestTime. Specify "rt" to enable real-time searches. Restrict your search results to a specific time window, ending with the latestTime. Specify "rt" to enable real-time searches.

Create a dynamic form search using drop-downs

You can create a dynamic form search that is populated using a dropdown list. You specify a search to populate the choice in the list. A user selects from the list to drive the search results.

Dynamic form search example

1. Use a simple form search to get started.

<form> <label>Username</label> <searchTemplate>sourcetype=logins $username$</searchTemplate> <fieldset> <input type="text" token="username" /> </fieldset> <row> <event> <option name="count">100</option> </event> </row> </form>

2. Change the input from a text box to dropdown list. Add a <populatingSearch> to generate the options for the list.

. . . <input type="dropdown" token="username"> <label>Select Name</label> <populatingSearch fieldForValue="suser" fieldForLabel="suser"> <![CDATA[sourcetype=p4change | rex "user=(?<suser>\w+)@" | stats count by suser]]> </populatingSearch>

48

</input> . . .

3. Display the results in a table. The following is the complete dynamic form search.

<form> <label>Username</label> <searchTemplate>sourcetype=logins $username$</searchTemplate> <fieldset> <input type="text" token="username" /> </fieldset> <input type="dropdown" token="username"> <label>Select Name</label> <populatingSearch fieldForValue="suser" fieldForLabel="suser"> <![CDATA[sourcetype=p4change | rex "user=(?<suser>\w+)@" | stats count by suser]]> </populatingSearch> </input> <row> <table> <title>Users</title> <option name="showPager">true</option> </table> </row> </form>

Dropdown list configuration options

There are several configuration options available for <input type="dropdown">. Tag
<label>label</label> <default>option</default> <prefix>search terms</prefix> <suffix>search terms</suffix>

Description
A label for the dropdown list.. The default option to select. If the default option cannot be found, the first option is selected. Prefix the search query with the specified search terms. Place the specified search terms after the search query. Specify options for the dropdown list. Options appear in the order they are defined, and before any options generated by a search specified by <populatingSearch>.

<choice value="value">

49

<populatingSearch fieldForLabel="label" fieldForValue="value">

A search that generates options for the dropdown list. Requires the attributes fieldForValue and fieldForLabel. fieldForValue is the field extracted from the populatingSearch and

placed in the value of the generated list option. fieldForLabel is the field extracted from the populatingSearch and placed as the label for the list option.
A saved search that generates options for the dropdown list. Requires the attributes fieldForValue and fieldForLabel. fieldForValue is the field extracted from the populatingSavedSearch and

<populatingSavedSearch fieldForLabel="label" fieldForValue="value">

placed in the value of the generated list option. fieldForLabel is the field extracted from the populatingSavedSearch and placed as the label for the list option.
Restrict your search results to a specific time window, starting with the earliestTime. Specify "rt" to enable real-time searches. Restrict your search results to a specific time window, ending with the latestTime. Specify "rt" to enable real-time searches.

<earliestTime>Splunk time format</earliestTime> <latestTime>Splunk time format</latestTime>

Drive multiple panels in a form

You can use post process to drive multiple panels in a search form. Post process allows you to reformat reporting results from the search. When you use post process, the base search must be a reporting search. This means you can create tables and charts according to specific criteria. For example, you can create various tables that are sorted on different columns, hide some columns, or filter rows that match some criteria. You can also do further aggregation on the original report. Caution: If the base search that you post process is not a search that generates reports, the results of the post process could be wrong. See How to use one search for a whole dashboard for more information on post processing searches.

50

Use the same search in multiple panels

You can configure one search to drive multiple outputs. This example has one base search that takes in a single search term. It then drives two separate searches that contain tokens matching user-entered values in the fieldset of the form. These panels display the results in a table panel and a chart panel. Note: The token attribute of each distinct search must match at least one of the input nodes defined within the fieldset.

<form> <label>Form search example - inverted flow, panel-defined search</label>

<fieldset> <input type="text" token="username"> <label>Global username</label> <default>*</default> <seed>claire</seed> </input> <input type="time" /> </fieldset> <row> <chart> <title>Commits over time</title> <searchTemplate> index=access_logs user=$username$ | timechart count </searchTemplate> <option name="charting.chart">area</option> </chart> <table> <title>Top files touched by the user</title> <searchTemplate> index=access_logs user=$username$ | top filePath </searchTemplate> </table> </row> </form>

51

Single-search, multi-post process

This example takes a single search and displays different facets of that search through post-processing. It combines the searches in the previous example into one search. The form search returns one result set. The searchPostProcess node inside each panel takes the results and runs (post processes) them through a separate search pipeline. The basic model is: 1. Create a base search seeded in the searchTemplate node that returns a report with a superset of data. 2. Create searchPostProcess nodes to filter or aggregate the base report.

<form> <label>Form search example - inverted flow, panel-defined post-process</label>

<searchTemplate> sourcetype=p4change OR sourcetype=jira user=$username$ | head 10000 </searchTemplate> <fieldset> <input type="text" token="username"> <label>Global username</label> <default>NON_EXISTENT</default> <seed>johnvey*</seed> </input> <input type="time" /> </fieldset> <row> <chart> <title>Commits over time</title> <searchPostProcess>timechart count</searchPostProcess> <option name="charting.chart">area</option> </chart> <table> <title>Top files touched by the user</title>

52

<searchPostProcess>top filePath</searchPostProcess> </table> </row> <row> <table> <title>Users vs changetype</title> <searchPostProcess>ctable user changetype maxcols=4</searchPostProcess> <option name="count">20</option> </table> <chart> <title>Average lines added by the user</title> <searchPostProcess>timechart avg(added)</searchPostProcess> <option name="charting.chart">line</option> <option name="charting.legend.placement">none</option> </chart> </row> </form>

Form search examples

These three examples show how to build different types of form searches using Simplified XML. There are additonal examples in the UI examples app, available from Splunkbase.

Simple table
This example shows how to create a simple form that searches for one field, sourcetype. Results from the search are displayed as a table with 50 rows maximum.

53

1. Create the form, give it a label, and specify the searchTemplate -- the search that is the basis for the form:

<form> <label>Simple table</label> <searchTemplate> index=_internal source=*metrics.log group=per_sourcetype_thruput series="$sourcetype$" | head 1000 </searchTemplate> <earliestTime>-30d</earliestTime> <latestTime>-0d</latestTime> ...

2. (Optional) Add an HTML panlel to display useful information &endash; instructions on how to create a search:

. . . <html> Enter a <code>sourcetype</code> in the field below. This view returns the most recent 1000 events from the metrics log referring to that <code>sourcetype</code>. </html> . . .

3. Set up an input. This example creates an input box that replaces the $sourcetype$ token in the searchTemplate above.

. . . <fieldset> <input token="sourcetype" /> </fieldset> . . .

4. Display the results in a table.

. . . <row> <table> <title>Matching events</title> <option name="count">50</option> </table> </row> </form>

54

Multiple inputs
This example shows how to take multiple inputs to build a form search. It also shows how to add a time range picker, which allows users to pick a time range for their search.

1. Set up a searchTemplate that creates two tokens:

$series$ $otherFilter$

The search does not include time specifications users can select from the time range picker:

<form> <label>Multiple inputs</label> <searchTemplate> index=_internal source=*metrics.log group="per_sourcetype_thruput" series=$series$ $otherFilter$ | fields eps, kb, kbps </searchTemplate>

2. Create a text box; upon first load, the box populates with 'splunkd'. If the user leaves the box empty, then the search uses '*'. This example always prefixes the token 'otherFilter' with 'eps>' if no value is entered, 'eps>-1' is inserted. Specify the timerange picker.

<fieldset> <input type="text" token="series"> <label>sourcetype</label> <default></default> <seed>splunkd</seed> <suffix>*</suffix>

55

</input> <input type="text" token="otherFilter"> <label>events per second greater than:</label> <prefix>eps></prefix> <default>-1</default> <seed>0</seed> </input> <input type="time" /> </fieldset>

3. Display the results in a table showing 20 rows per page. A pager allows users to navigate through the results.

<row> <table> <option name="showPager">true</option> <option name="count">20</option> </table> </row> </form>

Inverted flow
This form search is built backwards -- the input comes first and then feeds two separate charts and one table. The charts and table are built from a separate search, each with a searchTemplate that uses the 'sourcetypeToken' text box input. This example is useful for rendering pages that collate disparate searches that share a common search keyword/token.

56

1. Define a common form search input that all panels use:

<form> <label>inverted flow, panel-defined search</label> <fieldset> <input type="text" token="sourcetypeToken"> <label>sourcetype</label> <default>*</default> <seed>splunkd</seed> </input> <input type="time" /> </fieldset> . . .

2. Create two separate charts, each with a searchTemplate that uses the input from the form search above with the $sourcetypeToken$.

<row> <chart> <title>KB Indexed over time</title> <searchTemplate> index=_internal source=*metrics.log Component=metrics

57

group="per_sourcetype_thruput" series="$sourcetypeToken$" | timechart sum(kb) </searchTemplate> <option name="charting.chart">column</option> <option name="charting.primaryAxisTitle.text">Sourcetype</option> <option name="charting.secondaryAxisTitle.text">KB Indexed</option> <option name="charting.legend.placement">none</option> </chart> <chart> <title>Average events per second over time</title> <searchTemplate> index=_internal source=*metrics.log Component=metrics group="per_sourcetype_thruput" series="$sourcetypeToken$" | timechart avg(eps) </searchTemplate> <option name="charting.chart">area</option> <option name="chart.stackMode">stacked</option> <option name="charting.primaryAxisTitle.text">Sourcetype</option> <option name="charting.secondaryAxisTitle.text">Events per second</option> <option name="charting.legend.placement">none</option> </chart> </row>

3. Display further results in a table, also using the searchTemplate that takes input from form search using the $sourcetypeToken$:

<row> <table> <title>average kbps over time</title> <searchTemplate> index=_internal source=*metrics.log Component=metrics group="per_sourcetype_thruput" series="$sourcetypeToken$" | timechart avg(kbps) </searchTemplate> <option name="count">20</option> </table> </row> </form>

58

Build advanced views

About Advanced XML
This section provides an introduction to building views using Splunk's Advanced XML. It describes basic concepts and provides some example views. The documentation in this chapter is enough to get you started using Advanced XML. For additional information: Splunk App Framework: Refer to the Splunk App Framework section available from the Splunk Developer Portal. UI Examples app: Additional examples and documentation are available from the UI Examples app, available from Splunkbase. Advanced XML from the Splunk Wiki Cookbook The Advanced XML section provides some useful examples on getting started.

Simplified XML and Splunk's Dashboard Editor

Before building a view using Splunk's Advanced XML, you may want to start with Splunk's Dashboard Editor, which uses Simplified XML. To add features not available with Simplified XML. convert views from Simplified XML to Advanced XML using the following URI from Splunk Web:
http://localhost:8000/en-US/app/<app_name>/<view_name>?showsource=true

Views
Splunk builds views from XML files stored in an App's view directory. Views are made out of a library of modules. A module is actually a directory of CSS, JavaScript, HTML and, in some cases, Python and Flash files. You can create and edit views according to your needs. Use Simplified XML for basic views. Use Advanced XML for features not available from Simplified XML. For example, if you want to build a search view, or you want to use modules that aren't available in Simplified XML.

59

Modules
Every element in a Splunk view, from the search bar to the results, derives from a Splunk module. Some invisible elements, such as searches running in the background, derive from modules as well. You build and configure views by selecting the appropriate modules and linking them together. For example, the search bar is one module. Graphs and charts, text entry boxes, links, drop-down menus, and other components are also modules. The Module Reference in this manual lists all available modules, sorted by category. Splunk Web also displays modules sorted alphabetically at the following URL:
http://localhost:8000/modules

Module implementation is available in the following directory of a Splunk installation:

$SPLUNK_HOME/share/splunk/search_mrsparkle/modules/

Module parameters Modules use parameters to specify module-specific configurations, such as the size of a graph or chart, or the number of events to display per view. Use the <param> tag within a <module> tag to specify parameters, as indicated below. For example:

<module name="Message"> <param name="filter">*</param> </module>

The Module Reference lists the parameters available for each module. Some params are required, while others are optional. Some params have default settings. Module hierarchy Modules in a view pass information through a tree structure. For example, in a search view, search information passes from a parent module to child modules. Each child module can modify the search in some way. Finally, the search returns events or is transformed into results. For dashboard views, each panel in the dashboard is likely built from a separate search. In this case, you have more modules with smaller trees than a dashboard built from a single search.

60

The top-level module in a hierarchy uses the layoutPanel attribute to specify its location within the view. Child modules in the tree that do not specify the layoutPanel attribute inherit the attribute from their parent. Multiple panels in a view specify their position on the page using the layoutPanel attribute. For example:

<module name="SearchBar" layoutPanel="mainSearchControls"> Append ?showsource=true to any view's URL to see the hierarchy

of modules in

the page. For example,

http://localhost:8000/en-US/app/search/charting?showsource=true

Intentions You can use intentions to pass search language modifications down the module tree hierarchy. Specifically, modules pass searches down the hierarchy, modifying the searches by adding intentions. Once a series of intentions reaches a special type of module -- a dispatching module -- the intentions are composed into a search that is run in Splunk. Most results modules are dispatching modules -- if a results module doesn't have any results from a search by the time they are invoked in a view, the results module compiles the intentions and runs the resulting search.

Layout templates
There are two types of views: dashboards and search views. A Mako layout template defines each of these types of views. Mako templates are HTML files with support for Python. Splunk's layout templates define page layout; basically, how each element fits into a page. Splunk stores layout templates in the following location:
$SPLUNK_HOME/share/splunk/search_mrsparkle/templates/view/

Dashboards use a series of rows and columns in their layout. Search views contain a search bar at the top, an events view area, and a few other areas for customization. Dashboards display results from a variety of different searches, typically using results modules. A search view contains a set of search modules. The search passes through any number of modules, displaying results in one or more results modules. You can add other modules to dashboard views and search views as necessary.

61

You can use a views CSS to modify the appearance of a view. For example, to float a module next to another module, or move one module below another module. For more information about how to change CSS for a view, see Customize CSS in this manual.

Basic steps for configuring a view

Here's a general outline of the basic steps for configuring views: 1. Decide which modules to include in your view. 2. Configure each module in <view_name>.xml. 3. Put <view_name>.xml in the views directory, inside your app directory. Use either of the following two locations:

$SPLUNK_HOME/etc/apps/<app_name>/local/data/ui/views/ $SPLUNK_HOME/etc/apps/<app_name>/default/data/ui/views/

Note: Be careful about using the defaultdirectory. If you are creating your own app, then use the default directory. If you are customizing an app shipped with Splunk (for example, the search app), or an app you installed from another source, use the local directory. If you used the default directory in this case, your changes could be overwritten by an update to the app. 4. If you have more than one view for your app, arrange them in the UI by following the instructions in Build navigation. 5. To change the CSS for a view, Customize CSS.

Useful URIs for view building

Here are some URIs that provide useful information about your system when building a view. These are especially useful when building views through the file system, and not using Splunk Manager.

62

Tools available with info By far, the most useful toolset for building views for Splunk is the info endpoint available. This page offers a list of all available modules, RelaxNG schemas for view building, and many other utilities.
http://localhost:8000/info

Show source
http://localhost:8000/en-US/app/<app_name>/<view_name>?showsource=true

Use this endpoint to view the implementation of the underlying Advanced XML for a view. The Advanced XML is available in a tree view and as source code. You use this endpoint to convert Simplified XML to Advanced XML. Module reference This endpoint provides a list of all Advanced XML modules, sorted alphabetically. Compare with the Module Reference, available in this manual, sorted by functionality.
http://localhost:8000/modules

Display a new view Use this endpoint to a view newly added to a Splunk instance.
https://localhost:8089/services/apps/local?refresh=true

Reload a specific view Use this endpoint to refresh a specific view in Splunk Web.
https://localhost:8089/services/apps/local/<appname>?refresh=true

Use this endpoint to refresh a specific view in Splunk Web. Reload all views Reload all views for the specified app.
http://localhost:8000/app/<appname>/

Reload nav Reload the navigation menu in Splunk Web.

https://localhost:8089/servicesNS/admin/<appname>/data/ui/nav?refresh=1

63

About editing XML

Here are a few suggestions about editing XML files for Splunk views. Use HTML entities for special characters XML does not support the following five characters. Use HTML entities to display these characters: Character " ' < > HTML Entitiy
&quot; &apos; &lt; &gt;

&amp; & Schemas and editors

Splunk recommends that you use an XML editor that understands XML schemas. Schemas are useful for validating XML and also provide guidelines for building an XML file. Many XML editors let you load a schema -- DTD, XSD, Relax, RelaxNG are just a few different types of schemas. Splunk contains RelaxNG formatted schemas for views, from dashboards to form searches to advanced XML views. Read more about how to use Splunk's schemas in the Use XML schemas topic in this manual. Nesting modules With Advanced XML, you often nest child modules several levels deep. It is a good idea to use consistent indentation and commenting to make sure you properly close parent modules.

Build a search view using Advanced XML

Search views in Splunk are similar to the view in Splunk's default Search app. A search view presents a search bar to users, and displays events or search
64

results. Search views also have a specific layout. This topic provides a step-by-step procedure showing how to use Advanced XML to build a search view and introduces the search view layout.

Configure the search view

1. Decide which modules you want to include in your view. Use the Module Reference in this manual. 2. Create a view XML file <view_name>.xml, either through Splunk Manager, or in the views directory, inside your app directory:
$SPLUNK_HOME/etc/apps/<app_name>/local/data/ui/views/

Note: Use the app's local directory to avoid overwriting your changes when an app is updated. When creating your own app, you might want to use the app's default directory. 3. Configure each module in your view's XML file. Set parameters for each module and layoutPanels for parent modules. 4. If you have more than one view for your app, arrange them in the UI by following the instructions in Build navigation for your app in this manual.

Open the view.xml file for editing

If you are creating a new view XML file, <view_name>.xml, add the following tags:

<view> </view>

Name your view

Use the label tag to give the view a descriptive name.

<view> <label>Basic Search View</label>

Add chrome
Typically, you add the top navigation modules AccountBar and AppBar.

<view>

65

<label>Basic Search View</label>

<module name="AccountBar" layoutPanel="appHeader"/> <module name="AppBar" layoutPanel="navigationHeader"/> </view>

Set params Modify module parameters to customize your view. For example, you can remove the app drop-down by setting a param for the AccountBar. The following XML creates a view that doesn't have the link to Manager or the app drop-down menu in the upper right-hand corner:

<view>

<module name="AccountBar" layoutPanel="appHeader"> <param name="mode">lite</param> <module name="AppBar" layoutPanel="navigationHeader"/> </view>

Each module recognizes a specific set of parameters, as listed in the Module Reference. Specify layout panels The layoutPanel attribute to <module> defines where to display a module in a view. There are different layout panels for each part of the view, and different layout panels for different types of views. It's a good idea to familiarize yourself with the different layout panels to understand how to best display modules in a view. Chrome layout panels Here are the layout panels for chrome:

Module
messaging appHeader navigationHeader Use this layoutPanel for

Description messaging modules. AccountBar.

appHeader contains all the overall links for Splunk

66

AppBar module, which contains all the navigation for the App.
Use this layoutPanel for the viewHeader viewHeader is a header panel for your view, where you can put a

title for your view.

Add the search bar

A basic search view shows the search bar:

To build this view, use the SearchField module -- this module creates the search bar. You can prepopulate this module with search terms, but leave it blank for now:

<view> <label>Basic Search View</label>

<module name="AccountBar" layoutPanel="appHeader"/> <module name="AppBar" layoutPanel="navigationHeader"/>

<module name="SearchBar" layoutPanel="mainSearchControls"> </view>

Search module layout panels The following layout panels are useful for search modules: Module
splSearchControls-inline

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

mainSearchControls

There are additional search modules. Refer to the search module section of the Module Reference.

Add the results display area

Add the EventsViewer module to display search results. A user can drill down from the events displayed.
67

<view> <label>Basic Search View</label>

<module name="AccountBar" layoutPanel="appHeader"/> <module name="AppBar" layoutPanel="navigationHeader"/>

<module name="SearchBar" layoutPanel="mainSearchControls">

<module name="EventsViewer"/> </module> </view> The SearchBar module contains the EventsViewer module, which means EventsViewer is a child of SearchBar EventsViewer can access the search the search bar. Child modules inherit the layoutPanel settings, as well.

from

Tip: Using Advanced XML, you often nest child modules several levels deep. It is a good idea to use consistent indentation and commenting to make sure you properly close parent modules. Results layout panels Splunk provides a number of results modules. See the results modules section of the Module Reference. Results modules look best when placed in the following layout panels: Module
fullWidthControls graphArea sidebar resultsHeaderPanel pageControls resultsAreaLeft resultsAreaRight

Description
Use this layout panel for results that take up the whole width of the view, such as serverSideInclude or other web resources. Use this panel for the

FlashTimeline module.

FieldPicker, MultiFieldViewer and SuggestedFieldViewer modules.

Use this panel to display the Add a header to your results with the Put

ResultsHeader module.

Paginator and other page controls modules here. EventsViewer module.

Display your results here with the

Add a secondary area to display results to the right of resultsAreaLeft.

68

resultsOptions

This is a pop-up layer and shows up as a link to

Options from

within pageControls.

Add pagination
Add a Paginator module to allow users to page through results spread over two or more pages.

<module name="Paginator"> <param name="entityName">events</param> The entityName parameter is required for the Paginator

module. This module

also accept several optional parameters. The Paginator module completes the example. Here is a listing of the complete search view.

<view> <label>Basic Search View</label>

<module name="AccountBar" layoutPanel="appHeader"/> <module name="AppBar" layoutPanel="navigationHeader"/>

<module name="SearchBar" layoutPanel="mainSearchControls">

<module name="Paginator"> <param name="entityName">events</param>

<module name="EventsViewer"/> </module> </module> </view>

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
69

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:

70

<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
messaging appHeader navigationHeader viewHeader Use this layoutPanel for

Description messaging modules. AccountBar.

appHeader contains all the overall links for Splunk Use this layoutPanel for the

AppBar module, which contains all the navigation for the App.
viewHeader is a header panel for your view, where you can put a

title for your page.

71

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:

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

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"

73

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
splSearchControls-inline

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

mainSearchControls

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>

74

<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> </module> </module>

Build a form search using Advanced XML

You can add a form search to any view using the Advanced XML. Advanced form searches use the ExtendedFieldSearch module in the search view template. To read more about search views, see Introduction to advanced views.

Add chrome
Start out your form search view by adding the chrome:

<view onunloadCancelJobs="False" autoCancelInterval="100"> <label>Sample search</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>

Add a form search pattern

All form searches include a form search pattern, which are available from the following modules: Module
HiddenSearch ExtendedFieldSearch EventsViewer (or other module to display results)

Description
Specifies the base search for your form search. Make sure you specify tokens correctly. For example, $mytoken$ Maps the term for replacement from your search. There are several parameters to set with this module. Specify a module to display the results.

The following example is a basic configuration of the ExtendedFieldSearch module. The parent module is a HiddenSearch. The intention and
75

replacementMap

parameters each take additional parameters to set up the form

input.

<module name="HiddenSearch" layoutPanel="mainSearchControls"> <param name="search">sourcetype=$st$</param> <module name="ExtendedFieldSearch"> <param name="intention"> <param name="name">stringreplace</param> <param name="arg"> <param name="st"> <param name="default">apache_error</param> </param> </param> </param> <param name="replacementMap"> <param name="arg"> <param name="st"> <param name="value"></param> </param> </param> </param> <param name="field">Sourcetype</param> <module name="EventsViewer" layoutPanel="resultsAreaLeft"> <param name="segmentation">full</param> </module> </module> </module>

Advanced examples
There are many ways to configure a form search using Advanced XML. Here are a few examples to get you started. Use wildcards This example shows how to use wildcards with a token.

... <module name="HiddenSearch" layoutPanel="mainSearchControls"> <param name="search">sourcetype=apache_error *$target$*</param> <module name="ExtendedFieldSearch"> <param name="intention"> <param name="name">stringreplace</param>

76

<param name="arg"> <param name="target"> <param name="default">500</param> </param> </param> </param> <param name="replacementMap"> <param name="arg"> <param name="target"> <param name="value"></param> </param> </param> </param> <param name="field">Wildcard search</param> <module name="EventsViewer" layoutPanel="resultsAreaLeft"> <param name="segmentation">full</param> </module> </module> </module>

Use two variables The following example takes two separate tokens as input.

<module name="HiddenSearch" layoutPanel="mainSearchControls"> <param name="search">sourcetype=apache_error $error$ $hours_ago$</param> <module name="ExtendedFieldSearch"> <param name="intention"> <param name="name">stringreplace</param> <param name="arg"> <param name="error"> <param name="fillOnEmpty">True</param> </param> </param> </param> <param name="replacementMap"> <param name="arg"> <param name="error"> <param name="value"></param> </param> </param> </param> <param name="field">Multiple replace (apache search)</param>

77

<module name="ExtendedFieldSearch"> <param name="intention"> <param name="name">stringreplace</param> <param name="arg"> <param name="hours_ago"> <param name="fillOnEmpty">True</param> <param name="prefix">starthoursago=</param> </param> </param> </param> <param name="replacementMap"> <param name="arg"> <param name="hours_ago"> <param name="value"></param> </param> </param> </param> <param name="field">Multiple replace (starthoursago)</param> <module name="EventsViewer" layoutPanel="resultsAreaLeft"> <param name="segmentation">full</param> </module> </module> </module> </module>

Use ORs The following example shows how to build a search with ORs. The desired search string is:
eventtypetag=authentication tag=cardholder-dest src_ip="$SourceIP$" OR user="$User$"

You can approximate the search string using the stringreplace parameter to intention intention's prefix and suffix parameters to intention where $User$ is prefixed with OR user=" and suffixed with ":
eventtypetag=authentication tag=cardholder-dest src_ip="$SourceIP$" $User$

<module name="HiddenSearch" layoutPanel="mainSearchControls"> <param name="search"> eventtypetag=authentication tag=cardholder-dest src_ip="$SourceIP$" $User$

78

</param> <module name="ExtendedFieldSearch"> <param name="field">SourceIP</param> <param name="intention"> <param name="name">stringreplace</param> <param name="arg"> <param name="SourceIP"> <param name="fillOnEmpty">True</param> <param name="value"></param> </param> </param> </param> <param name="replacementMap"> <param name="arg"> <param name="SourceIP"> <param name="value"></param> </param> </param> </param> <module name="ExtendedFieldSearch"> <param name="field">User</param> <param name="intention"> <param name="name">stringreplace</param> <param name="arg"> <param name="User"> <param name="fillOnEmpty">True</param> <param name="prefix">OR user="</param> <param name="suffix">"</param> </param> </param> </param> <param name="replacementMap"> <param name="arg"> <param name="User"> <param name="value"></param> </param> </param> </param> <module name="EventsViewer" layoutPanel="resultsAreaLeft"> <param name="segmentation">full</param> </module> </module> </module> </module>

79

Reuse the same token This example reuses the same token for two different parts of the search:

... <module name="HiddenSearch" layoutPanel="mainSearchControls"> <param name="search">eventtypetag=config_file source=$File$ OR $File$</param> <module name="ExtendedFieldSearch"> <param name="field">File</param> <param name="intention"> <param name="name">stringreplace</param> <param name="arg"> <param name="File"> <param name="value"></param> </param> </param> </param> <param name="replacementMap"> <param name="arg"> <param name="File"> <param name="value"></param> </param> </param> </param> <module name="EventsViewer" layoutPanel="resultsAreaLeft"> <param name="segmentation">full</param> </module> </module> </module> ...

Use XML schemas

Starting with version 4.1, Splunk provides RelaxNG formatted schemas for the view XML, including the simplified dashboards, simplified form searches, advanced dashboards and views. Also, there are schemas available for the navigation XML, the setup XML and manager pages XML. You can find all of these schemas off the info endpoint:

http://localhost:8000/info

These schema files are in RelaxNG compact syntax (*.rnc). But you can convert to other formats with Trang. Trang is an open source tool that lets you convert between different XML schema formats.
80

Here's an example of using Trang to convert from Relax to RelaxNG

java -jar trang.jar -O rng all.rnc all.rng

Files
Here's a descriptive list of all the files available from the info endpoint: File
all.rnc

Description
Serves as a single entry point for all of the registered RelaxNG schemas. All of the schemas are written in RelaxNG compact syntax and are automatically converted to the full RelaxNG schema using Trang. Covers all 3 forms of view XML. Covers the app nav XML, Placeholder schemas for management XML files. Covers the app setup XML.

view.rnc nav.rnc manager.rnc setup.rnc

Validation
Splunk provides a validation script, validate_all.py, located at:$SPLUNK_HOME/share/splunk/search_mrsparkle/exposed/schema/ This script inspects the UI XML files present here in Splunk installation:
$SPLUNK_HOME/etc/

To validate your XML files, first navigate to the location listed below and then run the script:

cd $SPLUNK_HOME/share/splunk/search_mrsparkle/exposed/schema/ $SPLUNK_HOME/bin/splunk cmd python validate_all.py

Advanced charting options

Splunk charts in dashboards and other views are highly customizable. You can make a wide variety of customizations through the Splunk Web UI with the Panel Editor, which enables you to change chart axis labels, define color ranges for gauges, configure stacking modes for column and bar charts, and much more.

81

When the basic customization options offered by the Panel Editor aren't enough, you can go "under the hood" and edit the panel XML directly to customize the appearance and behavior of your charts in additional ways. You can change axis label text styles, reverse chart axes, define specific color palettes for chart results, and much more. You can customize the appearance of charts using either Simplified XML or Advanced XML. The syntax for charts differs slightly between Simplified and Advanced XML. For example, in Simplified XML syntax, charting controls are specified with option attributes. In Advanced XML, you specify the same thing using params to a HiddenChartFormatter module. For code examples, see the "Chart colors" section, below, as well as the sections that follow. This topic provides a few common customizations using both Simplified and Advanced XML. For more information on building charts in simplified XML, refer to adding a chart to your dashboard. Refer to the Custom Chart Configuration Reference in this manual for a complete list of chart customizations available.

Chart customization and non-Flash chart displays

Dashboards built from Simplified XML use the JSChart module to render graphics. JSChart uses JavaScript to build the graphics for a chart. This provides charting support on platforms such as iOS mobile devices that cannot display Flash-based graphics. The JSChart module also provides better printing quality. Any chart that you create and edit through Splunk Web (for example, using the Report Builder, the Add to Dashboard dialog, and the Dashboard and Panel Editors) use Simplified XML. Thus the JSChart module renders the graphics for a chart using JavaScript Flash is not required. Unsupported JSChart properties Caution: Splunk offers a wide array of dashboard chart customization properties that are not currently supported by the JSChart module. Using any of these properties with JSChart affects how dashboards are displayed: Dashboard using Simplified XML To render a chart using unsupported properties for JSChart, Splunk uses FlashChart, the Flash-based charting module. This means that the chart displays incorrectly in platforms that do not support Flash. Dashboard using Advanced XML In Advanced XML you need to specify the charting module (JSChart or FlashChart) for each chart in the
82

dashboard. For a chart that uses the JSChart module Splunk simply ignores unsupported properties. For example, consider a dashboard created using Simplified XML that contain a panel with a line chart. If you edit the seriesColors chart customization property, which is unsupported by the JSChart module, Splunk renders the line chart with FlashChart. The line chart displays correctly in browsers that support Flash, but the chart won't show up on platforms that do not support Flash, such as an iPad. Splunk applies charting modules in dashboards on a panel by panel basis. It is possible to have a dashboard where some charts use the JSChart module while others use FlashChart. Note: All of the charting customizations described in the following topics (series colors, brushes, palettes, and so on) are not supported by the JavaScript-based charting module. If you implement them using Simplified XML, the resulting charts display only on platforms supporting Flash. For more information about what charting parameters are supported by the Java-script charting module and what charting parameters are not, see the Custom Charting Configuration Reference in this manual. JSChart display issues The JSChart charting module has some display issues that may be resolved in upcoming releases. Non-transforming searches The JSChart module cannot render charts based on searches that do not include (or properly use) transforming search commands such as chart, timechart, stats, or eval. The FlashChart module will attempt to chart the results of non-transforming searches, but charts won't revert to FlashChart automatically when non-transforming searches are used. You will need to explicitly specify that Splunk use the FlashChart module in the charting XML. Time Charting JSChart 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, JSChart treats the timestamp data as a series of strings.
83

FlashChart can plot time-based data with other transforming search commands. Search result truncation For performance reasons, the JSChart module truncates search result data sets that are too large. The exact limits that trigger this truncation depend on the browser being used as well as the charting configuration. When the JSChart module is caused to truncate data sets, it displays an error message below the chart. To remove the error message you can: Switch to a chart type that involves drawing only one shape per series (in other words, move from a column chart to a line chart). Reduce the number of fields that are being plotted. For time charts, use a longer time-span between data points. There are additional conditions that can cause truncation: Searches that return too many results per series can cause JSChart to hang the browser. Splunk employs a throttling strategy that restricts the number of results returned per series to 500 by default. You can configure this value by going to JSChart.conf and changing the maxResultsCount parameter to something other than 500. JSChart can only plot the first 50 series that are returned. Additional series will not be plotted. Object rendering limits by charting module. Both charting modules have rendering limits if the total number of objects plotted in the chart exceeds a certain number. If you run into this limit you'll want to change either the search string or search time range so that the results returned fall under the limit. For the FlashChart module, the rendering limit in all cases is 2000 objects. If you hit this limit, the chart stops rendering. The JSChart module has a 2000 object limit for line charts, a 1200 object limit for other chart types, and a 1000 object limit for charts built in Internet Explorer. If you hit the limit with a chart that uses JSChart, Splunk provides an error message. Category limit In JSChart, when you are plotting data on a categorical axis, no more than 80 categories can be displayed. When there are more than 80 categories Splunk doesn't truncate the data but instead hides the labels and tick marks. This is not
84

configurable; Splunk runs into performance issues if you go higher than this. If you need to display a large number of axis categories, use FlashChart. It has a much higher limit. Chart rendering limits Both charting modules have limits as to the full number of objects/pixels that they can render.

Chart colors
You may want to set a specific set of colors for a series in a chart. To change chart colors, use the seriesColors property charting.seriesColors. The seriesColors property is the simplest way to adjust the colors of series in a Splunk chart. It is represented as a list of hexadecimal color values (0xRRGGBB values separated by commas and surrounded by brackets). For example, in a Simplified XML dashboard:

<dashboard> <label>My dashboard</label> <row> <chart> <searchName>My saved report</searchName> <option name="charting.seriesColors"> [0xFF0000,0xFFFF00,0x00FF00] </option> </chart> </row> </dashboard>

In an Advanced XML dashboard, use the charting options with HiddenChartFormatter:

... <module name="HiddenChartFormatter"> <param name="charting.seriesColors"> [0xFF0000,0xFFFF00,0x00FF00] </param> ...

Series colors for Splunk charts are index-based, which means that a color is assigned to a particular series based on its index among all other series assigned to legend labels in a specific order. (This usage of "index" does not refer to Splunk event indexes or indexers). Given the seriesColors list defined above, the first series of a chart is assigned color 0xFF0000 (red), the second
85

series 0xFFFF00 (yellow), and so on. For example, in a Simplified XML dashboard:

<dashboard> <label>My dashboard</label> <row> <chart> <searchName>My saved report</searchName> <option name="charting.legend.labels">[error,warn,info]</option> <option name="charting.seriesColors">[0xFF0000,0xFFFF00,0x00FF00]</option> </chart> </row> </dashboard>

In an Advanced XML dashboard, use the charting options with HiddenChartFormatter:

... <module name="HiddenChartFormatter"> <param name="charting.legend.labels">[error,warn,info]</param> <param name="charting.seriesColors">[0xFF0000,0xFFFF00,0x00FF00]</param> ... This assigns the series named error to the color 0xFF0000 (red) and the series named warn to the color 0xFFFF00 (yellow) (and so on) from the seriesColors list

above. However, if there are other charts in a view, this mapping is not necessarily be guaranteed. That's because all legends for all charts in a view are connected to a common "master legend" by default to synchronize their colors. The master legend determines the final label/series index mapping from the merged mappings of its "slave" legends. The first slave legend to be processed by the master legend (typically the first one in a view) has its labels placed before the labels of the next legend to be processed (minus duplicates). Therefore, error at series index 0 in the labels list above is not necessarily at series index 0 in the master list. To alleviate this problem, you can exclude a legend from synchronization by assigning its masterLegend property to null or an empty string. For example, in a Simplified XML dashboard:

<dashboard> <label>My dashboard</label> <row>

86

<chart> <searchName>My saved report</searchName> <option name="charting.legend.labels">[error,warn,ok]</option> <option name="charting.seriesColors">[0xFF0000,0xFFFF00,0x00FF00]</option> <option name="charting.legend.masterLegend"></option> </chart> </row> </dashboard> This guarantees a one-to-one mapping between the labels and seriesColors

lists above. But what if you want to assign a color to a particular series based on its name instead of its series index? In that case use the fieldColors property to map specific colors to particular fields. The fieldColors property is represented as a map of field/color pairs surrounded by curly braces:

<option name="charting.fieldColors"> {"error":0xFF0000,"warn":0xFFFF00,"info":0x00FF00} </option> This example assigns the series named error to the color 0xFF0000 (red), the series named warn to the color 0xFFFF00 (yellow), and the series named info to the color 0x00FF00 (green). Although not required in this case, double quotes must surround field names containing any of these characters []{}(),:".

Existing double quotes or backslashes in the field name must be escaped with a preceding backslash.

Brushes and palettes

The entire concept of a series "color" is a drastic simplification of how a series, or any other visual element in Splunk charts, is actually styled. For example, the default style of all series in Splunk charts is not a solid color at all--it's a gradient of two colors. The seriesColors property described earlier is actually a convenience property to simplify the complexity of how chart styles are really defined. If you're only interested in changing the default series color mappings of a chart, while keeping the rest of the default styling, then the seriesColors property will suffice. If, however, you want more elaborate styling beyond the default gradients or even beyond colors, you need to become familiar with the underlying brush and palette architecture. All visual elements in Splunk charts, with the exception of text, are "painted" using brushes. A brush can paint fills, strokes, gradients, images, and even video. Some brushes can combine and layer these methods. For example, a Solid Fill Brush paints solid color fills, while a Solid Stroke Brush paints solid
87

color strokes. There is also a Group Brush that paints with a group of brushes simultaneously. You might use the Group Brush to paint a solid color fill surrounded by a solid color stroke, for example. Here's an example of how a custom brush with a solid red fill and 50% transparency might be defined:

<dashboard> <label>My dashboard</label> <row> <chart> <searchName>My saved report</searchName> <option name="charting.myBrush">solidFill</option> <option name="charting.myBrush.color">0xFF0000</option> <option name="charting.myBrush.alpha">0.5</option> </chart> </row> </dashboard>

Charts often have several series to plot, which means they usually need several brushes, one for each series. But spending your time designing unique brushes for individual series for all the different chart visualization options doesn't scale, especially if you have views that include dozens of series. Instead, charts use brush palettes. A brush palette maps a series index to a brush. There are a variety of brush palettes for Splunk charts. The simplest brush palette is the Solid Fill Brush Palette, which generates a solid fill brush for each series in a chart. To determine the color of each brush it generates, the Solid Fill Brush Palette uses another type of palette - a color palette. Similar to a brush palette, a color palette maps a series index to a color. For example, a List Color Palette maps a series index directly to a color from a specified list of colors. By default, if an index is out of range of the list of colors, it wraps around to the beginning of the list, essentially repeating the colors. The List Color Palette can optionally interpolate between the list of colors, instead of wrapping, to produce a range of colors that spans over the total number of series. The following example specifies a color palette that interpolates between red, green, and blue:

<dashboard> <label>My dashboard</label> <row> <chart> <searchName>My saved report</searchName> <option name="charting.myColorPalette">list</option> <option name="charting.myColorPalette.colors">[0xFF0000,0x00FF00,0x0000FF]</option> <option name="charting.myColorPalette.interpolate">true</option>

88

</chart> </row> </dashboard>

Property references
In order to use the color palette defined above to generate Solid Fill Brushes for a chart, reference it from the appropriate property of a Solid Fill Brush Palette. To reference a property to use as the value of another property, use the "@" symbol followed by the property name to reference (minus the "charting" prefix). The Solid Fill Brush Palette has a colorPalette property that expects a color palette as its value:

<option name="charting.myBrushPalette">solidFill</option> <option name="charting.myBrushPalette.colorPalette">@myColorPalette</option>

Again use a property reference to create a Column Chart whose columns are painted using the brushes generated from myBrushPalette. The Column Chart has a columnBrushPalette property designed specifically for this purpose:

<option name="charting.chart">column</option> <option name="charting.chart.columnBrushPalette">@myBrushPalette</option>

You can also use a property reference in the original definition of myColorPalette to reference another property defining the list of colors. This is exactly how the simple seriesColors property described earlier is wired up to the underlying default set of brushes and palettes in Splunk charts:

<option name="charting.myColorPalette.colors">@seriesColors</option>

Create chart options on the fly

You can define your own properties on the fly by simply declaring them. For example, the following declares a custom brush with a red solid fill:

<option name="charting.myBrush">solidFill</option> <option name="charting.myBrush.color">0xFF0000</option>

You can assign a property to another property either by reference or copy. The "@" symbol denotes a property reference and the "#" symbol denotes a property copy (or clone). For example, to use the custom brush defined above as the background of the tooltip, you can use a property reference:

<option name="charting.tooltip.backgroundBrush">@myBrush</option>

89

However, if you would like to use a brush that's the same as the custom brush defined above except it has an alpha transparency of 50%, you can clone it then modify the alpha property of the clone.

<option name="charting.tooltip.backgroundBrush">#myBrush</option> <option name="charting.tooltip.backgroundBrush.alpha">0.5</option>

If you need to use either the "@" or "#" symbols as the first character of a string (for example, an axis title), you can escape it with a second symbol:

<option name="charting.axisTitleY.text">## Of Downloads</option> <option name="charting.axisTitleX.text">@@Foo</option>

Customize drilldown options

By default, all tables and charts provide drilldown capability into the relevant events. In views created with the Splunk Dashboard Editor or Simplified XML, you can set up a few options for drilldown search. Learn more about the basic options for table chart drilldown in the User Manual. However, if the basic table and chart drilldown configurations don't suit your needs, you can configure additional behavior using Advanced XML. For example, to send your drilldowns to views other than the timeline or to generate a chart from one search and drilldown to run a separate search. You can change the default drilldown behavior for any table or chart in your dashboard. You first need to create an advanced dashboard, as described earlier in this manual. This topic includes a few examples of advanced drilldown configurations. There are many customization options available with Advanced XML use these examples to get started. For more examples, see the UI examples app posted on Splunkbase.

Add chrome
Start out your view by adding the chrome and nav:

<view onunloadCancelJobs="False" autoCancelInterval="100"> <label>Drilldown view</label> <module name="AccountBar" layoutPanel="appHeader"/> <module name="AppBar" layoutPanel="navigationHeader"/> <module name="Message" layoutPanel="messaging"> <param name="filter">*</param>

90

<param name="clearOnJobDispatch">False</param> <param name="maxSize">1</param> </module>

Add a drilldown pattern

Next, decide what kind of drilldown to build and pick one or more of the following configurations. All table and chart drilldowns start with the basic drilldown pattern, which is built with the following modules: Module
HiddenSearch SimpleResultsTable ConvertToDrilldownSearch ViewRedirector

Description
Use this module to specify the search that populates your chart or table. Display your results. Enables drilldown with all the defaults. Specify what view to send your users to when they click on the chart or table.

<module name="HiddenSearch" layoutPanel="panel_row2_col1" autoRun="True"> <param name="search">host=foo OR bar</param> <param name="earliest">-1h</param> <module name="SimpleResultsTable"> <param name="displayRowNumbers">False</param> <param name="drilldown">row</param> <param name="entityName">results</param> <module name="ConvertToDrilldownSearch"> <module name="ViewRedirector"> <param name="viewTarget">flashtimeline</param> </module> </module> </module> </module>

This basic pattern sets up a drilldown search on a table. When a user clicks a row within the table, they are redirected to relevant search results in the timeline view.

Advanced examples
Here are a few examples of the customized drilldown actions that you can create using Advanced XML.

91

Change the default click behavior You can use the advanced XML to change the behavior when a user clicks on a table or chart. You may want to send them to another view besides the timeline, or you may want to display another chart below the first table or chart.
Launch a search in a new view

With a small edit to the default drilldown configuration, you can open a search in a view other than timeline. Just change the viewTarget param of theViewRedirector module. If a user clicks to drilldown, the new view opens in the same window. To open in a new window, ctrl-click (or command-click on a Mac). This example opens up drilldown click searches in a view called MyCustomView.

<module name="HiddenSearch" layoutPanel="panel_row2_col1" autoRun="True"> <param name="search">host=foo OR bar</param> <param name="earliest">-1h</param> <module name="JobProgressIndicator"></module> <module name="SimpleResultsTable"> <param name="displayRowNumbers">False</param> <param name="drilldown">row</param> <param name="entityName">results</param> <module name="ConvertToDrilldownSearch"> <module name="ViewRedirector"> <param name="viewTarget">MyCustomView</param> </module> </module> </module> </module> Drilldown to a new chart

Here's an example that opens a new chart below when a user clicks to drilldown on the initial chart. This example includes a bar chart that displays the top ten sourcetypes by total volume indexed. A click on a bar causes a second chart to open below the initial one. The second drilldown chart displays the average eps over time for the sourcetype that was clicked, over the same period of time used to collect the sums in the original search.

92

And here's the XML behind this example:

<module name="HiddenSearch" layoutPanel="panel_row3_col1" autoRun="True"> <param name="search"> index=_internal source=*metrics.log group=per_sourcetype_thruput | chart sum(kb) over series | sort -sum(kb) | head 10 </param> <param name="earliest">-1h</param> <module name="HiddenChartFormatter"> <param name="charting.chart">bar</param> <param name="charting.primaryAxisTitle.text">Sourcetype</param> <param name="charting.secondaryAxisTitle.text">KB Indexed</param> <param name="charting.legend.placement">none</param> <module name="JobProgressIndicator"/>

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

<module name="HiddenSearch"> <param name="search"> index=_internal source=*metrics.log group=per_sourcetype_thruput | timechart avg(eps) </param> <param name="earliest">-1h</param>

93

<module name="ConvertToIntention"> <param name="intention"> <param name="name">addterm</param> <param name="arg"> <param name="series">$click.value$</param> </param> </param>

<module name="JobProgressIndicator"></module>

<module name="SimpleResultsHeader"> <param name="entityName">results</param> <param name="headerFormat"> EPS over time for sourcetype=$click.value$ $time$ </param> </module> <module name="HiddenChartFormatter"> <param name="chart">line</param> <param name="primaryAxisTitle.text">Time</param> <param name="secondaryAxisTitle.text">events per second</param> <param name="legend.placement">none</param> <module name="FlashChart"> <param name="width">100%</param> <param name="height">160px</param> </module> </module> </module> </module> </module> </module> </module>

Swap out the underlying search You can configure a drilldown to launch a different search than the search that generates the data in the table or chart. There are a couple of reasons to do this: To build charts and tables on searches of a summary index. To build charts and tables on metadata searches.

94

If you keep the default drilldown behavior, these searches don't really result in a useful set of events. So it's best to swap out the drilldown search. You do this by adding another HiddenSearch or HiddenSavedSearch module between the chart or table and the ConvertToDrilldownSearch module. For example, if you have a dashboard timechart based on this summary index search:
index=summary report=firewall_top100_sources_hourly | timechart count by host

Use Advanced XML to configure the dashboard panel so a drilldown initiates a search that matches the events returned by the original summary index search, such as:
sourcetype=cisco sourcetypetag=production | timechart count by host

Here's what the XML looks like:

<module name="HiddenSearch" layoutPanel="panel_row2_col1" autoRun="True"> <param name="search"> index=summary report=firewall_top100_sources_hourly | timechart count by host </param> <param name="earliest">-1h</param> <module name="HiddenChartFormatter"> <param name="chart">line</param> <param name="primaryAxisTitle.text">Time</param> <param name="secondaryAxisTitle.text">events per second</param> <param name="legend.placement">none</param> <module name="FlashChart"> <param name="width">100%</param> <param name="height">160px</param> <module name="HiddenSearch" layoutPanel="panel_row2_col1" autoRun="True"> <param name="search"> sourcetype=cisco sourcetypetag=production | timechart count by host </param> <module name="ConvertToDrilldownSearch"> <module name="ViewRedirector">

95

<param name="viewTarget">flashtimeline</param> </module> </module> </module> </module> </module> </module>

Build a real-time dashboard

You can use Splunk's real-time reporting capability to show streaming results in dashboards. First, construct a real time search, as described in the real-time search and reporting topic in the User Manual. Save this search and add it to your dashboard using the HiddenSavedSearch module. To enable real-time on your dashboard, add the EnablePreview module to your view XML. For example:

... <module name="EnablePreview"> <param name="enable">true</param> <param name="display">false</param> ...

If you're building an inline search with the HiddenSearch module, you can specify a sliding window for real-time results by setting the earliest and latest params on your HiddenSearch module. For example, the following sets a five minute window, therefore showing streaming results from the most recent five minutes:

... <module name="HiddenSearch" autoRun="True"> <param name="search">host=foo OR bar | top IP</param> <param name="earliest">rt-5m</param> <param name="latest">rt</param> ...

Example
Here is a complete example. This example sets the real-time window to 30 seconds.

<?xml version="1.0"?> <view template="dashboard.html"> <label>Real time example</label>

96

<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> <module name="TitleBar" layoutPanel="viewHeader"> <param name="actionsMenuFilter">dashboard</param> </module> <module name="GenericHeader" layoutPanel="panel_row1_col1" autoRun="True"> <param name="label">My real time search</param> <module name="HiddenSearch" autoRun="True"> <param name="search">host=foo OR bar | top IP</param> <param name="earliest">rt-30s</param> <param name="latest">rt</param> <module name="EnablePreview"> <param name="enable">true</param> <param name="display">false</param> <module name="HiddenChartFormatter"> <param name="chart">area</param> <param name="primaryAxisTitle.text">Time</param> <param name="chart.stackMode">default</param> <param name="secondaryAxisTitle.text">Count</param> <module name="FlashChart"> <param name="width">100%</param> <param name="height">250px</param> </module> <module name="ViewRedirectorLink"> <param name="viewTarget">flashtimeline</param> <param name="label">View results</param> </module> </module> </module> </module> </module> </view>

97

Turn off autopause

Searches in views pause automatically if all three of the following conditions are met: The view contains a JobStatus module (for example flashtimeline, charting). The view has configured JobStatus with a valid autoPauseInterval parameter (defaults to 30 seconds). The URI of the view contains an auto_pause=true parameter, for example:

http://localhost:8000/app/search/flashtimeline?auto_pause=true&q=search foo bar

The best way to build a URI with auto_pause=true is to send searches to a view using the ViewRedirector in another view. Use the ViewRedirector module to insert the URI params in your redirect. For example:

<module name="ViewRedirector"> <param name="viewTarget">flashtimeline</param> <param name="uriParam.auto_pause">true</param> </module>

Specifically, set:
<param name="uriParam.auto_pause">true</param>

Switcher modules
Switchers are useful for creating navigation within a view. You can use tabs or pulldown menus to switch between content. Switchers create a fork between different branches of XML, but the choice doesn't influence any individual search in the child branches. This is similar to lister modules, but lister modules allow for input that affects the searches in the child branches. The Switcher modules that are most useful are: PulldownSwitcher TabSwitcher LinkSwitcher

98

Here is an example using LinkSwitcher. There are more examples in the UI examples app, available from Splunkbase.

Add chrome
First add the chrome and nav for your page:

<view template="dashboard.html"> <label>Switcher Intro</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> <module name="TitleBar" layoutPanel="viewHeader"> <param name="actionsMenuFilter">dashboard</param> </module> . . . </view>

The group attributes can be confusing sometimes they populate the dashboard panel titles, as in the module immediately below. But in the immediate child modules of switcher modules, the group attributes become the relevant label for the switcher element. For example, the tab's or pulldown option's text.

LinkSwitcher
This is a basic example using a LinkSwitcher with four children. All children use chart patterns. Module
HiddenSearch HiddenChartFormatter JobProgressIndicator FlashChart Specifies

Description
Specifies a search to drive the chart.

custom charting configurations.

(Optional) Displays the amount of chart remaining to load. Displays the actual Flash chart.

The last child adds a TimeRangePicker to drive the time of results.

99

. . . <module name="LinkSwitcher" layoutPanel="panel_row2_col1"> <param name="mode">independent</param> <param name="label"> </param> . . .

First switcher child The group attribute set on HiddenSearch governs the label that represents this branch in the switcher. For LinkSwitcher the label displays as a link.

. . . <module name="HiddenSearch" group="cpu time by processor" autoRun="True"> <param name="search"> index="_internal" source="*metrics.log" group="pipeline" | chart sum(cpu_seconds) over processor | sort -sum(cpu_seconds) | head 10 </param> <module name="HiddenChartFormatter"> <param name="chart">line</param> <param name="primaryAxisTitle.text">CPU seconds</param> <param name="secondaryAxisTitle.text">Pipeline processors</param> <param name="legend.placement">right</param> <module name="JobProgressIndicator"/> <module name="FlashChart"> <param name="width">100%</param> <param name="height">300px</param> </module> </module> </module> . . .

Second switcher child

. . . <module name="HiddenSearch" group="KB Indexed by sourcetype" autoRun="True"> <param name="search"> index=_internal source=*metrics.log component=metrics group=per_sourcetype_thruput | chart sum(kb) by series | sort -sum(kb) | head 10 </param> <param name="earliest">-1h</param>

100

<module name="HiddenChartFormatter"> <param name="chart">bar</param> <param name="primaryAxisTitle.text">Sourcetype</param> <param name="secondaryAxisTitle.text">KB Indexed</param> <param name="legend.placement">none</param> <module name="JobProgressIndicator"/> <module name="FlashChart"> <param name="width">100%</param> <param name="height">300px</param> </module> </module> </module> . . .

Third switcher child

. . . <module name="HiddenSearch" group="eps Indexed over time" autoRun="True"> <param name="search"> index=_internal source=*metrics.log component=metrics group=per_sourcetype_thruput | timechart avg(eps) by series </param> <param name="earliest">-1h</param> <module name="StaticContentSample"> <param name="text"> Some static text to describe the elements. </param> </module> <module name="HiddenChartFormatter"> <param name="chart">line</param> <param name="primaryAxisTitle.text">Sourcetype</param> <param name="secondaryAxisTitle.text">events per second</param> <param name="legend.placement">right</param> <module name="JobProgressIndicator"/> <module name="FlashChart"> <param name="width">100%</param> <param name="height">300px</param> </module> </module> </module>

101

. . .

Fourth switcher child This pattern uses HiddenSearch driven by a TimeRangePicker. Even though autoRun is set, (autoRun=true), the search does not run until given user input.

<module name="TimeRangePicker" group="Bucket Distribution"> <param name="searchWhenChanged">True</param> <param name="selected">All time</param> <module name="HiddenSearch" autoRun="True"> <param name="search">| dbinspect bins=400</param> <module name="HiddenChartFormatter"> <param name="chart">line</param> <param name="primaryAxisTitle.text">Time</param> <param name="chartTitle">Distribution of index buckets over time</param> <module name="JobProgressIndicator"/> <module name="FlashChart"/> </module> </module> </module>

Lister modules
Use lister modules to add lists to your dashboards. There are two types of listers: Entity listers Entity listers build lists from REST endpoints. Use entity listers to create lists of users, saved searches or other objects within Splunk. Search listers Search listers build lists from searches run in the module. All search listers essentially work the same -- they only differ cosmetically. If prefer to have have radio buttons, use SearchRadioLister.

Add chrome and nav

First add the chrome and nav for your view:

<view template="dashboard.html">

102

<label>Lister intro</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> <module name="TitleBar" layoutPanel="viewHeader"> <param name="actionsMenuFilter">dashboard</param> </module> . . . </view>

SearchSelectLister
This basic example uses a SearchSelectLister to generate the top ten sourcetypes with the most data indexed in the last hour. When a user clicks on a sourcetype in the list, they are redirected to the timeline view, which runs a search for just the events from that sourcetype over the past two hours.

. . . <module name="HiddenSearch" layoutPanel="panel_row2_col1" group="Drilldowns - 1" autoRun="True"> <param name="search">*</param> <param name="earliest">-2h</param> <module name="SearchSelectLister"> <param name="settingToCreate">series_setting</param> <param name="search">index=_internal</param> <param name="earliest">-1h</param> <param name="label">source</param> <param name="searchWhenChanged">True</param> <param name="searchFieldsToDisplay"> <list> <param name="label">series</param> <param name="value">series</param> </list> </param> <module name="ConvertToIntention"> <param name="settingToConvert">series_setting</param> <param name="intention"> <param name="name">addterm</param> <param name="arg"> <param name="sourcetype">$target$</param> </param> </param>

103

<module name="SubmitButton"> <param name="label">Drilldown 1</param> <module name="ViewRedirector"> <param name="viewTarget">flashtimeline</param> </module> </module> </module> </module> </module>

SearchLinkLister
This example is the same as the previous, except it uses SearchLinkLister and ViewRedirector instead of SearchSelectLister.

. . . <module name="HiddenSearch" layoutPanel="panel_row2_col2" group="Drilldowns - 2" > <param name="search">*</param> <param name="earliest">-2h</param> <module name="SearchLinkLister"> <param name="settingToCreate">series_setting</param> <param name="search">index=_internal</param> <param name="earliest">-1h</param> <param name="searchWhenChanged">True</param> <param name="searchFieldsToDisplay"> <list> <param name="label">series</param> <param name="value">series</param> </list> </param> <module name="ConvertToIntention"> <param name="settingToConvert">series_setting</param> <param name="intention"> <param name="name">addterm</param> <param name="arg"> <param name="sourcetype">$target$</param> </param> </param> <module name="ViewRedirector"> <param name="viewTarget">flashtimeline</param> </module> </module>

104

</module> </module> . . .

EntityLinkLister
This example shows how to use an EntityLinkLister module. This module lets you access configurations and knowledge objects from REST endpoints within Splunk. The below example returns a list of saved searches that are available (using Splunk's permissions system) to the current Splunk user and app. Clicking on the searches in the list runs the search in the default search (timeline) view.

<view template="dashboard.html"> <label>Lister intro</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> <module name="TitleBar" layoutPanel="viewHeader"> <param name="actionsMenuFilter">dashboard</param> </module> <module name="EntityLinkLister" layoutPanel="panel_row1_col1"> <param name="entityPath">saved/searches</param> <param name="settingToCreate">savedSearch</param> <param name="entityFieldsToDisplay"> <list> <param name="label">name</param> <param name="value">name</param> </list> </param> <module name="HiddenSearch" > <param name="search">| savedsearch "$savedSearch$"</param> <module name="ConvertToIntention"> <param name="intention"> <param name="name">stringreplace</param> <param name="arg"> <param name="savedSearch"> <param name="fillOnEmpty">True</param> <param name="value">$savedSearch$</param> </param> </param>

105

</param> <module name="ViewRedirector"> <param name="viewTarget">flashtimeline</param> </module> </module> </module> </module> </view>

Use lookups with a view

There are many ways to use Splunk's lookup feature with views. If you're not familiar with building lookup tables in Splunk, refer to the "Look up fields from external data sources" topic in the Knowledge Manager Manual. Here are a few examples of using lookups in views. There are many different ways to use lookups these examples give you an idea of the possibilities.

Lookups and dropdowns

This example shows a dashboard that has two dropdowns, one to select country and one to select a city in that country. The city dropdown is populated by a lookup called "citylookup" that dynamically populates the dropdown based on the country selection. The part of the XML that calls the lookup is within the SearchSelectLister module.

. . . <module name="SearchSelectLister"> <param name="settingToCreate">pref</param> <param name="label">City</param> <param name="applyOuterIntentionsToInternalSearch">True</param> <param name="search">| inputlookup myLookup2</param> <param name="searchFieldsToDisplay"> <list> <param name="label">city</param> <param name="value">city</param> </list> </param> . . .

Here is the code for the two dropdowns:

. . .

106

<module name="StaticSelect"> <param name="settingToCreate">area</param> <param name="label">Country</param> <param name="staticFieldsToDisplay"> <list> <param name="label">USA</param> <param name="value">USA</param> </list> <list> <param name="label">Japan</param> <param name="value">Japan</param> </list> <list> <param name="label">China</param> <param name="value">China</param> </list> <list> <param name="label">Germany</param> <param name="value">Germany</param> </list> </param> <module name="ConvertToIntention"> <param name="settingToConvert">area</param> <param name="intention"> <param name="name">addterm</param> <param name="arg"> <param name="area">$target$</param> </param> </param> <module name="SearchSelectLister"> <param name="settingToCreate">pref</param> <param name="label">City</param> <param name="applyOuterIntentionsToInternalSearch">True</param> <param name="search">| inputlookup citylookup</param> <param name="searchFieldsToDisplay"> <list> <param name="label">city</param> <param name="value">city</param> </list> </param> <module name="ConvertToIntention"> <param name="settingToConvert">pref</param> <param name="intention"> <param name="name">addterm</param> <param name="arg"> <param name="pref">$target$</param> </param> </param>

107

</module> . . . </module> </module> </module> . . .

Use one search for a whole dashboard

Sometimes you end up with a dashboard running various searches that are very similar. You can save search resources by creating a dashboard in Advanced XML that feeds all downstream panels with one single search. This topic shows how to use one base search for a dashboard, and use the HiddenPostProcess module to process the search differently for each panel. The HiddenPostProcess module allows you to reformat reporting results from a search. When you use post process, the base search must be a reporting search. Post process allows you to reformat reporting results from the search. This means you can create tables and charts according to specific criteria. For example, you can create various tables that are sorted on different columns, hide some columns, or filter rows that match some criteria. You can also do further aggregation on the original report. Note: Post process does not work for all modules. Currently it is supported for SingleValue, SimpleResultsTable, EventsViewer, and FlashChart. It is not supported in MultiFieldViewer, ResultsHeader, SimpleResultsHeader, FlashTimeline and SuggestedFieldViewer. Caution: Only use post process on a base search that is a reporting search. You can mangle your results if you do not construct your base search correctly. Some primary reporting commands are: chart top rare stats "Use reporting commands" in the User manual provides additional reporting commands with examples.

Construct your base search

When you build your base search, it is tempting to build a simple search that you pipe to the post process search in downstream panels. However, this does not work. Downstream panels must know about the fields you want to do statistics on
108

so you must include these fields in the initial search. For example, if you intend to do any count of the fields IP, user, series, and host, you need to explicitly include these fields in the base search. Then later the post process searches have all the information to process the search. For example, a good base search typically includes these clauses at the end of the search query:
| bin _time span=5min | stats count by series, eps, kb, kbps, _time

The stats count with the various group-by clauses is important. Without these specified in the search you lose the benefits of map-reduce in distributed search. You also subject results to some truncation at 10,000 rows. The bin command further optimizes the base search so instead of one row per timestamp you have one aggregate row per 5 minute bucket. The following examples show various ways to post process a single search.

Add chrome
First, add the chrome and nav for your view:

<view template="dashboard.html"> <label>Using postProcess on dashboards</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> <module name="TitleBar" layoutPanel="viewHeader"> <param name="actionsMenuFilter">dashboard</param> </module> . . . </view>

Add the base search

You can use a base search for a view with HiddenSearch or HiddenSavedSearch modules. To save even more search resources, you can use a HiddenSavedSearch that is run on a schedule. The HiddenSearch module is open in this example to add child modules for post process on each panel.

109

Note: Be careful crafting your search you need the results to include all fields on which you may want to run statistics.

. . . <module name="HiddenSearch" layoutPanel="panel_row2_col1" autoRun="True"> <param name="search"> index=_internal source=*metrics.log group=per_sourcetype_thruput | bin _time span=5min | stats count by series, eps, kb, kbps, _time </param> <param name="earliest">-6h</param> . . . . . .

Post process a search

Use the HiddenPostProcess module to process the results from your base search and feed into a results module. For example, this panel displays search results in a SingleValue module:

<module name="HiddenPostProcess" layoutPanel="panel_row2_col1_grp1"> <param name="search"> dedup series | stats count | rangemap field=count low=0-29 elevated=30-99 high=100-500 severe=501-10000 default=low </param> <module name="SingleValue"> <param name="field">count</param> <param name="afterLabel"> sourcetypes</param> <param name="classField">range</param> </module> </module>

More SingleValue modules

The following example shows two additional SingleValue modules with different post process searches.

<module name="HiddenPostProcess" layoutPanel="panel_row2_col1_grp2"> <param name="search"> stats avg(eps) | rangemap field=avg(eps) low=0-999 elevated=1000-10000 high=10000-100000 severe=100000-10000000 </param>

110

<module name="SingleValue"> <param name="field">avg(eps)</param> <param name="afterLabel">avg eps</param> <param name="classField">range</param> <param name="format">decimal</param> </module> </module> <module name="HiddenPostProcess" layoutPanel="panel_row2_col1_grp3"> <param name="search"> stats sum(kb) | rename sum(kb) as K | eval MB=K/1024 | rangemap field=MB low=0-99.99 elevated=100-499.99 high=500-4999.99 severe=5000-100000 </param> <module name="SingleValue"> <param name="field">MB</param> <param name="afterLabel">MB</param> <param name="classField">range</param> </module> </module>

Display post process searches in a chart

The following post process searches display results in a chart, using the HiddenChartFormatter and FlashChart modules.

<module name="HiddenPostProcess" layoutPanel="panel_row3_col1"> <param name="search">timechart avg(eps)</param> <module name="HiddenChartFormatter"> <param name="chart">line</param> <param name="primaryAxisTitle.text">time</param> <param name="secondaryAxisTitle.text">overall eps</param> <param name="legend.placement">none</param> <module name="FlashChart"> <param name="width">100%</param> <param name="height">400px</param> </module> </module> </module>

111

<module name="HiddenPostProcess" layoutPanel="panel_row3_col2"> <param name="search"> chart sum(kb) over series | rename sum(kb) as k | eval MB=k/1024 </param> <module name="HiddenChartFormatter"> <param name="chart">bar</param> <param name="primaryAxisTitle.text">sourcetype</param> <param name="secondaryAxisTitle.text">MB</param> <param name="legend.placement">none</param> <module name="FlashChart"> <param name="width">100%</param> <param name="height">400px</param> </module> </module> </module>

112

Customize Splunk Web

Customization options
Building dashboards, form searches, and other views in Splunk aren't the only ways to customize Splunk Web. There are more options, including: Customize the login screen Add a custom greeting to the login screen, letting users know important information about this Splunk instance. Requires minimal knowledge of HTML. Embed Splunk dashboard elements in third party software Build a report or a dashboard and then IFrame it into a different Web application. Requires some knowledge of HTML and Splunk's view system, as well as a customized login or SSO. Customize event display Change the way events display in Splunk, for example build a Twitter-like interface to display events as they stream into Splunk in real time. Requires some knowledge of HTML, Splunk's view system, and possibly JavaScript. Customize CSS Add custom CSS to a view or app. You can also overwrite the CSS for specific elements or modules in a view. Requires knowledge of CSS. We also recommend you use Firebug, or some other CSS inspector when working with CSS development. Translate Splunk Add a set of localizations for a Splunk instance. Requires a PO editor, and it may be helpful to understand how to use a PO editor for translations.

Clear Splunk-related cache after customization

If you've made changes to an app's static content while customizing Splunk Web, you can reload that content for all the users of your app using this URI:
http://localhost:8000/_bump

The _bump endpoint clears out the Splunk-related cached items in client browsers, allowing new static content to load.

113

Customize the login screen

As of Splunk 4.1, you can add a custom message to Splunk's login screen. Just add an attribute to web.conf to set a custom message. You can use HTML to format your message or add links. You must restart the splunkweb process after you make the change.

Customize the login screen

Beginning with Splunk 4.1, you can add a custom message to Splunk's login screen. Just add an attribute to web.conf to set a custom message. You can use HTML markup to format your message and add links. Restart the splunkweb process after editing web.conf to make your message visible. Note: Make sure your message appears in a single line in web.conf, as shown in the example below.

Example
Add the following key to the [settings] stanza in web.conf located at:
$SPLUNK_HOME/etc/system/local/web.conf

[settings] login_content = This is a <b>production server</b>.<br />For expensive searches try: <a href="http://server2:8080">server2</a>

Embed Splunk dashboard elements in third party software

Using HTML IFrames, you can embed Splunk views containing graphs and charts in another web application. Starting with version 4.1, Splunk supports single sign-on (SSO). Using a URI of a view configured for SSO, you can embed Splunk views in HTML documents by passing the URI as the src attribute to the <iframe> tag of a third party document.

<iframe src ="http://myhostthroughproxy:8000/en-US/app/foo/myview" width="100%" height="300">

114

This topic illustrates the basic steps for embedding a Splunk view in a third party HTML document. The example uses insecure login to simplify the explanation. For security reasons, you should implement this feature using SSO.

1. Enable insecure login

Caution: The example below uses insecure login. Anyone with access to the page can get the user credentials by viewing the link url. To enable access to the view you want to embed, configure web.conf for inseceure longin. Add the following stanza to a local version of web.conf:

[settings] enable_insecure_login = true ...

Restart Splunk to enable the configuration setting. If you're unfamiliar with how Splunk configuration files work, read the Admin manual topic "About configuration files."

2. Create the view in Splunk

Create the view you want to embed. The view should contain only the modules you want to display in your portal. Strip out any of the Splunk chrome. Note: Splunk only supports Advanced XML for embedding views in third party HTML pages. You cannot use Simplified XML. Save the view here:
$SPLUNK_HOME/etc/apps/<app_name>/local/data/ui/views/<view_name>.xml

Example view Here's an example view with the Splunk chrome stripped out. It shows only a chart driven by a hidden search.

<view template="dashboard.html"> <module name="HiddenSearch" autoRun="True" layoutPanel="panel_row1_col1"> <param name="search">sourcetype=access_common | timechart span=5m count</param> <param name="earliest">-24h</param>

115

<module name="HiddenChartFormatter"> <param name="chart">line</param> <param name="primaryAxisTitle.text">Time</param> <param name="legend.placement">bottom</param> <param name="chartTitle">Stuff past 24 hours</param> <module name="JobProgressIndicator"/> <module name="FlashChart"/> </module> </module> </view>

After editing the view, refresh it by loading this URI:

https://localhost:8089/servicesNS/<user_name>/<app_name>/data/ui/views?refresh=1

3. Create an IFrame in an HTML document

Embed the view in an IFrame of the HTML document using the insecurelogin endpoint as the src attribute to the <iframe> tag. The endpoint contains parameters for username, password, return_to. Replace username and password with the appropriate login values. URI escape the value of the return_to parameter. Here's a link to a third party URI encoder.

http://splunkserver:8000/account/insecurelogin?username=admin&password=changeme&return_t

Example HTML Here's an example of adding an IFrame into an HTML document:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title>Splunk Stuff</title> </head> <body>

<h1>Hey Look At My Pretty Pictures!</h1>

<iframe src ="http://myhost:8000/account/insecurelogin?username=test_user&password=changeme&return_t width="100%" height="300"> <p>Your browser does not support IFrames.</p> </iframe>

116

</body> </html>

Customize event display

There are several ways you can customize how events appear and behave in a view: Change formatting and add icons or decorations to the text Use JavaScript to change behavior of displayed events Use CSS to change the presentation Use HTML to change the structure For example, use custom event renderers to flag all compliance events as NOT OK and display a red exclamation point next to them. If you're not familiar with event types, you can read about them in the Event types and transactionsl chapter of the Splunk Knowledge Manager manual.

Configuration
This section shows you several ways to customize the appearance of events. 1. Create an event type that includes the data to which you want to apply a custom renderer. For information on building event types, see "defining event types" in the Knowledge Manager Manual. Place the event type in the app directory in which you are working:$SPLUNK_HOME/etc/apps/<app_name>/local/eventtypes.conf 2. Add a mapping to event_renderers.conf, located here:
$SPLUNK_HOME/etc/apps/<app_name>/local/event_renderers.conf

3. Add custom CSS, HTML or JavaScript to your app to determine the presentation, structure or behavior of events. Place CSS and JavaScript here:
$SPLUNK_HOME/etc/apps/<app_name>/appserver/static

Place HTML here:

$SPLUNK_HOME/etc/apps/<app_name>/appserver/event_renderers/

117

event_renderers.conf Add an event_renderers.conf file to the following location to link your HTML template to the event type you want to style:
$SPLUNK_HOME/etc/apps/<app_name>/local/event_renderers.conf

Here's an example event_renderers.conf file that creates three different event renderers.

[event_renderer_1] eventtype = hawaiian_type priority = 1 css_class = EventRenderer1 [event_renderer_2] eventtype = french_food_type priority = 1 template = event_renderer2.html css_class = EventRenderer2 [event_renderer_3] eventtype = japan_type priority = 1 css_class = EventRenderer3

To write your own event renderers, add stanzas to event_renderers.conf:

Name
[<stanza_name>] eventtype = eventtype template = valid html

Description
Unique name for the stanza, which can be anything you want. Specify the event type name from eventtypes.conf. Write the template and place it into the app's event_renderers

directory:

($SPLUNK_HOME/etc/apps/<app_name>/appserver/event_renderers).
Set the priority for this event renderer to show on this event type.

priority = positive integer

An event can have multiple event types, use the priority key to control load ordering. Highest number takes precedence. The default renderer has a priority of 100.
CSS class name suffix to apply to the parent event element class attribute. This can be any valid css class value.

css_class = CSS class name

118

The value is appended to a standard suffix string of splEvent-. A css_class value of foo results in the parent element of the event having an html attribute class with a value of splEvent-foo (class="splEvent-foo"). You can externalize css style rules for this in:
$SPLUNK_HOME/<app_name>/appserver/static/application.css.

For example, to make the text red add the following to your app's application.css:
.splEvent-foo { color:red; }

Add custom HTML

Add custom HTML to set up a new event renderer -- specifically, to change the order and structure of events displayed in a view. Add your HTML file to the following directory:
$SPLUNK_HOME/etc/apps/<app_name>/appserver/event_renderers.

Make sure you reference your HTML file by name in event_renderers.conf, with the template attribute. The custom HTML you build inherits from the default template. The default template for displaying search results is located here:

$SPLUNK_HOME/share/splunk/search_mrsparkle/modules/results/EventsViewer_default_renderer

To inherit the default file, add this to your HTML:

<%inherit file="//results/EventsViewer_default_renderer.html" />

Customize the display structure of events by overriding the settings from the default renderer and creating a custom layout. For example:

## override <%def name="event_raw(job, event, request, options, xslt)"> <a href="http://www.yelp.com/search?find_desc=french&find_loc=San+Francisco%2C+CA&ns=1&rpp= target="_blank">French restaurants in San Francisco</a> <img src="${make_url('/static/app/stubby/event_renderer2.jpg')}" /> </%def>

119

## remove <%def name="event_fields(job, event, request, options)"> </%def> ## parent <%def name="event_time(job, event, request, options)"> ${parent.event_time(job, event, request, options)} </%def> Here is the stanza in event_renderers.conf for this event renderer:

[event_renderer_2] eventtype = french_food_type priority = 1 template = event_renderer2.html css_class = EventRenderer2

Add a custom CSS file

Create an application.css file for an app at the following location:
$SPLUNK_HOME/etc/apps/<app_name>/appserver/static

The rules in this CSS file apply only to the app in which the CSS file is located. For more information about adding CSS to Splunk apps in general, see the Create custom CSS topic in this section. Here's an example application.css file that inserts a background picture and changes the size of the events:

.splEvent-EventRenderer1 { background:url(event_renderer1.jpg) 100px 0px no-repeat; height:60px; } .splEvent-EventRenderer1 .event, .splEvent-EventRenderer1 .fields { display:none; } Here is the stanza in event_renderers.conf for the CSS class defined in application.css:

[event_renderer_1] eventtype = hawaiian_type priority = 1 css_class = EventRenderer1

120

Add custom JavaScript

Add JavaScript to a view to specify custom actions additional functionality on specific events. To add JavaScript, create an application.js file in the following location:
$SPLUNK_HOME/etc/apps/<app_name>/appserver/static

This file contains custom JavaScript to apply to an app. Bind the JavaScript to the CSS class in the event_renderers.conf file:

$(document).bind("splEvent-<css_class_name>", <js function name>);

The following JavaScript code creates a link to search Google in Japanese from events in Splunk.

function eventRenderer3Handler(event, options){ var type = options.nativeEvent.type; var target = options.nativeEvent.target;

//cancel all mouse hover behavior if(type=="click"){ var q = encodeURIComponent($(options.nativeEvent.target).html()) window.location.href = "http://www.google.co.jp/search?hl=ja&source=hp&q="+q+"&btnG=Google+%E6%A4%9C% options.nativeEvent.preventDefault(); } } $(document).bind("splEvent-EventRenderer3", eventRenderer3Handler);

Here is the stanza in event_renderers.conf for the custom JavaScript event behavior:

[event_renderer_3] eventtype = japan_type priority = 1 css_class = EventRenderer3

Add Web resources to your view

You can use Splunk's Web resource modules to add IFrames or HTML to a view.

121

Add HTML
Use the ServerSideInclude module to add HTML to a view. 1. Create an HTML file, for example foo.html here:
$SPLUNK_HOME/etc/apps/<appname>/appserver/static

2. Add the Web content into the file. 3. Update the Advanced XML for the view to include the ServerSideInclude module:

<view> <module name="ServerSideInclude"> <param name="src">foo.html</param> </module> </view>

Note: The Advanced XML implementing the view should be located here:
$SPLUNK_HOME/etc/apps/<appname>/default/data/ui/views/<view_name>.xml

4. Access the view in a browser

http://<hostname>:<port>/app/<appname>/<view_name>

Add images To add an image use the Mako template utility function make_url in the HTML:

<img src="${make_url('/static/app/<app_name>/<image>.png')}" />

Add links You can create dynamic and static links from the HTML template included using the ServerSideInclude. Dynamic: <a href=?${make_url(?/manager/foo/bar?)}?>click me</a> Static: <a href=?/manager/foo/bar?>click me</a>

122

The dynamic version uses the make_url method, which properly qualifies the URL to the current locale and inserts relevant modifiers for static content or proxied instances. You can also use make_urlto insert runtime information (such as the app name). In the following example, you pass a list as the first argument, not a plain string.

<a href=?${make_url([?manager?, APP[?id?], ?foo?, ?bar?])}?>click me</a>

Here are some common variables available from the HTML template system: current namespace: APP[?id?] current app friendly label: APP[?label?] current view id (what appears in the URI): VIEW[?id?] current view label: VIEW[?label?] These variables are available if you link to a view with an s= saved search name: current saved search name: SAVED['name'] current viewstate ID associated with saved search: SAVED['vsid'] Style your HTML document Use CSS to style your HTML document. Once you've created an HTML document, you can create a corresponding CSS file to specify its style. Splunk's CSS implementation is not scoped. If you add CSS to a page, make sure you scope the class names. Splunk does not recommend applying styles to global selectors. Instead, use class selectors to control scope and possible collisions. Global selectors: body {background:pink;} Class selectors (recommended): .myclass {background:pink;} Here are some steps you can follow to learn more about CSS and apply them to
123

an HTML document in Splunk. 1. Familiarize yourself with CSS. If you're not familiar with CSS, check out this CSS resource. Specifically, familiarize yourself with how a CSS class selector works. In an HTML document, a class selector is the XHTML element to which you apply CSS styles. For example:

<div class="bar"> w00t! </div>

Define a class selector in CSS using the "." sign followed by the value of the class attribute (no space between the "." and the name of the class). For example:

.bar { background:pink; }

You can use the same class name within an XHTML document multiple times. 2. Create a CSS file, for example foo.css, at the following location:
$SPLUNK_HOME/etc/apps/<appname>/appserver/static

3. Add a rule to the CSS file:

.bar { background:pink; }

Any element with a matching class attribute of bar now has a pink background.

<div class="bar"> <h1>I have a pink background now!</h1> </div>

Add an IFrame
Use the IFrameInclude module to add an IFrame into a view. 1. Determine the URI you want to load into an IFrame.
124

2. Update the view XML to include the IFrameInclude module, with a link to the URI:

<view> <module name="IFrameInclude"> <param name="src">myawesomewebsite.com</param> </module> </view>

3. (Optional) set the height. This example sets the height to 42 pixels.

<view> <module name="IFrameInclude"> <param name="src">myawesomewebsite.com</param> <param name="height">42/param> </module> </view>

4. (Optional) Add a parameter to IFrameInclude that tests if the URI exists:

<view> <module name="IFrameInclude"> <param name="src">myawesomewebsite.com</param> <param name="check_exists">True</param> </module> </view>

Customize CSS
You can make any number of changes to Splunk Web's appearance by customizing the CSS. You can change display options such as background colors, buttons, navigation, menus, and so on. To change the layout of a page, build a view. Start with the simple dashboard described in the Build dashboards section of this manual. To change which elements are displayed in a page, add different modules to your view. Splunk's default CSS is defined in default.css, which is located here:
$SPLUNK_HOME/share/splunk/search_mrsparkle/exposed/css/skins/default/

You can make changes to the CSS for your entire app, for a specific view, or for any HTML you have added to your view. If you want to update a given style or class for your app, look for it in default.css. This file is thoroughly commented
125

and organized to serve as a reference for Splunk Web's default classes. You can also use a web inspection tool to find the class you want to change. Splunk recommends using Firebug in Firefox. Firebug lets you inspect the elements of a page and pinpoint the classes whose style you want to change. Using Firebug, you can also try out different CSS settings before making any changes.

Configure CSS for an app

Each app's directory can contain an application.css file that defines the CSS for the entire app. The application.css file has a higher priority than any of Splunk's other CSS files anything defined in application.css overwrites the default settings. Each module has its own CSS file that defines its layout and other properties. Within application.css you can overwrite CSS specifications for several modules simultaneously. 1. Create application.css in the following location:
$SPLUNK_HOME/etc/apps/<appname>/appserver/static/

2. Look for the style to override in default.css or by using a web inspection tool (such as Firebug). 3. Add an entry to your application.css indicating the class you want to change and the style you want to set. 4. Save your file. Restart Splunk Web, then refresh the browser page in which you are you viewing your app. The CSS changes are picked up on refresh. Note: For subsequent changes to application.css, you do not have to restart Splunk Web. You can just refresh the browser page in which you are viewing your app.

Configure CSS for a view

You can include any CSS file in a view by referencing the CSS file in the <view> tag at the beginning of the view's XML. Place the CSS file in the app's static directory:
$SPLUNK_HOME/etc/apps/<appname>/appserver/static/

126

For example, add the following to a dashboard's view XML file to import the mystyles.css style sheet:

<view template="dashboard.html" stylesheet="mystyles.css">

Or you can add the view name before any class you want to style in the CSS file. If you've added a web resource, import the CSS file into your HTML.

Add images
To add images, place them in the ../appserver/static/ directory alongside the application.css file. You can reference them directly in the CSS file. The following example adds a new header, myHeader.png, and a new logo, myLogo.png. These files are in the folloing location:
$SPLUNK_HOME/etc/apps/<app_name>/appserver/static

If you want to reference an image file in a different directory, the path is relative to the ../appserver/static directory.

.appHeaderWrapper { background: url(myHeader.png) repeat-x; } .appLogo { background: url(myLogo.png) no-repeat 0 0; }

Example
The samples app provided with your Splunk installation overwrites the built-in CSS with the following styles from its application.css:

/* * Top app banner section */ .AccountBar { background-image: url(/static/app/samples/samples_header.png); background-repeat: no-repeat; background-color: #79a60b; height: 140px;

127

} .AccountBar .appLogo, .AccountBar p.appName { display: none; } .AccountBar .accountBarItems { background-color: #000; opacity: .5; filter: alpha(opacity=50); } /* * view menu system */ .AppBar { font-family: Arial Black, Arial, sans-serif; font-size: 18px; font-variant: small-caps; } .AppBar a { color: #f3df00 !important; } .AppBar a:hover { color: #6ad7ff !important; } /* * Body content */ body { background-image: url(/static/app/samples/body_bg.png); background-repeat: repeat-x repeat-y; }

Translate Splunk
Splunk supports the internationalization and localization of strings within the product. Use Splunk's localization tools to: Translate text generated by Python code, JavaScript code, views, menus and Mako templates. Set language/locale specific alternatives for static resources such as images, CSS, other media. Create new languages or locales. Format times, dates and other numerical strings.
128

When you log in to Splunk, Splunk uses the language that your browser is set to. If you'd want to switch languages, change your browser settings. Splunk detects locale strings. A locale string contains two components: a language specifier and a localization specifier. This is usually presented as two lowercase letters and two uppercase letters linked by an underscore. For example, en_US means US English while en_GB means British English. When looking for a suitable translation, Splunk first tries to find an exact match for the whole locale, but falls back to just the language specifier if the entire setting is not available. For example, translations for fr answer to requests for fr_CA and fr_FR (French, Canada and France respectively). The user's locale also affects the formatting of dates, times, numbers, and other localized settings. Different countries have differing standards on how to format these entities.

Configuration
Splunk uses the gettext internationalization and localization system. When using gettext, you typically use an editor to create, generate, and edit the files used to localize strings in an application. Splunk recommends Poedit, a free, open source editor for localization. To translate Splunk, follow these directions: 1. Create a directory for the locale. For example, to create the fictional locale mz, create the following directory:

$SPLUNK_HOME/lib/python2.6/site-packages/splunk/appserver/mrsparkle/locale/mz_MZ/LC_MESS

2. Load the following messages.pot file into your PO editor.

$SPLUNK_HOME/lib/python2.6/site-packages/splunk/appserver/mrsparkle/locale/messages.pot

3. Use the PO editor to translate any strings you want to localize. Save the file as messages.po in the directory you created in step 2. The PO editor also saves a messages.mo file, which is the machine readable version of the PO file. 4. Restart Splunk. There are no other configuration files to edit. Splunk detects the new language files when it restarts.

129

Localization files Splunk stores localization information at the following location:

$SPLUNK_HOME/lib/python<version>/site-packages/splunk/appserver/mrsparkle/locale/...

messages.pot: Holds the strings to translate. Use a PO editor to edit these files. <locale_string>: The directory containing localization files for the locale specified by <locale_string> (for example, ja_JP). <locale_string>/LC_MESSAGES/messages.po: Contains the source strings specified for localization in messages.pot. Using a PO editor, provide the translations for these strings. <locale_string>/LC_MESSAGES/messages.mo: A machine readable version of messages.po that Splunk uses to find translated strings. The PO editor creates this for you when it creates the messages.po file. Localize dates and numbers You can format numbers and dates to the standards of a locale without having to translate any text. For this scenario, copy the contents of the en_US directory to the target locale directory. For example, to enable localization of numbers and dates for the it_IT locale (Italian Italy), copy the contents of the following directory:
$SPLUNK_HOME/lib/python2.7/site-packages/splunk/appserver/mrsparkle/locale/en_US

and place them here:

$SPLUNK_HOME/lib/python2.7/site-packages/splunk/appserver/mrsparkle/locale/it_IT

Translate Apps
You can also use gettext to translate apps. However, most apps must be translated in their own locale subdirectory. Apps that ship with Splunk are automatically extracted and their text included in Splunk's core messages.pot file. There's no need to handle them separately.

130

To extract the strings from an installed application, ready to be translated in a PO editor, run the following command from Splunk's command line:
splunk extract i18n -app <appname>

This creates a locale/ subdirectory in the app's root directory and populates it with a messages.pot file. Then, follow the steps above to translate the strings within the app. When using views from a different app, the new messages.pot file contains the strings for these views.

Locale-specific resources
Splunk stores static resources such as images, CSS files, and other media as subdirectories at the following location:
$SPLUNK_HOME/share/splunk/search_mrsparkle/exposed/

When serving these resources, Splunk checks to see whether a locale-specific version of the resource is available before falling back to the default resource. For example, if your locale is set to fr_FR, Splunk searches for the logo image file in the following order: exposed/img/skins/default/logo-mrsparkle-fr_FR.gif exposed/img/skins/default/logo-mrsparkle-fr.gif exposed/img/skins/default/logo-mrsparkle.gif Splunk follows the same path to load HTML templates (including any views) that define each page in the UI. This can be useful for languages that require a modified layout that CSS alone can't accommodate (right to left text for example).

Plot search results on a map

Use these instructions to add a map to your view. You must first download and install the Ammap app from Splunkbase to get this working. These are the basic steps for building a map view: 1. Install the Ammap app: this contains all the supporting libraries you'll need to build your own map. 2. Make a search with the fields required to build the map. 3. Invoke the mapit script.
131

4. Put your map into Splunk Web by building a view.

Install the Ammap app

The app can be found on Splunkbase here. Install the app the same way you install any other app -- either download it through Launcher, or unzip it into $SPLUNK_HOME/etc/apps/. Also, you will need to install the supporting MAXMIND app.

Make a search
Once you've installed the app, you'll notice an empty map on the default landing page of this app. That map is set to be populated by your data on an hourly basis, mapping the top 100 public IP addresses in your instance that are recorded in the last hour. If you are running Splunk Free you will need to manually populate this map. To make sure everything is working correctly, run the following search:
* | rex "(?<ip>\d+\.\d+\.\d+\.\d+)"| search ip!=192.168* ip!=0.0.* ip!=10.* | stats count by ip | head 100 | eval count_label="Event" | eval iterator="ip" | eval iterator_label="IP" | eval movie_color="#FF0000" | eval output_file="home_threat_data.xml" | eval app="amMap" | lookup geoip clientip as ip | mapit

If you get back a result count from the above search you should see a populated map. If you do not see anything remove the | mapit part of the search and run it again to make sure you are getting back a results table with populated geo info. If a table is returning but the geo fields are empty you have most likely do not have any public IPs addresses in your data for the ip2geo translation to operate on. Build your own search Now, you can build your own search and save it to run on a schedule, or when you load the view. First, make sure you have a field called IP. You can either do this by creating a field extraction to save your field, or use the rex expression to extract the field on the fly. It's best practice to create an IP field, either client_ip, src_ip, dest_ip or some other field containing only IP address data. This example searches apache data then applies a filter to remove any internal IP addresses from the search:
sourcetype=apache ip!=192.168* ip!=0.0.* ip!=10.*

This part of the search represents the results you are interested in. You may want to add additional values to have results that represent a particular threat,
132

web traffic or any other data you would like to see represented geographically on the flash map. Next, create a stats table for that IP field. For example:
| stats count by ip

The next step is to create the required fields necessary for the map_results.py script to run. For example: | eval count_label="Event" | eval iterator="ip" | eval iterator_label="IP" | eval movie_color="#FF0000" | eval output_file="home_threat_data.xml" | eval app="amMap"

These eval statements create the REQUIRED fields for the map to work: count_label: what to display upon mouseover (i.e. Security Events, BotNet events, etc.). In the example above, this is set to "Event." iterator: what the script should iterate on. In the example above, this is set to "ip," meaning the script will count all the unique IP addresses for each location. iterator_label: give a pretty print name to the iterator. In the example above, this is "IP." This label appears in the mouseover for a location as Unique IP(s). movie_color: this is the color of the marker on the map. The example above uses eval and sets the marker to one static color. If you'd like to set a dynamic range of colors, use the rangemap command. app: specify an app to write the map data to. output_file: name the XML file where the map data will be written to. The output file will go into the $SPLUNK_HOME/etc/apps/<app_name>/appserver/static/xml_out.

Invoke the script

Now that you have the search down there are a couple of ways to get the map output. Set up an alert action If you have a Splunk Enterprise License you can schedule a search and use the alert action map_results.sh. You will need to copy the sh file from the bin/alert_scripts directory of this app into $SPLUNK_HOME/bin/scripts/

133

Use a search command Another option to map things on the fly is to use the mapit search command that ships with the Ammap app. The command is exported globally and can be called from any app. Construct a search as described above, and then pipe it to mapit to generate a map on the fly. You can also schedule this search.

Add your map to Splunk Web

You must first copy over various assets from the Ammap app into your app directory. Copy:
$SPLUNK_HOME/etc/apps/amMap/appserver/static/ammap/

to
$SPLUNK_HOME/etc/apps/<your_app>/appserver/static/ammap/

Create an empty xml_out directory within the static/ directory to store the results of your search. Copy:
$SPLUNK_HOME/etc/apps/amMap/appserver/static/ammap.html

to
$SPLUNK_HOME/etc/apps/<your_app>/appserver/static/ammap.html

Next, edit the HTML. You only need to specify what app you want to generate your map in by setting the correct app in the appropriate HTML file. If you're making a threat map, use threat_map.html, if you're creating a traffic map, use traffic_map.html. Set any instance of /static/app/ammap/ to the path of the app you're working in. For example, change /static/app/ammap/ammap/ to your app's path. The code you're interested in is below:

var so = new SWFObject("/static/app/ammap/ammap/ammap.swf", "ammap", "100%", "350", "8", "#FFFFFF"); so.addVariable("path", "/static/app/ammap/ammap/"); so.addVariable("data_file", escape("/static/app/ammap/xml_out/home_threat_data.xml")); so.addVariable("path", "/static/app/ammap/ammap/");

134

so.addVariable("settings_file", escape("/static/app/ammap/ammap/ammap_settings.xml"));

Now, build a view in your app that includes the HTML in a ServerSideInclude module. For example:

<view template="dashboard.html"> <label>AMMAP View</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> <module name="TitleBar" layoutPanel="viewHeader"> <param name="actionsMenuFilter">dashboard</param> </module> <module name="SearchBar" layoutPanel="splSearchControls-inline"> <param name="useAssistant">true</param> <param name="useTypeahead">true</param> <param name="useOwnSubmitButton">False</param> <module name="TimeRangePicker"> <param name="selected">All time</param> <param name="searchWhenChanged">True</param> <module name="SubmitButton"> <param name="allowSoftSubmit">True</param> <module name="ViewRedirector" layoutPanel="viewHeader"> <param name="viewTarget">flashtimeline</param> </module> </module> </module> </module> <module name="ServerSideInclude" layoutPanel="panel_row1_col1"> <param name="src">threat_map.html</param> </module> </view>

Debugging
The map_results log file is indexed into the Splunk _internal index. You can view that log with the following search:
index="_internal" source="*ammap_map_results.log"

Additional debugging statements can be added by un-commenting anywhere you see logger() being called. Also, you can call the script from the CLI and pass a search ID. This is helpful for catching exceptions thrown by the script. The usage for this is like so:
135

$SPLUNK_HOME/bin/splunk cmd python $SPLUNK_HOME/etc/apps/amMap/bin/map_results.py <sid>

136

Build apps
Apps and add-ons: an introduction
Apps and add-ons extend Splunk with pre-built knowledge and new capabilities. Apps contain a user interface that you often customize according to the capabilities of the app and the needs of your users. Add-ons are smaller, reusable components much like an app, but do not contain a navigable UI. Any member of the Splunk community can build an app or add-on and share it with other Splunk users, usually by uploading it to Splunkbase. Before you build an app or add-on, it's a good idea to familiarize yourself with the Splunk app mental model. Splunk apps and add-ons are made of objects and configurations. Read on for a description of these data types, as well as information about app structure and Splunk's permissions system.

Why apps and add-ons?

Apps and add-ons let you construct and maintain different environments on top of one Splunk instance. One Splunk installation can run multiple apps. This way, any number of different groups can use the same Splunk instance without running into each other. For example, you can make an app for all your helpdesk employees and a different app for your marketing department. When a user in the helpdesk role logs into Splunk, they see a customized environment that helps track support cases. When a user from the marketing group logs in, they see the business analytics app, where they can run reports on business trends and web activity. Meanwhile, the Splunk admin can maintain all the installed apps, as well as build and install apps. You can build apps, to create separate contexts for different groups of Splunk users within an organization: one app for troubleshooting email servers, one app for analyzing business trends, and so on. This way, everyone uses the same Splunk instance, but sees only data that is relevant to their interests. Some groups can access multiple apps while others may see only one. apps are highly customizable, so you get to decide who sees what and how it works.

137

What is an app?
At a high level, you can think of an app as a workspace that solves a specific use case. An app can extend Splunk with new navigable views that report on particular kinds of data, can provide tools for specific use cases and technology, and are often developed for a specialized user role. For example, a helpdesk app can contain customized views and dashboards to track and diagnose support cases. Apps can range in complexity from new views or dashboards to an entirely new program using Splunk's REST API. A single Splunk installation typically contains several apps, such as the Search app provided with Splunk, an OS app (such as *nix) downloaded from Splunkbase, and custom apps that you build. Apps: Contain at least one navigable view. Can be opened from the Splunk Home Page, from the Splunk App menu, or from the Apps section of the Splunk Manager. Focus on aspects of your data. Are built around use cases. Support diverse user groups and roles. Run in tandem. Contain any number of Splunk configurations and knowledge objects. Are completely customizable, from front to back end. Can include Web assets, such as HTML, CSS and JavaScript.

What is an add-on?
An add-on is a reusable Splunk component much like an app, but does not contain a navigable view. You cannot open an add-on from the Splunk Home Page or the Splunk App menu. Add-ons can include any combination of custom configurations, scripts, data inputs, custom reports or views, and themes that can change the look and feel of Splunk. A single add-on can be used in multiple apps, suites, or solutions.

What's in an app?
Apps are made up of knowledge objects and configuration, anything from custom UI to custom input scripts.

138

Customizable UI Use Splunk's app framework to make custom UIs for different users and use cases. Splunk's UI (Splunk Web) is completely customizable, so you can make small changes to a single page in Splunk Web or completely redesign Splunk's UI.
Change Splunk's appearance

Change everything from the menu layout to background images, build your own custom HTML and JavaScript into your app. Learn more about what you can do with customization options.
Build your own pages in Splunk

There are several option for building your own custom pages in Splunk: Build a dashboard Dashboards are useful for presenting visual summaries of various searches. Learn more about dashboards. Build a form search Form searches let you restrict the search interface to present one or more search boxes with more complex searches running behind the scenes. There's more information at Introduction to forms. Build an advanced view Advanced views give you view customization options in Splunk Web beyond what is available in the simplified XML syntax. Learn more about advanced views. Customizable back-end Customize your app further by collecting and managing specific types of data. Add knowledge to your data to facilitate your users and use cases. Most of Splunk's configurations are now available through Splunk Web's Manager interface. Through Splunk Manager, you can: Add inputs and indexes to collect and store your data. Add knowledge through objects such as saved searches, reports and fields. Set permissions on apps and objects. Create and edit new views and navigation menus. Add users and roles and scope them to your app. And more.

139

Knowledge objects

Knowledge objects are all configurations within Splunk that are permissionable and controlled via Splunk's access control layer. Splunk knowledge objects include: Saved searches Event types Dashboards, form searches and other views Fields Tags Apps Field extractions Lookups Search commands To learn more about knowledge objects in general, see the Knowledge Manager Manual. To learn more about how to use knowledge objects in your app, see Step 4: add objects. To learn more about setting permissions on objects, see Step 5: set permissions.
Configurations

Configurations are global in scope and do not have permissions applied to them. All configurations are available at the system level. They can be managed through Manager and are only available to users with admin privileges. Configurations include: Users Roles Authentication Distributed search Inputs Outputs Deployment License Server settings (for example: host name, port, and other settings) To learn more about configurations in general, see the Splunk Admin Manual. To learn more about how to use configurations in your app, see Step 3: add configurations.

140

App directory structure All apps live in a custom directory, within $SPLUNK_HOME/etc/apps. Typically, you do most of your work within the Default/ directory, and its subdirectories: Default/ Put all the Splunk configuration files your app needs in Default. All Apps must have an app.conf. Some may also contain savedsearches.conf, inputs.conf, or other relevant configuration files. Read more about configuration files in Step 3: add configurations. Within the Default/ directory, there are more subdirectories for configuring the UI. These are contained within $SPLUNK_HOME/etc/apps/<App_name>/default/data/UI/, and include: Nav/ This directory contains only default.xml. Use this file to build navigation for your app. Views/ Put all the views you create in this directory. Use views to build dashboards, form searches and other advanced views. The other subdirectories in your app are: Appserver/ Add images, CSS or HTML to your app in the appserver/static directories within your app's directory. Use the static directory to store any Web resources your app requires, or if you're customizing Splunk Web. Bin/ Store any custom scripts for your app in the bin directory. For example, any search scripts you may write. Local/ Developers don't configure anything within the local dir. It is there for app users and admins to overwrite any default configurations. Local/ mimics the same
141

structure as Default/ Metadata/ Store app objects permissions here in the local.meta or default.meta files. Learn more about these files in Step 5: set permissions.

Step 1: Getting started

You have a lot of options when building your app. First and foremost, decide on your app's scope and use case. To get you started, here's a high level view of how to build an app for Splunk. For more specifics, read through each step and the how-tos in this section.

What you need

You can jump right into building an app with the app builder in Splunk's Manager interface, but you may also want to carefully plan out and build your app. If so, here are a few things you might want to set up before you get started. An editor for XML, CSS, and HTML files You can build apps entirely within Splunk Web, but if you want to create custom XML, CSS or HTML you may want to use an editor designed for those formats. Starting with Splunk 4.3, Splunk provides an XML editor available from Splunk Web. This editor provides syntax highlighting and auto-indent features. This editor opens when you edit XML files from Splunk Web. For all formats, Splunk recommends Komodo Edit -- it's free, cross-platform, and supports text highlighting for a variety of standard formats. Useful, relevant data Index some data to showcase in your app. Build knowledge around this data and present this knowledge through your app's UI. For example, if you're building an app for your custom firewall data, set up a data input to index this data. You can optionally set up a custom index to keep this data segregated from the rest of your Splunk install.

142

 Splunk knowledge objects Objects include data visualization components, like saved searches and reports, as well as UI components to display these, such as views and dashboards. Web development tools These browser dependent tools help you troubleshoot your JavaScript, CSS and HTML. If you're doing advanced customization, we strongly suggest you use one of these tools. If you're using Firefox, you'll want to check out Firebug. IE8 has a built-in console in the Tools menu, under Developer Tools. Chrome has an Inspect Element option that is useful for inspecting CSS, HTML, JavaScript, and other resources. Safari 4 also has a built-in console. First you have to enable the develop menu for the menu bar under Preferences > Advanced Tab. Check Show Developer Menu in menu bar. Then select Develop > Show web inspector.

App building overview

From a high level, app building follows these steps. 1. Get started: What is your use case and how do you want to solve it? Decide what data you want to work with and how you're going to get it into Splunk. Storyboard your app so you know who will use it and how they'll navigate around. 2. Create your app workspace: Use app builder to create your app workspace. A more in-depth description of this step is located in this manual as Step 2: create your app. 3. Add configurations to your app: Add custom configurations to index and process your data. App configurations include data inputs, indexes, users and roles.

143

 A more in-depth description of this step is located in this manual as Step 3: add configurations. 4. Create objects for your app: Add saved searches and reports that display the information you're interested in. Add dashboards and other views, and put your saved searches and reports in your dashboards. A more in-depth description of this step is located in this manual as Step 4: add objects. 5. Set access controls and permissions for your app users: Set permissions to allow your app users to add knowledge objects to your app. Learn more about how object permissions work. Optionally add users and roles for your app. Create a role for the users you want to access your app. For example, if you're building an app for your web developer team, create a role called "Web_Developer" and add all your users into this role. A more in-depth description of this step is located in this manual as Step 5: set permissions. Read more about how to create roles 6. Build navigation Build navigation for your app so users can easily navigate to dashboards, reports, saved searches and other views. A more in-depth description of this step is located in this manual as Step 6: build navigation 7. Optionally add a setup screen for your app. If your app requires user input to be configured, add a setup screen. Read more about this in Configure app setup screen. 8. Optionally package your app for distribution on Splunkbase. Splunkbase, Splunk's community for app developers is located here. You can package your app for distribution on Splunkbase. A more in-depth description of this step is located in this manual as Package your app.
144

Step 2: Create your app

Splunk's app framework works from a specific directory structure. You can create the directory structure by hand within your $SPLUNK_HOME/etc/apps directory. However, you can also use Splunk's app builder to create and customize your app workspace. App builder creates the directory structure for you, as well as the app.conf configuration file that registers your app with your Splunk server.

Use app builder

App builder is available from Splunk Manager. To use app builder in Splunk Web, follow these instructions: 1. Log in to Splunk Web and navigate to Manager > Apps. 2. Click Create app. 3. Specify the following in the Add new panel. Name: The name for your app. The name maps to the label setting in app.conf and is the name that appears in Launcher and the App drop-down menu in Splunk Web. Folder name: The name to use for the directory in $SPLUNK_HOME. Visible: Apps containing views should be marked visible. Description: A description of the app that appears on the Splunk Home page. Template: Splunk provides the sample_app and barebones app templates. sample_app includes sample views and saved searches. barebones just provides the app directory structure and an app.conf file. You can add additional customized templates. Upload asset: Add any image, HTML, JavaScript, CSS, or other asset to your app. You can only upload one file from this panel. 3. Save your app. You do not have to restart Splunk before your app is available, but you may need to restart Splunk to load configurations. 9. Continue building out your app in Step 3: add configurations.
145

Step 3: Add configurations

Configurations specify behavior for your app. For example, what kind of data do you want to input into your app? What kind of access controls do you want to set up for your app? Configurations include any Splunk config files that structure how your app interacts with the Splunk server. To set up how your app looks (that is, specify app knowledge), proceed to Step 4: add objects. This section is an overview of the major configuration options available. You can find additional information on configurations in the Splunk Admin Manual and Splunk Getting Data In Manual. Once you've set up custom configurations, you may want to configure an app setup screen to expose relevant app configurations to users setting up your app. Configurations set up the data layer of your app. The data layer includes data inputs and other configurations that specify how Splunk should treat your data. This way, you can customize what data is available to your app, how it gets into your Splunk instance, and how Splunk stores it. Many, but not all, apps for Splunk contain back-end configurations. You can use any configuration from the set of configuration files, described in About configuration files in the Admin manual. Put the configuration files in your app's directory to package them with your app. Note that all configurations are global, meaning they are by default available to all apps. You may segregate configurations by placing them in your app's directory. However, any data inputs indexed into Splunk are always available to other apps.

App settings
The most important configuration file for app developers is app.conf. This file is created by app builder, but you may need to edit it to customize your app. Basic configuration To enable your app and make it in Splunk Web add the following stanza to the app.conf file here:
$SPLUNK_HOME/etc/apps/<app_name>/default/app.conf:

[ui]

146

is_visible = true label = <name>

The stanza must have the [ui] header. Set is_visible to true if you want your app to appear in the drop-down menu in Splunk Web. Set label to the name of your app. Add your app to the app launcher Add the following stanza to app.conf to add your app into the app launcher. Fill out each attribute as described.

[launcher] author=<author of app> description=<textual description of app> version=<version of app>

Make sure you add an the following images to your app's ../appserver/static/ directory: appIcon.png: This icon appears in the launcher to the left of the app name. App icons must be 36x36 pixels, in PNG format. screenshot.png: This screenshot appears in launcher above your app description. Screenshots should be a minimum of 623 x 350 pixels in PNG format. If they are larger, they are automatically cropped. Update content for a new version Splunk's appserver caches all static assets in your app (such as images, CSS and Javascript). If you release a new version of your app, you can set app.conf to make your updated assets available to users. Add the install stanza attribute to your app.conf file, and specify a build number. For example:

[install] build = 2

The stanza must have the [install] header. Set the build number to a unique ID. This way, when someones installs a new version of the app, they get the new assets you package with your app.

147

Inputs
Configure inputs for your app. Do you want to index a specific type of data just for your app? For example, you may just want to index your Web logs so your Web developers can look at them in one place -- your Web app. Read more about getting data into Splunk in the Getting Data In manual.

Indexes
Configure custom indexes to store the data for your app. This is the best way to make sure your app users can only search through specific data. Learn more about how to set up multiple indexes in the Admin manual.

Props and transforms

Splunk has rules for processing most data types. But if you have a custom data type you can set segmentation, character set or other custom data processing rules. Create rules for data processing in props.conf and link it to your data via transforms.conf. You can package these configurations with your app, but they will be applied on a source, sourcetype or host basis. Learn more about how Splunk's data processing rules work in the Getting Data In manual.

Users and roles

You can create a custom user or role to access your app and the content within your app. This is a good way to restrict different teams to different content. Learn more About users and roles in the Admin Manual.

Step 4: Add objects

Objects are configurations within your app that are local in scope and permissionable. This means that objects can be scoped to an app and can have read and write permissions set. For example, saved searches are objects that only show up within a given app (unless configured to be global). Users can be granted read only or read/write permissions on any saved search. When you build an app, you typically add a number of objects that add knowledge to your app, making it more useful. The Knowledge Manager Manual covers the objects available from Splunk, and also covers their configuration details.

148

Available object types

Here's a list of object types available in Splunk: Saved searches Event types Dashboards, form searches, and other views Fields Tags Field extractions Lookups Search commands Each of these object types has a use within your app. Use this page as a reference to figure out which objects you want to use, then refer to the topic in the Knowledge Manager Manual to learn more about how to configure the object you want. Saved searches and reports Saved searches and reports are the building block of most Splunk apps. Use saved searches and reports to dynamically capture important pieces of your data. Display them in your app on a dashboard, or add them to a drop-down menu in Splunk Web to run as needed. Use saved searches as a shortcut to launch interesting and relevant searches into whatever data you've loaded into your app. Saved searches are useful when building dashboards as you can schedule your saved search to run and collect data so that when your dashboard loads, the search results are already available. Event types Configure event types to capture and share knowledge in your app. Learn more about event types in the Knowledge Manager manual. Fields Splunk automatically extracts fields from your data. You may want to add in your own custom fields to your app, however. For example, you may have some custom data in your app that you want to showcase in your results by creating a new field. Read more about fields in the Knowledge Manager manual.

149

Tags Tags are another way to add metadata to your data. Any tags you create you can add to your app. Read more about tags in the Knowledge Manager Manual. Views Customize Splunk's UI by building views. Views include dashboards and search views and present the knowledge objects you've built in your app. Dashboards generally contain links to relevant searches, as well as any reports you want to display upon loading your app. Search views let you run searches on an ad-hoc basis.

Permissions for objects

Set default permissions for objects in your app in Step 5: set permissions.

Step 5: Set permissions

Every app and object within the app is governed by a set of permissions. Splunk's permissions work much like the *nix filesystem permissions: objects and apps can be set to read only or read and write for every role within Splunk. Use permissions to govern what users can see and interact with. For example, you can create a business stats view that is only available to your executive team and a set of views reporting application errors that are only available to your application development team. You can also specify which apps can be accessed by different teams in your organization. For example, you may have a business analytics app that is the only thing your executive team can see when they log into Splunk. Furthermore, since you can set read and write permissions, you can enable certain users to create new objects, or edit existing objects within an app while other users can only create new objects or edit objects within their user directory. Every user has their own user directory, so if they create a saved search, for example, it lives in their user directory. Users can promote objects from their users level to the app level -- but only if they have write permissions on the app. When a user shares an object by promoting it, Splunk actually moves the object on the filesystem from the user directory to the app directory. For example, if a member of the Ops team creates a saved search, it lives in their user directory unless they specifically share it with a given app. Then, it is available to all users who have read access within that app.
150

You can set permissions through Splunk Manager or through the file system. Splunk recommends that you use Splunk Manager first, but if you need to make some tweaks, this page explains how to edit the metadata file in your app. If you'd like to know more about users and roles, refer to About users and roles in the Admin manual.

Set permissions in Splunk Manager

You can set permissions on a per-object and per-app basis in Splunk Manager. Follow these instructions: 1. Navigate to Splunk Manager. 2. In the Knowledge panel, select a category containing the object you want to edit permissions for. For example, to change permissions on a saved search, click Searches and reports. You can also select All configurations to access all the configurations in a given app. 3. Once you've found the object you want to set permissions for, click the permissions link next to the object. 4. Set permissions to read and/or write for all the roles listed. 5. Click Save.

Set permissions in the filesystem

Use default.meta to set read and write permissions for all the objects in your app. Follow these instructions: 1. Add default.meta to your app's default directory:
$SPLUNK_HOME/etc/apps/<app_name>/metadata/default.meta

2. Then, edit this file to set permissions for any object in the app. 3. Add an entry for each object, or all objects of a type:

[<object_type>/<object_name>] access = read : [ <comma-separated list of roles>], write : [ comma-separated list of roles>]

Object type can be any of the objects listed in step 4: add objects, including saved searches, event types, views, and apps. The object name is whatever name you gave to your saved search, view, event type, or other object. If you don't specify an object name, then permissions apply to all objects of that type.

151

Set permissions per object You can set permissions on a per-object basis by explicitly naming the object. For example, in default.meta, this entry gives the admin role read and write permissions for the "Splunk errors in the last 24 hours" saved search:

[savedsearches/Splunk%20errors%20last%2024%20hours] access = read : [ admin ], write : [ admin ]

Set permissions for all objects of a type You can set permissions for all objects of a given type. In default.meta, this entry grants read permissions to everyone and write permissions to admin and power roles for all event types in the app:

[eventtypes] access = read : [ * ], write : [ admin, power ]

Make objects globally available By default, objects are only visible within the app in which they were created. So if you create an event type in your business analytics app, it is available only within that app. To make an object available to all apps, add the following line to the object's entry in default.meta:

export = system

For example, add the following entry to:

$SPLUNK_HOME/etc/apps/business_analytics/metadata/default.meta

[eventtypes] access = read : [ * ], write : [ admin, power ] export = system

This makes all event types in your business analytics app viewable in every app in your Splunk installation.

Step 6: Build navigation for your app

Once you've built views for your app, specify how to arrange them in the navigation bar in Splunk Web. You can customize this navigation to work as you wish, using the instructions below. Specify the order to display your views, and which menu you want to display them in. For example, the UI Examples app
152

includes this navigation:

Follow the instructions on this page to gather together all the views, searches and reports in your app. Also, use these instructions to specify a default view -the first view users see upon launching your app and the view that is loaded when users click the logo in the upper left-hand corner.

Create your navigation file

Create and edit your navigation menu either through Splunk Manager or through the file system. The navigation menu is built on a custom XML structure that is stored as default.xml in your app's nav directory. If you created your app using App Builder, default.xml exists at this location:

$SPLUNK_HOME/etc/apps/<app_name>/default/data/ui/nav/default.xml

You can edit the file with an editor of your choice or you can use Splunk Manager. Splunk Manager If you used the sample_app template with App Builder, you can edit this file through Splunk Manager. 1. Launch your app. You launch the app from the Splunk Web App menu, or you can navigate to Manager > Apps and click the Launch app action for your app. 2. After your app is launched, click Manager > User interface > Navigation Menus. Note: The Splunk Manager page for Navigation Menus displays navigation with respect to the context of the current app.

153

3. Click default to open the Splunk XML Editor. [screenshot] Edit the file as described in Build the navigation XML below. Click Save. File system If you are not using App Builder, create a file named default.xml in your app's nav directory:

$SPLUNK_HOME/etc/apps/<app_name>/default/data/ui/nav/default.xml

Edit the file in an editor of your choice, as described in Build the navigation XML below. To edit in Splunk manager, refresh the page located at Manager > User interface > Navigation menus. Click default under Nav name for your app.

Build the navigation XML

Now, set up your navigation menu. This maps to your app's drop-down menus in Splunk Web.

<nav> <collection label="Dashboards"> <view name="mydashboard" /> </collection> <collection label="Search views"> <view name="mysearchview" /> <a href="http://google.com">Google</a> </collection> </nav>

This example adds one view named "mydashboard" to the Dashboards drop-down in Splunk Web, another view named "mysearchview" and a link to Google in the Searches drop-down. Customize menus You can change the drop-down menu titles to whatever you want. For example, change the Dashboards menu to Ponies:

<nav>

154

<collection label="Ponies"> <view name="mydashboard" /> </collection> <collection label="Search views"> <view name="mysearchview" /> </collection> </nav>

Set a default view Specify a default view, which is the view users land on when loading your app. This is also the view users are directed to upon clicking on the logo in the upper left hand corner. To specify a view as default, add the default="true" tag:

<nav> <collection label="Ponies"> <view name="mydashboard" /> </collection> <collection label="Search views"> <view name="mysearchview" default="true" /> </collection> </nav>

If no view is marked as default, then the first one listed in default.xml becomes the default. If no view is listed in default.xml, then the app users see the first view (in alphabetical order) they have read permissions for. Dynamically include all views Include all unlisted views in a view collection, without explicitly listing them. Use the view source="unclassified" tag:

<nav> <collection label="Dashboard"> <view name="mydashboard" /> </collection> <collection label="Search views"> <view name="mysearchview" default="true" /> <view name="anothersearchview" default="true" /> </collection> <collection label="Others"> <view source="unclassified" /> </collection> </nav>

Now all the views that have not been explicitly listed in default.xml show up in
155

the Others drop-down in Splunk Web. To include all available views (even ones that have been listed), specify:

<view source="all" />

Automatic lists can be restricted by a substring match. For example, if you want all views that include the word "dashboard" in their name to appear in a collection, specify the following:

<collection label="Dashboards"> <view source="unclassified" match="dashboard"/> </collection>

Nested menus To create a nested menu, add a view collection as a child to an existing view:

<nav> <collection label="Dashboard"> <view name="helloworlddash" /> </collection> <collection label="Views"> <view name="helloworldview" default="true" /> <collection label="Others"> <view source="unclassified" /> </collection> </collection> </nav>

Note: The Splunk user interface currently does not support more than two levels of nesting. Link directly to a view Link directly to a view from the navigation menu. The view appears as a link in the navigation menu instead of being listed in a drop-down menu. Add the view name=mychart" right underneath nav:

<nav> <view name="mychart" /> <collection label="Dashboard"> <view name="mydashboard" /> </collection> <collection label="Searches"> <view name="mysearchview" default="true" />

156

</collection> <collection label="Others"> <view source="unclassified" /> </collection> </nav>

Hide views If you want to hide a view from being picked up in the navigation menu, edit the view's XML. Make sure you edit the top-level <view> tag, not a <view> tag contained within the <nav> tag.

<view isVisible="false"> ... </view>

Add saved searches and reports Add saved searches and reports into your navigation menu, too. This example adds the following saved search into the saved searches drop-down menu:
<saved name="MySavedSearch" />

<nav> <collection label="Dashboard"> <view name="mydashboard" /> </collection> <collection label="Searches"> <view name="mysearchview" default="true" /> </collection> <collection label="Others"> <view source="unclassified" /> </collection> <collection label="Saved Searches"> <saved name="MySavedSearch" /> </collection> </nav>

Now the saved search MySavedSearch shows up in the Saved Searches drop-down. You can specify what view to load the saved search by adding a view= tag to the saved tag:

<nav> ...

157

<collection label="Saved Searches"> <saved name="MySavedSearch" view="mychart" /> </collection> </nav>

Splunk checks for a 'view' property attached to the savedsearches.conf stanza. If none is specified, the saved search launches in the Search app's 'timeline' view. Saved searches can also be nested, just like views:

<nav> ... <collection label="Saved Searches"> <saved name="Daily indexing volume by server" view="charting" /> <collection label="Errors"> <saved source="unclassified" match="error" /> </collection> <saved source="unclassified" /> </collection> </nav>

Dynamically include saved searches You can automatically include unnamed saved searches just the same as dynamically adding views. Just specify saved source="unclassified":

<nav> <collection label="Dashboard"> <view name="mydashboard" /> </collection> <collection label="Searches"> <view name="mysearchview" default="true" /> </collection> <collection label="Others"> <view source="unclassified" /> </collection> <collection label="Saved Searches"> <saved source="unclassified" /> </collection> </nav>

This example now loads all unclassified saved searches in your App into the saved search menu, sorted alphabetically. Restrict automatic lists with a substring match Automatic lists can be restricted by a substring match. For example, if you want all unclassified searches that include the word "match" in their name to appear in a collection, use saved source="unclassified" match="<term>".
158

On the other hand, if you want to set up an automatic list that includes all searches and reports available to the app with a specific term in their name, use saved source="all" match="<term>". Matching is case insensitive.

<nav> ... <collection label="Errors"> <saved source="all" match="error" /> </collection> </nav>

This example creates an "Errors" search collection, which automatically lists all saved searches with the substring "error" in their name, including searches that may already appear elsewhere in the nav menu.

Step 7: Configure a setup screen

You can make life easier for your users by creating a setup screen for your app or add-on. Setup screens make it easier to distribute apps to different environments, or to customize an app for a particular usage. When the user first runs the app, the setup screen displays that allows the user to specify configurations for the app without having to edit the configuration files directly. The user can later run the setup screen from Splunk > Manager > Apps > Actions. A setup screen uses the Splunk REST API to manage the app?s configuration. For example, you can use the setup screen to enable or disable a scripted input or set the frequency and alerting for a saved search. The setup screen can configure REST endpoints available from the Splunk API or custom endpoints that you create for your app.

This topic walks you through creating a setup screen. You can jump ahead to view the following examples:

159

 Setup screen example Setup screen example using a custom endpoint

Create a setup screen

To create a setup screen: 1. Create a setup.xml file in your app's default directory:
$SPLUNK_HOME/etc/apps/<AppName>/default/setup.xml.

2. Supply initial values for the fields in your app's configuration files. The setup screen uses these values to populate the input fields in the setup screen. See setup.xml syntax below for information on creating setup.xml. View the setup.xml spec file. Endpoints, entities, and fields Splunk uses its REST API to update configurations specified in a setup screen. In setup.xml, you specify the endpoints, entities, and fields which Splunk accesses when updating a configuration. Here are summary descriptions of endpoint, entities and fields to help you understand how they are used in setup.xml:
Directly or indirectly indicates which configuration file to update. Most of the configuration files within Splunk have one or more corresponding endpoints. For example, inputs.conf has a number of corresponding endpoints, including data/inputs/monitor (for monitored files) and data/inputs/script (for scripted inputs).

endpoint

Navigate to the following location to see the endpoints available to all apps in your Splunk installation.
https://localhost:8089/servicesNS/nobody/ The object ID listed by the endpoint. Typically maps to a stanza in a configuration file.

entity

Use URI encoding to specify paths to entities. field

Maps to an attribute of an entity. Typically, this is a setting in the stanza of a configuration files. The user specifies values for the attribute in the setup screen.

160

See About configuration files to learn more about how Splunk uses configuration files to manage apps and Splunk. See Splunk's API is RESTful to learn more about Splunk's REST API.
REST endpoints and configuration file settings

Splunk uses REST endpoints to interact with other Splunk resources, both in memory and on disk. For setup screens, you typically access configuration files to allow a user to easily configure an app for their specific circumstances without having to manually update the configuration files. The name of Splunk REST endpoint parameters usually, but not always, map directly to the name of the setting in a configuration file. For example, the following stanza in savedsearches.conf enables a scheduled search:

[MySearch] search = sourcetype=access_combined ( 404 OR 500 OR 503 ) dispatch.earliest_time = -1d cron_schedule = */5 * * * * enableSched = 1

You can view the corresponding REST endpoints here:

https://localhost:8089/servicesNS/nobody/<AppName>/saved/searches/WebSearch At this REST endpoint, the names search, dispatch.earliest_time, and cron_schedule match the names of the attributes in savedsearches.conf. But the REST endpoint parameter for enableSched is is_scheduled. In the setup.xml, you reference is_scheduled to modify the setting for enableSched. Example settings for endpoint, entity, and field

For example, in setup.xml for an app called sampleApp: endpoint saved/searches Maps to the configuration file savedsearches.conf. You can view the REST destination from a web browser at:
https://localhost:8089/servicesNS/nobody/sampleApp/saved/searches)

entity sample_scheduled_search In savedsearches.conf, refers to the stanza, [sample_scheduled_search].

161

 field cron_schedule Maps to the setting in [sample_scheduled_search] to update. In the setup screen, the user could specify a value, such as */5 * * * *.

Providing credentials to access scripts If your app contains scripted inputs that require a user name and password, you can capture the credentials for the script in your setup screen. In setup.xml, you can provide username and password fields to capture the user credentials. See Setup screen example with user credentials for an example on how to provide fields for user credentials. The password field masks input with a ?*? character. Splunk encrypts the credentials and stores them in a stanza in the app?s app.conf configuration file. app.conf is at:

$SPLUNK_HOME/etc/apps/local/app.conf

Here is the stanza, which is generated by splunkd, that contains the encrypted credentials. <realm> is optional:

[credential:<realm>:<username>] password = $1$<encrypted-password>

Caution: security implications Splunk stores the encrypted password and encryption key on the same machine. This is because the script needs access to the decrypted password from Splunk. For more information see: app.conf spec file setup.xml syntax Setup screen example with user credentials

162

Running the setup screen If your app contains a setup.xml file, when the user first runs the app the setup screen opens, displaying default configuration values for items listed on the setup screen. The user can choose to accept the default configuration, or specify new values. The user can later run the setup screen from the Splunk Manager > Apps > Actions. Click on the Set up link for your app to open the setup screen. Note: The setup screen writes changes made to the app?s configuration to the $SPLUNK_HOME/etc/apps/<app>/local directory. The local directory overrides any settings in the app?s default directory.

Creating setup screens for custom endpoints

For more complex setups, you can write your own Python scripts. For example, the setup screen for the WebSphere app (available from Splunkbase) takes a single user input, the path to profileRegistry.xml for a WebSphere Application Server instance. From this registry file, the app extracts the locations of the WAS log files and configures inputs.conf to monitor all of them. To use a custom endpoint in your setup: 1. Create your custom configuration file with the initial values for the fields in the stanzas. (Alternately, you could initialize the values for the fields in a python script.) 2. Create a stanza in $SPLUNK_HOME/etc/apps/<AppName>/default/restmap.conf that maps your endpoint to your custom configuration file. 3. Write a python script for your endpoint and place it in:
$SPLUNK_HOME/etc/<AppName>/bin/

4. Write setup.xml. See Setup screen example using a custom endpoint for a detailed example.

setup.xml syntax
defines the setup screen that prompts users for configuration settings. You place setup.xml in your app?s default directory:
setup.xml

163

$SPLUNK_HOME/etc/<AppName>/default/setup.xml

<setup> The base element of a setup screen. It contains any number of block elements. Block elements cannot be nested inside other block elements. <block> The block element defines the UI for the setup screen. A block element can contain one or more of the following: text element input element A block element can declare the following attributes: <block> attributes attribute
title

description
(Required) Displays a header for the block. (optional) Specifies a Splunk REST endpoint for your app. The endpoint attribute is inherited by all input child elements. Splunk uses its REST API to access specified endpoints. Each endpoint is relative to: https://hostname:port/servicesNS/nobody/<AppName> For example, the endpoint: saved/searches corresponds to this REST endpoint, which you

endpoint

can access in a web browser:

https://localhost:8089/servicesNS/nobody/<appName>/saved/searchesThis endpoint maps to the savedsearches.conf configuration file. (optional) Specifies the object at the endpoint to modify. Typically, entity maps to a stanza in a configuration file.

entity

This attribute can only be set for a block that specifies an endpoint. The entity attribute is inherited by all input child elements. creates a new entity. Typically, this results in a new stanza in the configuration file pointed to by the REST endpoint.
entity= "_new"

mode

(optional) Sets how to process an entity attribute when you define the entity with a regex, such as *. All entities matching the regex are configured. Note: Splunk interprets '*' as '.*'.

The value of mode can be either iter or bulk.

164

iter:

Iterates through all matching entities at that endpoint, displaying separate inputs for each matching entity. Allows the user to specify different values for each entity. For example, the user can set the polling interval separately for a number of scripted inputs.
bulk:

Displays a single input for all matching entities. For example, lets the user set a single polling interval for a number of scripted inputs. When using bulk, all values for the matching entities should have the same type, such as string or number. <text> An optional element that provides descriptive text for the setup screen. The text element can only be used inside block elements.

<input> The input element collects input from the user. It associates the input with the specified field. The type element within an input element defines the user interface control to display. When the user clicks Save on the setup screen, Splunk uses the POST method to update the fields for the specified endpoint/entity pair. The input element can contains the following child elements: <label> (required) <type> (required)

<input> attributes attribute description

(required) Specifies the REST endpoint that Splunk uses. See the description of endpoint for the <block> element. endpoint

Each input element has one (and only one) endpoint. The endpoint can be inherited from a parent block.
entity

165

(required) Specifies the object at the endpoint to modify. Typically, entity maps to a stanza in a configuration file.

The entity can be inherited from a parent block. creates a new entity. Typically, this results in a new stanza in the configuration file pointed to by the REST endpoint.
entity="_new" Specifies the setting to be configured in the stanza specified by entity. field

When used with entity= "_new" creates a new setting in the new stanza.
(optional) Sets how to process an entity attribute when you define the entity with a regex, such as *. All entities matching the regex are configured. Note: Splunk interprets '*' as '.*'.

The value of mode can be either iter or bulk.

iter: mode

Iterates through all matching entities at that endpoint, displaying separate inputs for each matching entity. Allows the user to specify different values for each entity. For example, the user can set the polling interval separately for a number of scripted inputs.
bulk:

Displays a single input for all matching entities. For example, lets the user set a single polling interval for a number of scripted inputs.

<label> Required element in an <input> element. The description of the input field which is displayed on the setup screen. Specify $name$ to display the name of the entity. Specify $field_name$ to specify the value of a specified field. For example, if iterating through a list of entities (mode = "iter"), use $name$ to display the name of each entity to the user. Use $search$ to display the value of the search field defined in each entity. <type> Required element in an <input> element. Specifies the UI control for capturing user input.
166

Allowed values for the type element: bool: Displays a checkbox that allows the user to choose true or false values. text: Displays a text field to input string values. password: Creates a password text field that masks passwords with the ?*? character. The UI displays a second password text field to ensure that the user types the same password twice. list: Displays values from a comma separated list, allowing the user to select a single value.

Step 8: Package your app or add-on

You can share your extensions to Splunk on Splunkbase and make them available to everyone in the Splunk community. You can show off anything you have done to make Splunk easier or more universal -- not just views, dashboards, and saved searches, but also scripted inputs, field extractions, workflow actions, lookups, event types and more. All you have to do is place your work in a dedicated directory and make sure everything is clean and works outside your special environment. Then add or update your app.conf file, icon, and screenshot to show off your extension in Launcher. Package, tar, or zip your work and upload it.

Prepare your app or add-on

Before you package your app or add-on, make sure you have all the components and that they work: 1. If you have not already done so, create a dedicated directory for your app or add-on under $SPLUNK_HOME/etc/apps/ (for example: $SPLUNK_HOME/etc/apps/<app_name>). If you created an app using app builder, this has been created for you. This directory is denoted by $APP_HOME for the rest of this topic. 2. Create or edit your $APP_HOME/default/app.conf file. If you created an app using app builder, app.conf has been created for you but you still need to add a stanza to have a description of your app show up in Launcher. If you are packaging an add-on, you need to create your app.conf file. 3. Review the app.conf.spec documentation to ensure your app can be uploaded to Splunkbase.
167

 Splunkbase requires an App ID, version string, and a description defined in app.conf. By default, Splunk checks for updates to an app. If you do not want Splunk to check for updates, include the following in app.conf:

[package] check_for_updates = 0

Splunkbase validates app.conf and other app files and does not allow you to upload if there are errors. 3. (Optional) If you want an icon or screenshot on Splunkbase or in the Launcher, create an icon and put it in $APP_HOME/appserver/static. If you are packaging an app, you can create a screenshot and place it in the same location. See Files and directories for apps and add-ons for requirements. 4. Place any scripts in the $APP_HOME/bin directory and make sure $APP_HOME/default/inputs.conf is set up correctly. If your app or add-on includes scripted inputs, scripted searches, or scripted lookups, you should follow general best practices for writing and testing the scripts. For example: Include any dependencies your app or add-on needs to run outside of your environment. You may want to test it on a different system to make sure it works out of the box. Splunk recommends that you make sure fields, event types, or other information tags adhere to the Splunk Common Information Model. This ensures that your app works with other Splunk instances. Scripts that serve their own webpage and need a new REST endpoint must be specified in restmap.conf. On *nix platforms, you can use environment variables to set locations in any scripts within your app or add-on so that they only have to be set once. If you do so, make sure to include this information in your README.txt. (Optional) Write a setup screen to allow your users to configure local settings. Provide instructions to test your scripts outside of Splunk. If your app is intended to run cross-platform, include both .sh and .bat files for scripted inputs and include an inputs.conf that can enable either one. You can enable both options by default (only one will run), write a setup script to allow the user which option to enable, or give the user manual instructions on how to enable the option they want. An example with both input types enabled:
168

[script://./bin/my_input.sh] interval = 60 sourcetype = my_sourcetype disabled = 0 [script://.\bin\my_input.bat] interval = 60 sourcetype = my_sourcetype disabled = 0

5. Make sure you have the correct configuration files, views, and navigations for your app or add-on. Objects created prior to the development of the app or add-on may be in $SPLUNK_HOME/etc/apps/search/local or $SPLUNK_HOME/etc/system/local. For example, if you are packaging field extractions, they may be defined in stanzas in props.conf and/or transforms.conf in the Search app. Wherever you make use of a stanza in a .conf file, you need to: (a) create a blank version of each relevant .conf file in your $APP_HOME/default directory. (b) copy the stanza heading and the relevant lines from the original .conf file to the version in $APP_HOME/default. Do not copy lines or stanzas that are not directly relevant to your app. Where it's hiding
$SPLUNK_HOME/etc/system/local/ $SPLUNK_HOME/etc/apps/search/local/

Move to
$APP_HOME/default/ $APP_HOME/default/

$SPLUNK_HOME/etc/users/admin/<app_name>/ $APP_HOME/default/ $APP_HOME/metadata/local.meta $APP_HOME/metadata/default.meta

See Files and directories for apps and add-ons for the correct file structure you need to share an app. See About configuration files for an overview of Splunk configuration files, and a list and description of all configuration files.

6. Verify permissions for each object in your app or add-on and change any permissions that aren't set correctly. You can set permissions using Splunk Manager or by editing default.meta. If you are creating an add-on that is not Visible, you must make each object globally available. For an explanation of permissions, see Curate Splunk knowledge with Manager in the Knowledge Manager manual for instructions on setting permissions, see Step 5: set
169

permissions in the Developer manual. If you set permissions through Manager, make sure that the permissions end up in default.meta and not local.meta. 7. Validate the XML for your views and navigation by running validate_all.py. See Use XML Schemas in this manual for more information. 8. Document your app. You can distribute your documentation in any of the following ways: A README.txt file in your $APP_HOME directory Documentation directly on your Splunkbase page. We recommend you document your app or add-on first and then cut and paste the documentation into the Splunkbase page. A PDF file in $APP_HOME/appbuilder/static/ 9. If your app needs user-supplied information (for example, an app that requires a Twitter account to analyze Twitter data), make sure to remove the information for your test account before tarring the final version. 10. Tar and zip your app as described in the next section. 11. Test your package. Extract your package in a clean Splunk install in a different location and environment than the one where you built your app or add-on. Log in as a different Splunk user from the one you used to create the app. You may also want to test it with earlier versions of Splunk.

Packaging your app for Splunkbase

The final step before uploading your app to Splunkbase is packaging. This means taking your app's directory and turning it into a single compressed file which can be uploaded to Splunkbase. Splunkbase uploads are required to have the .spl file extension, e.g. myapp.spl. SPL format is identical to .tar.gz format (also known as a "tarball"). The only difference is the file extension. Make sure you have placed all the app's components in the correct location, have moved all customizations from /local to /default, and have tested your app before you package it.

170

You can use your preferred file-compression utility to create the .tar.gz-format file, or you can follow the OS-specific instructions below. Packaging on Unix/Linux/Mac On Linux/Unix systems, creating a .tar.gz is straightforward because tools for creating .tar.gz archives are packaged with almost all *nix OS distributions. First you need to tar your app's folder, which creates a .tar file. Then you need to gzip the folder into a .tar.gz file. Finally, rename the file extension from .tar.gz to .spl. Example commands are below:

$: tar cv appdirpath/ > appname.tar $: gzip appname.tar $: mv appname.tar.gz appname.spl OS X users: You may need to set COPYFILE_DISABLE=true tar --exclude=".*" before using tar to avoid unwanted metadata files being added to your .spl file,

which may cause your upload to fail. Packaging on Windows Unlike ZIP files which Windows handles natively, creating .tar.gz-format files requires using a third-party compression utility not packaged with the Windows OS.
Using WinACE

The following is an example procedure that uses WinACE, a shareware product. compression/decompression tool that supports all modern versions of Windows. To package your app using WinACE, follow these steps: 1. Download and install WinACE from winace.com. 2. Open WinACE. 3. Navigate to your $SPLUNK_HOME\etc\apps directory. 4. Highlight your app's directory. 5. Click the Create button in the upper toolbar. 6. In the Add Files / Create Archive dialog, select the Options tab. 7. Under Archive type select GZipTar. 8. Click Add. 9. Congratulations, your package is ready for upload Splunkbase!

171

Using 7-Zip

Following is an example procedure that uses 7-Zip, a free compression/decompression tool that supports all modern versions of Windows. To package your app using 7-Zip, follow these steps: 1. Install 7-Zip from http://www.7-zip.org/. 2. Open 7-Zip. 3. Navigate 7-Zip's file explorer to the parent directory of your app (for example c:\Program Files\Splunk\etc\apps). 4. Select your app's folder in the left pane of 7-Zip. 5. Click "Add" (the green plus sign) on 7-Zip's toolbar. 6. An "Add to Archive" dialog box will come up. 7. Choose "tar" from the "Archive Format" dropdown box. The filename shown in the "Archive" textbox should change to have a ".tar" file extension. 8. Click the "..." button in the upper-right-corner to choose a location for your temporary tar file outside Splunk's Program Files folders, since you won't want these files cluttering up your actual Splunk install. 9. Click OK to create the .tar file 10. Now it's time to zip up the .tar file into a .tar.gz. Back in 7-Zip's main UI, select the .tar file you created in the previous step 11. Click the "Add" button in the toolbar 12. An "Add to Archive" dialog box will come up. 13. Choose "GZip" from the "Archive Format" dropdown box. The filename shown in the "Archive" textbox should change to have a ".tar.gz" file extension. 14. Click OK to create the new .tar.gz file 15. To test your new package, double-click on the new .tar.gz file in 7-Zip to drill into it. You should see a single .tar file inside it. Double-click again, and you'll see a single folder which contains your app content. 16. Finally, assuming you're satisfied that your app has been packaged properly, rename your package file from a .tar.gz extension to an .spl file extension. 17. Congratulations, your package is ready for upload to Splunkbase!

Files and directories for apps and add-ons

You can share any extension to Splunk - not just the views and navigation you find in an app, but saved searches, scripted inputs, and Splunk knowledge. To do this, place the necessary files in a directory for distribution to the recipient's $SPLUNK_HOME/etc/apps directory. You can share an extension even if it doesn't
172

have a UI environment of its own.

Apps vs. add-ons

You can add views and navigation along with other extensions to make a separate app, but this is not necessary. Extensions such as field extractions or scripted inputs may not necessarily benefit from a separate UI with a distinct URL and a collection of views and dashboards. You can provide the benefits without creating a full-blown app that shows up on the App menu. In this case, you package the extension as an add-on. An add-on is essentially an app that has no UI of its own and exists only as a container for other things (such as saved searches or scripted inputs) that are shared globally. What can an app or add-on do? Apps and add-ons can both include: scripted inputs or other input types field extractions for a specific source type (often implemented with an input method) scripted lookups or searches saved searches that can be accessed from the Search app views and navigation event types tags workflow actions What is the difference? apps are set to Visible and must have a navigation file. Apps have a separate URL and appear on the App menu. Apps are not restricted to dashboards and searches, although in practice, they are often view-intensive. add-ons are set to Not Visible. They do not have a separate URL and do not show up on the App menu. An add-on can have views, but they show up under an existing app (for example, the Search app). Every object in an add-on -- views, saved searches, navigations, etc. -- must be globally available in order to be accessible. See App architecture and object ownership in the Admin manual. Apps vs. add-ons are something of a marketing distinction. From the point of view of the code, apps and add-ons are created and administered as apps. All apps and add-on have a separate folder in $SPLUNK_HOME/etc/apps/ and an
173

app.conf

file. The following table summarizes the difference between apps and

add-ons: app
visible navigation file required (see not visible

add-on Build navigation

for your app)

appears on App menu has dedicated URL objects accessed using app

navigation file optional does not appear on App menu does not have dedicated URL objects accessed using other apps; must be globally available

For another view of apps and add-ons, see What are apps and add-ons? in the Admin manual. Set visibility The visibility setting determines whether an extension can be considered an app and appear on the App menu. To set visibility: 1. Create a directory under $SPLUNK_HOME/etc/apps (or %SPLUNK_HOME%\etc\apps on Windows), for example $SPLUNK_HOME/etc/apps/<addon_name>. This is called $APP_HOME for the rest of this topic. 2. Restart Splunk 3. Go to Manager > Apps and navigate to the configuration screen for your app or add-on by clicking on the name of your directory. 4. Select whether you want to make the extension Visible.

Note: You can also set app visibility using the app.conf file in the $APP_HOME/default/ directory. To do this, open or create app.conf in a text editor and edit or create the ui stanza. For example, to set an add-on to be not Visible:

[ui] is_visible = false

174

Files and directories for apps and add-ons

If you are sharing your app or add-on, make sure you have all the files you need in the correct location under the home directory for your app ($APP_HOME). To allow users to make their own customizations without being clobbered by later updates of your app, you move all the files in $APP_HOME/local/ to $APP_HOME/default/. Also check for files and stanzas that may be scattered around the system outside of the app's directory. Depending on the functionality you have implemented, the followings file may show up: file or directory
$SPLUNK_HOME/etc/apps/<app_directory> ($APP_HOME) $APP_HOME/appserver/static/

app
required

add-on
required

comme

dedicated directory u $SPLUNK_HOME/et

Directory for web res as images, CSS, or H your app or add-on

$APP_HOME/appserver/static/appIcon.png

recommended

recommended

Icon for app or add-o Launcher and Splunk should be in PNG for x 36px in size. NB: N punctuation of appIc Specifically, the capi

$APP_HOME/appserver/static/screenshot.png

recommended

not required

Screenshot or splash app or add-on displa Launcher. Image mu format. Display dime 623px x 350px - will with white if smaller, For best results, mak image size is in the 9 do not include brows your image.

$APP_HOME/appserver/static/documentation.pdf optional

optional

Downloadable PDF d for your app or add-o

$APP_HOME/bin/
$APP_HOME/bin/*.sh, *.bat, *.py, *.pl, etc.

Directory for custom scripts for searches or scripte

optional optional

$APP_HOME/default/
$APP_HOME/default/app.conf

Directory for configuration files specific to your app

required required

File that sets app na description; app visib add-on); and any cus configuration file sett app. See configure

the Developer ma
175

app.conf in the A for more informat

Visibility setting in ap [ui] [ui] determines whether is_visible=true is_visible=false separate UI (app) or

Additional configurat required by your app Pretty much any .con here, except for thos define global settings $APP_HOME/default/*.conf optional optional

add configuration Developer manua configuration files Admin manual fo information about configuration files

$APP_HOME/default/setup.xml

optional

optional

File for custom setup your app or add-on.

$APP_HOME/default/data/ui/
$APP_HOME/default/data/ui/nav/default.xml

Directory for navigation and views

optional optional

Navigation specific to add-on. See build n

your app in the D manual for more

Views specific to you add-on; an app must more views. See bu $APP_HOME/default/data/ui/views/*.xml required optional

dashboards, form and advanced vie Developer manua information.

$APP_HOME/local/

Directory for user-generated configuration files

required required Include an

empty l directory when yo your app or add-o user makes any c changes via Man will be stored her developer of an a should never plac shipping configur local, as subsequ

176

would end up clo user's customizat $APP_HOME/lookups/

$APP_HOME/lookups/*.csv

Directory for lookup tables

optional optional CSV file for lookups

$APP_HOME/metadata/

Directory for permissions

$APP_HOME/metadata/default.meta

required

optional

File that sets default the app or add-on; w missing, permissions Users set permission $APP_HOME/metad See Step 5 Set pe

the Developer ma more information

$APP_HOME/README.txt recommended recommended

Readme that contain on installing and con app or add-on, as we for troubleshooting.

Set up app.conf
When you use app builder to create an app, it automatically creates an app.conf file and enables a UI context for your app. You still need to define the launcher stanza before you share your app on Splunkbase. If you have built an add-on directly, you may need to create your own app.conf using a text editor. To instrument the difference between an app and an add-on, set the Visible setting for the app in Manager. You can also set the is_visible setting in the [ui] stanza in the app.conf file. Example app.conf for an add-on
Here is a sample directory and app.conf file for a simple add-on that provides a scripted input: [ui] is_visible = false label = My Add-on [launcher] author=me description=My Add-on provides scripted inputs that allow you to index your Specific Third-party Application in Splunk 4.0 or later. version="1.0"

177

Note: author and version do not actually show in the Launcher app, but it's a good idea to include them. author lets you get credit for your work; it appears in the app details in Manager > Apps. version allows users to check the current version of their app. If you are uploading your app to Splunkbase, make sure that the version number in app.conf matches the version number on Splunkbase. Example app.conf for an app with updated images
This example shows an app with the following:

UI context enabled a launcher description a build specification to ensure static web assets (such as images, CSS and Javascript) are updated for users.

[ui] is_visible = true label = My App [launcher] author=me description=My App provides pre-built data inputs, searches, reports, alerts, and dashboards. This update provides a new user interface with flashier, more exciting icons. version="2.1" [install] build = 3

Setup screen example

The following example illustrates a setup screen for an app, MySampleApp. MySampleApp contains three saved searches and a scripted input. In the setup screen, the user specifies the following configurations:

178

 Interval for running the scripted input Enable or disable one the Web Search The cron schedule for each of the searches The earliest dispatch time for all the searches. This setup screen modifies savedsearches.conf and inputs.conf.

In this example: The configuration files already exist in

$SPLUNK_HOME/etc/apps/MySampleApp/default/. The configuration file contains the stanzas you are modifying. The values present in the stanza represent the default values displayed by the setup screen. If the user changes the default settings to a configuration file from the setup screen, Splunk writes the updates to the configuration file in $SPLUNK_HOME/etc/apps/MySampleApp/local/.

The setup screen uses the following REST endpoints to update the configuration:

https://localhost:8089/servicesNS/nobody/MySampleApp/saved/searches/ https://localhost:8089/servicesNS/nobody/MySampleApp/data/inputs/script/

Configuration files for the example

Here are the default configuration files: savedsearches.conf

179

[Web Search] search = sourcetype=access_combined ( 404 OR 500 OR 503 ) dispatch.earliest_time = -1d cron_schedule = */5 * * * * enableSched = 1 [Firewall Data Search] search = sourcetype=cisco_wsa .exe usage!="Unknown" dispatch.earliest_time = -1d cron_schedule = */5 * * * * enableSched = 0 [Email Data Search] search = sourcetype=cisco_esa OUTBREAK_* dispatch.earliest_time = -1d cron_schedule = */5 * * * * enableSched = 0

inputs.conf
[script://$SPLUNK_HOME/etc/apps/MySampleApp/bin/myscript.sh] interval = 60 sourcetype = customsourcetype source = customsource

setup.xml
Here is the setup.xml file that implements the setup screen. Note the following in the setup.xml file: The entity specifying the path to scripted input uses URI encoding The field for the Web Search uses the REST endpoint, is_scheduled. This updates the enableSched field in the [Web Search] stanza. The text blocks use HTML entities to specify italic and bold for the type. In the block that configures the cron schedule, entity specifies the regex '*' to specify all searches. The block contain examples for specifying iteration mode and bulk mode See "setup.xml syntax" on Step 7: configure a setup screen for details on the syntax used in the example setup.xml
<setup>

<block title="Enable a scripted input" endpoint="data/inputs/script" entity="%24SPLUNK_HOME%252Fetc%252Fapps%252FMySampleApp%252Fbin%252Fmyscript.sh <text> &lt;i&gt;Specify the configuration for a single setting in a

180

stanza.&lt;/i&gt; </text> <input field="interval"> <label>Specify the interval for [$name$] </label> <type>text</type> </input> </block> <block title="Enable the schedule for a search" endpoint="saved/searches" entity="Web Search"> <text> &lt;i&gt;Specify the configuration for a single setting in a stanza.&lt;/i&gt; </text>

<input field="is_scheduled"> <label>Enable Schedule for $name$</label> <type>bool</type> </input> </block> <block title="Configure Cron Schedule" endpoint="saved/searches" entity="*" mode="iter"> <text> &lt;i&gt;&lt;b&gt;Iteration mode&lt;/b&gt;: specify the cron schedule for each search in the conf file.&lt;/i&gt;</text> <input field="cron_schedule"> <label>$name$</label> <type>text</type> </input> </block>

<block title="Set earliest dispatch time" endpoint="saved/searches" entity="*" mode="bulk"> <text> &lt;i&gt;&lt;b&gt;Bulk mode&lt;/b&gt;: enable the earliest dispatch time for each search in the conf file.&lt;/i&gt; </text> <input field="dispatch.earliest_time"> <label>Set earliest dispatch time for all searches</label> <type>text</type> </input> </block> </setup>

181

Setup screen example using a custom endpoint

This example shows how to create a setup screen that uses Splunk?s REST API to configure a custom endpoint. The custom endpoint maps to a configuration file you create at $SPLUNK_HOME/etc/apps/<myApp>/default/myappsetup.conf.

To update a custom endpoint, do the following: 1. Create your custom configuration file with the initial values for your setup screen. 2. Create a stanza in restmap.conf that maps your endpoint to your custom configuration file. 3. Write a python script that initializes your setup screen and handles the user-entered values. 4. Write setup.xml.

1. Create a custom configuration file with default values

This example uses a configuration file to initialize the default values for the stanza [setupentity]. The entity attribute in setup.xml refers to this stanza. However, you can also initialize the default values in your python script. myappsetup.conf
[setupentity] field_1 = field_3 = 60 field_2_boolean = 0

182

2. Example stanza in restmap.conf

The following example stanza in restmap.conf sets up a custom endpoint at:
https://localhost:8089/services/mycustom/customendpoint

restmap.conf
. . . [admin:myendpoint] match=/mycustom members=customendpoint [admin_external:customendpoint] handlertype = python handlerfile = MyApp_python_handler.py handleractions = list, edit . . . [admin_external:<endpoint_name>] Names

the endpoint. Make sure you use a

unique name for your endpoint. handlertype Specifies the language of the REST endpoint script. Currently, Splunk only supports python for custom endpoints. handlerfile The name of the python script. Place the script here:
$SPLUNK_HOME/etc/apps/<app_name>/bin

handleractions Actions supported by the script. list displays the initial field values. edit updates the endpoint when the user saves the setup screen.

3. Example python script that implements a new endpoint

The python script looks for the configuration file, myappsetup.conf in either .../default or .../local. It also searches for values for the fields defined in the configuration file, and writes any changes to .../local.

MyApp_python_handler.py
import splunk.admin as admin import splunk.entity as en # import your required python modules ''' Copyright (C) 2005 - 2010 Splunk Inc. All Rights Reserved. Description: This skeleton python script handles the parameters in the

183

configuration page. handleList method: lists configurable parameters in the configuration page corresponds to handleractions = list in restmap.conf handleEdit method: controls the parameters and saves the values corresponds to handleractions = edit in restmap.conf ''' class ConfigApp(admin.MConfigHandler): ''' Set up supported arguments ''' def setup(self): if self.requestedAction == admin.ACTION_EDIT: for arg in ['field_1', 'field_2_boolean', 'field_3']: self.supportedArgs.addOptArg(arg) ''' Read the initial values of the parameters from the custom file myappsetup.conf, and write them to the setup screen. If the app has never been set up, uses .../<appname>/default/myappsetup.conf. If app has been set up, looks at .../local/myappsetup.conf first, then looks at .../default/myappsetup.conf only if there is no value for a field in .../local/myappsetup.conf For boolean fields, may need to switch the true/false setting. For text fields, if the conf file says None, set to the empty string. ''' def handleList(self, confInfo): confDict = self.readConf("myappsetup") if None != confDict: for stanza, settings in confDict.items(): for key, val in settings.items(): if key in ['field_2_boolean']: if int(val) == 1: val = '0' else: val = '1' if key in ['field_1'] and val in [None, '']: val = '' confInfo[stanza].append(key, val) '''

184

After user clicks Save on setup screen, take updated parameters, normalize them, and save them somewhere ''' def handleEdit(self, confInfo): name = self.callerArgs.id args = self.callerArgs if int(self.callerArgs.data['field_3'][0]) < 60: self.callerArgs.data['field_3'][0] = '60' if int(self.callerArgs.data['field_2_boolean'][0]) == 1: self.callerArgs.data['field_2_boolean'][0] = '0' else: self.callerArgs.data['field_2_boolean'][0] = '1' if self.callerArgs.data['field_1'][0] in [None, '']: self.callerArgs.data['field_1'][0] = ''

''' Since we are using a conf file to store parameters, write them to the [setupentity] stanza in <appname>/local/myappsetup.conf ''' self.writeConf('myappsetup', 'setupentity', self.callerArgs.data) # initialize the handler admin.init(ConfigApp, admin.CONTEXT_NONE)

4. Create setup.xml
Here is the setup.xml file that creates the setup screen for the custom endpoint.
<setup> <block title="Configure This App"> <text>Setup screen with custom endpoints</text> </block> <block title="A text input" endpoint="mycustom/customendpoint" entity="setupentity"> <input field="field_1"> <label>Enter your text</label> <type>text</type> </input> </block> <block title="Enable and set a numeric value" endpoint="mycustom/customendpoint" entity="setupentity">

185

<input field="field_2_boolean"> <label>Enable This Input</label> <type>bool</type> </input> <input field="field_3" endpoint="mycustom/customendpoint" entity="setupentity"> <label>Set this number (minimum value=60)</label> <type>text</type> </input> </block> </setup>

Setup screen example with user credentials

This example shows the steps needed to create a set up screen that accepts user/password credentials for a python script. The python script uses the credentials supplied in the setup screen. 1. Create the block in your setup screen that accepts user credentials. 2. Write a python script that uses the credentials 3. Create a stanza in inputs.conf for your script.

1. Create a block in setup.xml that accepts user credentials

Add the following block to setup.xml to create the User input fields for your scripts.

<block title="Add new credentials" endpoint="admin/passwords" entity="_new"> <input field="name"> <label>Username</label> <type>text</type> </input> <input field="password"> <label>Password</label> <type>password</type> </input>

<input field="realm"> <label>Realm</label> <type>text</type> </input>

186

</block>

2. Write a python script that uses credentials

Here is the path to the example script:
$SPLUNK_HOME/etc/apps/<MyApp>/default/bin/MyInputScript.py

MyInputScript.py

import splunk.entity as entity . . . # access the credentials in /servicesNS/nobody/<MyApp>/admin/passwords def getCredentials(sessionKey): myapp = 'name-of-your-app-here' try: # list all credentials entities = entity.getEntities(['admin', 'passwords'], namespace=myapp, owner='nobody', sessionKey=sessionKey) except Exception, e: raise Exception("Could not get %s credentials from splunk. Error: %s" % (myapp, str(e))) # return first set of credentials for i, c in entities.items(): return c['username'], c['clear_password'] raise Exception("No credentials have been found") def main(): # read session key sent from splunkd sessionKey = sys.stdin.readline().strip() if len(sessionKey) == 0: sys.stderr.write("Did not receive a session key from splunkd. " + "Please enable passAuth in inputs.conf for this " + "script\n") exit(2) # now get twitter credentials - might exit if no creds are available username, password = getCredentials(sessionKey)

187

# use the credentials to access the data source . . .

3. Create a stanza in inputs.conf

Here is the path to inputs.conf for the example:
$SPLUNK_HOME/etc/apps/<MyApp>/default/inputs.conf

Add the following stanza to inputs.conf:

[script://./bin/MyInputScript.py] . . . passAuth = splunk-system-user

How to migrate 3.X apps to 4.1.X

This topic discusses strategies for migrating your 3.x apps to Splunk 4.x. What you choose to do will vary depending on the contents of your app, so first determine which configurations you will migrate and whether or not they are supported in 4.x. First, familiarize yourself with the new configurations in 4.0 by reading through the 4.0 Installation manual topic on what to expect when migrating to 4.0. Next, read about upgrading to 4.1 in the 4.1 Installation manual. In a lot of cases, you can reuse knowledge items (event types, source types, and so on) in your 4.x app. You can also use the information in this topic to rebuild useful 3.x apps created by the Splunk community so that they work on your 4.x deployment.

Inputs and other back-end configurations

Most back-end configuration files -- files that specify how your Splunk server works and your data settings -- can be migrated with no problem. These include authentication.conf, authorization.conf, indexes.conf, inputs.conf, outputs.conf, web.conf. Note that there have been minor changes to these files. If you are not sure whether a specific setting can be migrated, check the spec file. Deployment server configurations have changed completely and must be migrated by hand.

188

Knowledge and presentation settings

Most configuration changes from 3.X to 4.0 are to the knowledge (event types, saved searches, etc.) and presentation (Splunk Web appearance) layers. However, the following files can typically be migrated with no problems: props.conf, transforms.conf, eventtypes.conf, and tags.conf. If you'd just like to copy over your knowledge from a 3.X app to a 4.0 app, you can clone the Search app, and then copy in your event types, tags, props, transforms and other knowledge settings. Note that you must migrate saved searches by hand (as described below). Saved searches and form searches Saved searches and form searches have been modified significantly and must be migrated by hand. You can copy over your savedsearches.conf, or copy in the search string through Splunk Manager. Splunk will migrate these searches, but there are a few things you will need to edit, such as any leftover :: in fields and deprecated search commands. If you want your saved search to be displayed in a dashboard, you will have to add the search to the dashboard, this will create a view state for your new search. Form searches must be created through the new view system -- you cannot migrate your old form search over through savedsearches.conf. Read more about Forms: an introduction in this manual.

Set permissions
4.0 introduces a new object model that sets permissions for all apps and objects (saved searches, reports, views, event types, etc). Once you've migrated your 3.X App to 4.0, set permissions on your app either through Splunk Manager or by adding a default.meta file by hand to your app's directory. Find further instructions on how to set app permissions in this manual. Note: If you've copied in configurations to Splunk by hand (without using Splunk Web) then you must set permissions so the configurations will show up in Splunk Web. If your application is simply a data provider for use in other applications such an firewall scraper app, you may want to just export its configuration globally.

189

Example
This example takes the Web Activity app from SplunkBase (located here). This app contains a savedsearches.conf and a bundle.conf. The saved searches can be migrated into a new app for 4.0 but the bundle.conf is deprecated. Use app.conf instead. Here are step-by-step instructions for migrating this app: 1. Create a new app directory. You can use App Builder, which will automatically create a default.meta, app.conf and other files for you, as well as the entire app directory structure. If you prefer, you can also create a directory by hand in $SPLUNK_HOME/etc/apps/. For example, create a directory $SPLUNK_HOME/etc/apps/web_activity_4. Make sure you add the requisite files (app.conf, default.meta). 2. Copy the old savedsearches.conf into your new app's default directory: $SPLUNK_HOME/etc/apps/web_activity_4/default/savedsearches.conf. You can also copy all the saved searches search strings into Splunk Manager by hand. 3. Edit your saved searches to make sure they work in 4.0, specifically change any instances of :: to =. For example sourcetype::access becomes sourcetype=access. Note that there may be some other issues with your saved searches. Splunk Web will alert you of any issues and you can edit your searches directly through Splunk Manager. 4. Save your edited saved searches. You may need to restart Splunk for your new app to show up. 5. Create new dashboards or edit existing dashboards to showcase your newly migrated saved searches.

What's changed for app developers in 4.2

App ID, version string, and description
An App ID, version string, and a description of an app are required to upload an app or add-on to Splunkbase. Splunk uses the App ID to notify users of updates to an app when the update becomes available on Splunkbase. Splunkbase uses the version string to make sure the latest version is available. The description helps users find apps that fit their needs.

190

Note: Apps uploaded to Splunkbase prior to September, 2010 did not require an App ID. Splunk recommends that you update these apps with an App ID, version string, and description. For these apps, manually update the app configuration file, and then upload the new version of the app to Splunkbase. The following section, Updating a legacy Splunk application on Splunkbase, describes the procedure.

Updating a legacy Splunk application on Splunkbase Here are the steps to update an app on Splunkbase to a new version. Splunk recommends you perform this update, even if there are no other changes in the app.
Define an App ID in the package stanza of app.conf

app.conf is found at $SPLUNK_HOME/etc/apps/<MyApp>/default/. The App ID must be unique on Splunkbase. The App ID must be the same name as the folder containing the app at:
$SPLUNK_HOME/etc/apps/

App IDs can contain only letters, numbers, and the dot '.' and underscore '_' characters. App IDs cannot end with a dot character. App IDs cannot be words that indicate a network location, such as CON, PRN, or LPT1.
Define a version string and description in the launcher stanza of app.conf

Version numbers are a number followed by a sequence of numbers or dots. Pre-release versions can append a space and a single-word suffix like "beta2." Descriptions are limited to 200 characters of text.
Package and upload the new version of the app to Splunkbase

See "Uploading a new version of the app to Splunkbase" below for details. Example app.conf file for UI Examples app
# # Splunk app configuration file #

191

[launcher] version = 1.2 description = This version has been updated to the latest version of Splunk [ui] is_visible = true label = UI Examples [package] id = ui_examples

app.conf spec file The app.conf.spec file provides details on App IDs, version strings, and descriptions. Here are the relevant sections of app.conf.spec. Refer to the app.conf.spec file for additional information.
version = <version string> * Version numbers are a number followed by a sequence of numbers or dots. * Pre-release versions can append a space and a single-word suffix like "beta2". Examples: * 1.2 * 11.0.34 * 2.0 beta * 1.3 beta2 * 1.0 b2 * 12.4 alpha * 11.0.34.234.254 description = <string> * Short explanatory string displayed underneath the app's title in Launcher. * Descriptions should be 200 characters or less because most users won't read long descriptions! [package] id = <appid> * id should be omitted for internal-use-only apps which are not intended to be uploaded to Splunkbase * id is required for all new apps uploaded to Splunkbase. Future versions of Splunk will use appid to correlate locally-installed apps and the same app on Splunkbase (e.g. to notify users about app updates) * id must be the same as the folder name in which your app lives in $SPLUNK_HOME/etc/apps * id must adhere to cross-platform folder-name restrictions: - must contain only letters, numbers, "." (dot), and "_" (underscore)

192

characters - must not end with a dot character - must not be any of the following names: CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9

Uploading a new version of the app to Splunkbase Before uploading a new version of an app, make sure you have provided an AppID, version string, and description as described in the previous section. Prepare your application for upload, as described in Package your app or add-on. Log in to your example on Splunkbase, click Edit, and follow the instructions on the form to upload your app.

Take advantage of Splunk's reduced restart requirements

Splunk 4.2 has reduced restart requirements when you install or update an application. Now there is a system app.conf file, located at $SPLUNK_HOME/etc/system/default/ which lists configuration files that, when delivered by an app update or installation, can be dynamically reloaded (thus avoiding a restart). Configuration changes that are not listed in this file require a restart. For example, if you install an app that contains a new index, you do not need to restart Splunk to see the new index. The [triggers] stanza in the system app.conf file contains the following line, indicating a restart is not necessary:
reload.indexes = access_endpoints /data/indexes

Note: Reduced restart requirements do not apply to changes in the file system change monitor. In inputs.conf, any updates you make for tracking changes to your file system in an [fschange] stanza require a restart of Splunk. If you update or add an [fschange] stanza, then in the [install] stanza of the app's app.conf file, make sure you set the following flag:
state_change_requires_restart = true

For more on the file system change monitor, see Monitor changes to your filesystem.

193

Custom configuration files If your app contains custom configuration files, then by default Splunk requires a restart. If the custom configuration changes do not require a restart, modify the [triggers] stanza in your app's app.conf file. If your custom configuration requires custom code to reload the configuration state change, specify the endpoint for the custom code in your app's app.conf file. The app's app.conf file is located at
$SPLUNK_HOME/etc/app/<MyApp>/default/app.conf

For example:
[triggers] # Do not force a restart of Splunk for state changes of MyApp # Do not run special code to tell MyApp to reload myconffile.conf reload.myconffile = simple # Do not force a restart of Splunk for state changes of MyApp. # Splunk calls the /admin/myendpoint/_reload method in my custom EAI handler. # Use this advanced option only if MyApp requires custom code to reload # the configuration for state change reload.myotherconffile = access_endpoints /admin/myendpoint

State change requires restart flag The [install] stanza of an app's app.conf file now contains a state_change_requires_restart flag with a default value of false. Set this flag to true only when changes to an app's state always require a restart. Typically, you accept the default value of false. Note: state_change_requires_restart = false does NOT prevent an app from requiring a restart. Setting this flag to false simply means that Splunk determines whether a restart is required according to the system app.conf file described above and any settings you may have indicated in the [triggers] stanza in the app's app.conf file. System app.conf file $SPLUNK_HOME/etc/system/default/app.conf

194

[triggers] reload.alert_actions = simple reload.app = simple reload.commands = simple reload.eventtypes = simple reload.history = simple reload.indexes = access_endpoints /data/indexes reload.lookups = simple reload.macros = simple reload.manager = simple reload.nav = simple reload.outputs = access_endpoints /data/outputs/tcp/server reload.props = simple reload.restmap = rest_endpoints reload.savedsearches = simple reload.searchbnf = simple reload.searchscripts = simple reload.tags = simple reload.times = simple reload.transforms = simple reload.views = simple reload.viewstates = simple reload.workflow_actions = simple reload.inputs = access_endpoints /data/inputs/monitor, /data/inputs/script, /data/inputs/udp, /data/inputs/tcp/raw, /data/inputs/tcp/cooked

How to restrict your users to one app

One of the major use cases for creating apps is to keep different users within your organization from accessing certain types of data. For example, your Ops team may only be authorized to see syslog data, while your Application Development team may only see Log4J and Apache data. How can you keep this all separate, but still only run one Splunk instance? This is where apps come in. You can create one app for your Ops team and one app for your Application Development team, each app showcasing the different types of data each team needs access to. Here are instructions on how to set up different apps in Splunk and restrict your users and roles to only the data they should see. First, set up a role for each team. For example, create one role for Ops and one role for Application Development. You can always add users to these roles. Next, set a default app for each role. You can do this from the Roles screen in the Access Controls section of Splunk Manager. Finally, limit your users to only their default app by setting permissions on the apps. Navigate to the App screen in Splunk Manager, and set permissions for
195

each app. You can make the Ops app read only for the Ops team and the Application Development app read only for the Application Development team. Roles can only see the apps they have read permissions to see. Optionally, place more restrictions on the views in each app by removing options from the AccountBar, like the app drop-down and the manager link. You can do this by editing the XML for your view and setting the following configuration for AccountBar:

<module name="AccountBar" layoutPanel="appHeader"> <param name="mode">lite</param> </module>

Note that this is only available in the Advanced XML. If you're using the Simplified XML, translate it to Advanced XML by accessing the showsource endpoint:
http://localhost:8000/en-US/app/<app_name>/<view_name>?showsource=true

196

Build scripted inputs

Scripted inputs overview
Splunk understands many types of data and can immediately index these data sources to make the data available for searching. See What Splunk can index in the Getting Data In manual. Splunk uses line termination characters and timestamps to parse the data into events. It then extracts fields which each event shares, such as host, source, sourcetype, eventtype, timestamp, linecount and others. Splunk also extracts custom per-event fields, such as username and transactionId. However, there are times when you want to use scripts to feed data to Splunk for indexing, or prepare data from a non-standard source so Splunk can properly parse events and extract fields. You can use shell scripts, python scripts, Windows batch files, PowerShell, or any other utility that can format and stream the data that you want Splunk to index. You can stream the data to Splunk or write the data from a script to a file. Streaming data to Splunk In the streaming model, Splunk starts the script at a specified interval. Splunk indexes the stdout data stream from the script. Before Splunk starts a script, it checks to see if the script is already running. If the script is running Splunk does not restart the script. Writing data to a file for Splunk to index In this model, you configure a script to write to a log file. Then configure Splunk to monitor and index the log file. This scenario is basically file input into Splunk. However, you can configure Splunk to launch the program at specific intervals, rather than configure an external method (such as cron or Windows scheduled task) for launching the script. Get data from APIs and other remote data interfaces through scripted inputs in the Getting Data In manual details how to add a scripted input using Splunk Web and how to manually edit the inputs.conf file to add a scripted input. This section focuses on the structure of a script, and provides tips and examples to help you create your own scripts.

Use cases for scripted inputs

Typical use cases for scripted inputs are:
197

 Whenever data is not available as an ordinary file, or the data cannot be sent using TCP or UDP. Stream data from command-line tools, such as vmstat and iostat. Poll a database, web service, or API for specific data, and process the results with Splunk. Reformat complex data so Splunk can more easily parse the data into events and fields. Maintain data sources with slow or resource-intensive startup procedures. Provide special or complex handling for transient or unstable inputs. Scripts that manage passwords and credentials. Wrapper scripts for command line inputs that contains special characters (see "Using a wrapper script" in the Getting Data In manual)

Setting up a scripted input

This section describes how to set up a scripted input for an app. To illustrate the setup, it uses an example script that polls a database and writes the results to a file. A more detailed version of this example is in Example script that polls a database. That topic provides details on the example, including code examples in Python and Java. Note: You can write any number and types of scripts in various scripting languages that perform various functions. This example shows the framework for a commonly found script. Adapt this framework according to your needs.

Script to poll a database

This example script does the following: Runs at a regular interval Queries a database Writes the output to a file in a format optimized for Splunk indexing Splunk indexes the file containing the results of the queries. Directory structure Place scripts in the bin directory of your app:
$SPLUNK_HOME/etc/apps/<myApp>/bin/

Here is the directory structure of the example script for this example. The
198

directory structure for your app might differ.

+ . . ./<myApp>/bin | | | + last_eventid | | | + key | | | + output.txt | | | + starter_script.sh | | | + my_db_poll.py | | | + ip2int.py | | + . . ./<myApp>/default | + inputs.conf | + app.conf

Script files my_db_poll.py This is the script that retrieves information from the database. This script does the following: Queries the database and writes the query result to file Defines the format of output data Accesses a database using credentials stored in key Reads last_eventid to determine the next event to read from the database Queries the database at the next event and writes the output to a file starter_script.sh Wrapper script that calls the my_db_poll.py script. In this example, it calls my_db_poll.py with the arguments needed to query the database. In .../etc/apps/<appName>/default/inputs.conf, create a stanza that references this wrapper script. In this example, the stanza specifies how often to call the starter script to poll the database. ip2int.py
199

A helper script to convert IP addresses from integer format to dotted format, and back. This is a type of helper script that formats data better for Splunk to index. You often have helper scripts that aid the main script. key Text file containing username and password encoded in base64 using the python function base64.b64encode(). The Splunk user has read and write access to this file. Security for passwords is an issue when running scripts. last_eventid File containing a number for the last event received from the database. my_db_poll.py writes the last_eventid after querying the database. The Splunk user has read and write access to this file. output.txt A single event from the script, for reference. my_db_poll.py writes the actual output from querying the database to another directory. . . ./default/inputs.conf Configure scripted data input in $SPLUNK_HOME/etc/myApp/default/inputs.conf. Use the local directory for the app to overwrite behavior defined in the default directory. Here is an example:
[script://$SPLUNK_HOME/etc/apps/<scripted_input_name>/bin/my_db_poll.sh] disabled = true # change to false to start the input, requires restart host = # enter hostname here index = main interval = 30 #frequency to run the script source = my_db sourcetype = my_db_data

$SPLUNK_HOME/etc/system/default/props.conf Configure properties for the script in the Splunk system props.conf:
[my_db] TIME_PREFIX=^[^\|]+\| TIME_FORMAT=%Q MAX_TIMESTAMP_LOOKAHEAD=10

#look ahead 10 characters

200

SHOULD_LINEMERGE=false

$SPLUNK_HOME/etc/system/default/transforms.conf Define field transforms in transforms.conf:

[my_db_extractions] DELIMS = "|" FIELDS ="EventID","AlertTime","UserName",. . ."

Writing reliable scripts

Here are some tips for creating reliable input scripts:

Environment variables
Clear environment variables that can affect your script's operation. One environment variable that is likely to cause problems is the library path. The library path is most commonly known as LD_LIBRARY_PATH on Linux, Solaris, and FreeBSD. It is DYLD_LIBRARY_PATH on OS X, and LIBPATH on AIX. If you are running external python software or using other python interpreters, consider clearing PYTHONPATH. Caution: Changing PYTHONPATH may affect other installations of python. On Windows platforms, the SPLUNKHOME environment variable is set for you. Avoid changing this environment variable. Changing this variable may interfere with the functioning of Splunk services.

Python version
For best results, use the version of Python available from your Splunk installation. Splunk uses this version to execute system scripts, so you should test your script using that version of Python. Some Python libraries your script requires may not be available in Splunk's version of Python. In this case, you can copy the libraries to the same directory as the scripted input. To run a script using the version of Python available from Splunk:

201

$SPLUNK_HOME/bin/splunk cmd python <your_script>.py

File paths in Python

Be careful when specifying platform-specific paths and relative paths. Platform-specific paths When writing scripts in Python, avoid hard coding platform-specific file paths. Instead specify file paths that can be interpreted correctly on Windows, UNIX, and Mac platforms. For example, the following Python code launches try.py, which is in the bin directory of your_app:

import os import subprocess # Edit directory names here if appropriate if os.name == 'nt': ## Full path to your Splunk installation splunk_home = 'C:\Program Files\Splunk' ## Full path to python executable python_bin = 'C:\Program Files (x86)\Python-2.6-32bit\python.exe' else: ## Full path to your Splunk installation # For some reason: #splunk_home = '/appl/opt/splunk_fwd/' # For a sensible OS: splunk_home = '/opt/splunk' ## Full path to python executable # For Mac OS X: #python_bin = '/Library/Frameworks/Python.framework/Versions/2.6/bin/python' # For a sensible filesystem: python_bin = '/usr/bin/python' try_script = os.path.join(splunk_home, 'etc', 'apps', 'your_app', 'bin', 'try.py') print subprocess.Popen([python_bin, try_script], stdout=subprocess.PIPE).communicate()[0]

Relative paths Avoid using relative paths in scripts. Python scripts do not use the current directory when resolving relative paths. For example, on *nix platforms, relative paths are set relative to the root directory (/). The following example shows how to locate the extract.conf file, which is in the same directory as the script:
202

import os import os.path script_dirpath = os.path.dirname(os.path.join(os.getcwd(), __file__)) config_filepath = os.path.join(script_dirpath, 'extract.conf')

Format script output

Format the output of a script so Splunk can easily parse the data. Also, consider formatting data so it is more human-readable as well. Use the Common Information Model The Common Information Model is based on the idea that you can break down most log files into three components: fields, event type tags, and host tags. With these three components you can set up log files in a way that makes them easily processable by Splunk and that normalizes noncompliant log files, forcing them to follow a similar schema. The Common Information model details the standard fields, event type tags, and host tags that Splunk uses when it processes most IT data. For more information, see Understand and use the Common Information Model. Timestamp formats Time stamp the beginning of an event. There are several options for timestamp formats: RFC-822, RFC-3339 These are standard timestamp formats for email headers and internet protocols. These formats provide an offset from GMT, and thus are unambiguous and more human-readable. RFC-822 Tue, 15 Feb 2011 14:11:01 -0800 RFC-3339 2011-02-15 14:11:01-08:00 Note: RFC-822 and RFC-3339 formats can be handled with %z in a TIME_FORMAT setting.

UTC UTC formatting may not be as human-readable as some of the other options. If the timestamp is epoch time, no configuration is necessary. Otherwise, requires a configuration in props.conf that declares the input as TZ=UTC.
203

UTC
2011-02-15T14:11:01-05:00 2011-02-15T14:11:01Z

UTC converted to epoch time

1297738860

Multi-line data and field names For multi-line data, find a way to separate events. Write a distinctive initial line for a multi-line event. Use a special end of event string to separate events. For example, use three newline characters to specify an end of an event. The event would then include any single or double newline characters. For multi-line field values, place the field data inside quotes. Use an equals (=) sign or other separator to expose name/value pairs. For example, key=value. Configure Splunk to use other tokens that might already exist in the data. Field names are case sensitive. For example the field names ?message? and ?Message? represent different fields. Be consistent when naming fields.

Write a setup screen to configure scripted inputs.

If you are packaging an app or add-on for distribution, consider creating a setup screen that allows users to interactively provide configuration settings for access to local scripted input resources. Include an input stanza for your script so setup.xml doesn?t require a custom endpoint. See Configure a setup screen for your app. Refer to the *Nix and Windows apps for examples on using setup.xml pages to create a setup screen. These apps are available for download from Splunkbase.

204

Save state across invocations of the script

Scripts often need to checkpoint their work so subsequent invocations can pick up from where they left off. For example, save the last ID read from a database, mark the line and column read from a text file, or otherwise note the last input read. (See Example script that polls a database.) You can check point either the Splunk index or the script. When check pointing data, keep in mind that the following things are not tied together as a transaction: Writing out checkpoint files Fully writing data into the pipe between the script and splunkd splunkd completely writing out the data into the index Thus, in the case of hard crashes, it?s hard to know if the data the script has acquired has been properly indexed. Here are some of the choices you have: Search Splunk index One strategy is to have the scripted input search in the splunk index to find the last relevant event. This is reasonable in an infrequently-launched script, such as one that is launched every 5 or 10 minutes, or at launch time for a script which launches once and stays running indefinitely. Maintain independent check point Because there is some delay between data being fed to splunk and the data becoming searchable, a frequently run scripted input must maintain its own checkpoint independent of the index. Choose a scenario If the script always believes its own checkpoint, data may not be indexed on splunkd or system crash. If the index search is believed, some data may be indexed multiple times on splunkd or system crash. You need to choose which scenario you best fits your needs.

Accessing secured services

Use proper security measures for scripts that need credentials to access secured resources. Here are a few suggestions on how to provide secure access. However, no method is foolproof, so think carefully about your use case and design secure access appropriately: Restrict which users can access the app or add-on on disk. Create and use credentials specific to the script, with the minimum permissions required to access the data. Avoid putting literal passwords in scripts or passing the password as a command line argument, making it visible to all local processes with
205

operating system access. Use Splunk to encrypt passwords. You can create an app set up page that allows users to enter passwords. (See Providing credentials to access scripts.) The user can enter a password in plain text, which Splunk stores in the credential stanza in apps.conf. Alternatively, you can specify a python script to securely provide access. Caution: Splunk assembles a secret using locally available random seeds to encrypt passwords stored in configuration files. This method provides modest security against disclosure of passwords from admins with local disk read capability. However, it is not an adequate protection for privileged accounts.

Concurrency issues for scripted inputs

Be careful scheduling two copies of a script running at any given time. Splunk detects if another instance of the script is running, and does not launch a new instance if this is the case. For example, if you have a script scheduled to execute every 60 seconds, and a particular invocation takes 140 seconds, Splunk detects this and does not launch a new instance until after the long-running instance completes. At times you may want to run multiple copies of a script, for example to poll independent databases. For these cases, design your scripts so they can handle multiple servers. Also, design your script so that multiple copies can exist (for example, use two app directories for script). Alternatively, you could have separate scripts using the same sourcetype.

Troubleshooting scheduled scripts

Splunk logs exceptions thrown by scheduled scripts to the splunkd.log file, located here:
$SPLUNK_HOME/var/log/splunk/splunkd.log

Check splunkd.log first if expected events do not appear in the expected index after scheduling the scripted input.

Shutdown and restart issues

Keep these shutdown and restart issues in mind when designing your scripts:
206

Output at least one event at a time This makes it easier to avoid reading a partial event if the script is terminated or crashes. Splunk expects events will complete in a timely manner, and has built-in time-outs to prevent truncated or incomplete events. Configure the pipe fd as line-buffered, or write() full events at once. Be sure the events are flushed: line buffered/unbuffered/fflush() Output relatively small batches of events Fetching thousands of event over a few minutes and then outputting them all at once increases the risk of losing data due to a restart. Additionally, outputting small batches of events means your data is searchable sooner and improves script transparency.

Example script that polls a database

Here is an example of a scripted input that polls a database. In the configuration for the script, you specify the interval at which the script runs. Note: No script can be a "one size fits all." The purpose of this example is to provide a basic framework that you modify and customize for your specific purposes. This script polls a database and writes the records retrieved to stdout. The data queries, connection, authentication, and processing of the query have been simplified. This example script does the following: Builds a query to extract 1000 records from a database Connects to a database Stores the key to the database as an eventID. Writes the last eventID retrieved from the database to file to track which events have been indexed. Executes the query and writes the results to stdout for Splunk to index.

Pseudo-code for the example script

# Script to poll a database # # Reads 1000 records from a database, # writes them to stdout for indexing by splunk,

207

# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

tracks last event read SQL Query information: Microsoft SQL Server syntax SELECT TOP 1000 eventID, transactionID, transactionStatus FROM table WHERE eventID > lastEventID ORDER BY eventID

MySQL syntax SELECT eventID, transactionID, transactionStatus FROM table WHERE eventID > lastEventID LIMIT 1000 ORDER BY eventID

Oracle syntax SELECT eventID, transactionID, transactionStatus FROM table WHERE eventID > lastEventID AND ROWNUM <= 1000 ORDER BY eventID ========================== Database Fields ========================== eventID transactionId char transactionStatus varchar ========================= Sample Data ========================= 1 2 3 4 5 A1756202 C1756213 A1756202 N1756754 C1756213 submitted acknowledged rejected submitted completed autoincrement unsigned 8 32

import needed files define SQL query define SQL connection information db server address db user db pw db name define path to file that holds eventID of last record read last_eventid_filepath read eventID from last_eventid file

208

connect to database execute SQL query write query results to stdout close db connection update eventID in last_eventid file

Script example, poll a database (Python)

Here is a python version of the database poll example. The code has been simplified for readability and does not necessarily represent best coding practices. Please modify according to your needs. The Python version of the example accesses a Microsoft SQL Server database. It assumes you have all the necessary libraries referenced in the script. This example requires the following: pymssql language extension FreeTDS 0.63 or newer (*nix and Mac OS X platforms only)

hello_db_poll_script.py
#!/usr/bin/python import _mssql import os import sys from time import localtime,strftime import time sql_server = "SQLserver" #Address to database server database = "hello_db_database" sql_uname = "splunk_user" sql_pw = "changeme" columns = 'TOP 1000 eventID, transactionID, transactionStatus' table = 'hello_table' countkey = 'eventID' last_eventid_filepath = "" # user supplies correct path # Open file containing the last event ID and get the last record read last_eventid = 0; if os.path.isfile(last_eventid_filepath):

209

try: last_eventid_file = open(last_eventid_filepath,'r') last_eventid = int(last_eventid_file.readline()) last_eventid_file.close() # Catch the exception. Real exception handler would be more robust except IOError: sys.stderr.write('Error: failed to read last_eventid file, ' + last_eventid_filepath + '\n') sys.exit(2) else: sys.stderr.write('Error: ' + last_eventid_filepath + ' file not found! Starting from zero. \n') # Fetch 1000 rows starting from the last event read # SELECT TOP 1000 eventID, transactionID, transactionStatus FROM table WHERE eventID > lastEventID ORDER BY eventID sql_query = 'SELECT ' + columns + ' FROM ' + table + ' WHERE ' + countkey + ' > ' + str(last_eventid) + ' ORDER BY ' + countkey try: conn = _mssql.connect(sql_server, sql_uname, sql_pw, database) conn.execute_query(sql_query) # timestamp the returned data indexTime = "[" + strftime("%m/%d/%Y %H:%M:%S %p %Z",localtime()) + "]" for row in conn: print "%s eventID=%s, transactionID=%s, transactionStatus=%s" % (indexTime, row['eventID'], row['transactionID'], row['transactionStatus']) this_last_eventid = row['eventID'] # Catch the exception. Real exception handler would be more robust except _mssql.MssqlDatabaseException,e: sys.stderr.write('Database Connection Error!\n') sys.exit(2) finally: conn.close() if this_last_eventid > 0: try: last_eventid_file = open(last_eventid_filepath,'w') last_eventid_file.write(this_last_eventid) last_eventid_file.close() # Catch the exception. Real exception handler would be more robust except IOError: sys.stderr.write('Error writing last_eventid to file: ' + last_eventid_filepath + '\n')

210

sys.exit(2)

211

Extend Splunk
Extend Splunk
There are several ways you can extend Splunk using the Splunk SDKs, the Splunk REST API, and custom search commands.

Splunk SDKs
Splunk provides a growing list of SDKs that you can use to write applications in third party software that access the Splunk REST API. [Splunk for Developers], the Splunk developer portal, provides details on the available SDKs plus documentation on how to build applications using the SDKs. The SDKs that are currently available include: Python SDK Java SDK JavaScript SDK

Splunk REST API

You can use the Splunk REST API to run searches or manage Splunk configurations and objects without accessing Splunk through Splunk Web.

Custom search commands

Splunk ships with a wide variety of search commands. However, you may want to build your own custom search command to parse and present data in a new way. Custom search commands requires a moderate understanding of Python. Note: Search commands are not recursive -- they only act on the data they receive back from the search.

Splunk SDKs
In Splunk 4.2.3, Splunk introduced Splunk for Developers, a portal for Splunk developers. Splunk for Developers contains information on the available Splunk SDKs. The SDKs provide wrapper functions, methods and modules for the Splunk REST API. These provide access to a Splunk server environment in a
212

programming language you prefer. The Splunk SDKs currently available are: Splunk Python SDK Splunk Java SDK Splunk JavaScript SDK The Splunk SDK Overview contains a roadmap for future development.

Custom search commands

Although the Splunk search language is extensive, you may want to write your own custom search commands. You can add a custom search script to Splunk to create your own search command. Use Python to add your search script. Note: The search command API does not support recursive searching. To build a search that runs recursively, use the REST search API.

Get started
There are two steps to building a search command into Splunk: 1. Build the search command in Python. 2. Add an entry to commands.conf to make Splunk aware of your custom command. Types of commands Command Description
A streaming command is applied as results travel through the search pipeline.

streaming

If your script is not streaming, it only process a single chunk of results. You can specify a search (that contains only streaming commands) to be executed before your non-streaming script, if your script is the very first non-streaming command in the pipeline, or if you have 'requires_preop' set to true (false by default).
A generating command must be the first command specified in a search. Generating commands rely on being passed useful arguments. retains events in commands.conf.

generating retevs

213

This setting indicates that this script outputs events when given events as input. By default this is set to false, meaning that the Timeline never represents the output of this command. Although there is no universal definition of what an event is, generally, if you intend to retain the _rawand _time fields, set retevs to true.
'requires_preop' in commands.conf. reqsop

This setting indicates if the string in the 'preop' variable must be executed, regardless if this script is the first non-streaming command in a search pipeline or not.
Represents both 'generates_timeorder' and 'overrides_timeorder' in commands.conf.

timeorder

'overrides_timeorder' overrides the order of the input to the script. For example, if the input to this script is in descending time order, the output will be in ascending time order. 'generates_timeorder' only applies to generating commands. This setting indicates that the script will ignore the order of the input and always generate output in descending time order.

Build your search command in Python

Python search commands rely on Intersplunk.py to grab events from the search pipeline and pass the modified events back. The arguments passed to your script in sys.argv are the same arguments you use when searching with the command. Handling input The simplest way to get data to your search command is to use splunk.Intersplunk.readResults, which takes three optional parameters and returns a list of dicts representing the list of input events. The optional parameters are input_buf, settings, and has_header. Parameter
inputbuf = None | file

Default
None

Description
Indicates where to read input from.

Set to None by default, which means your search

214

command expects to get data from sys.stdin.

Indicates where to store any information found in the input header. settings = None |

dict None Set to None by default, which means do not record the settings.

has_header = True | False

True

Indicates whether or not to expect an input header.

Here's an example call to splunk.Intersplunk.readResults:

results = splunk.Intersplunk.readResults(None, None, True)

This indicates that you're reading results from the search pipeline. The input to your script will either be pure CSV, or a header section followed by a blank line followed by pure CSV. By setting True in the above example, your command will expect a header with your results. If you set this to False, you must also set the enableheader key in the commands.conf entry for your command. If your script does not expect a header section in the input, you can directly use the Python csv module to read the input. For example:

import csv r = csv.reader(sys.stdin) for l in r: ...

The advantage of this configuration is that you can break at any time in the for loop and only lines in the input that you've iterated to will already be read into memory, leading to much better performance for some cases. Sending output Intersplunk can also be used to construct your script's output. splunk.Intersplunk.generateErrorResults takes a string and writes the correct error output to sys.stdout. splunk.Intersplunk.outputResults takes a list of dict objects and writes the appropriate CSV output to sys.stdout. To output data, add:

splunk.Intersplunk.outputResults(results)

215

The output of your script is expected to be pure CSV. To indicate an error, return a CSV with a single "ERROR" column and a single row (besides the header row) with the contents of the message. Debugging your script If your script has 'supports_getinfo' = true, the first argument to your script must either be __GETINFO__ or __EXECUTE__. Setting 'supports_getinfo' = true is a good tool for debugging as it allows your script to be called with the command arguments at parse time, before any execution of the search. Any syntax errors will stop your search query being executed. If you call your script with __GETINFO__, you can also dynamically specify the properties of your script (such as streaming or not) depending on your arguments. If your script has 'supports_getinfo' set to True, you should first make a call like:

(isgetinfo, sys.argv) = splunk.Intersplunk.isGetInfo(sys.argv)

Which will strip the first argument from sys.argv and check if you are in GETINFO mode or EXECUTE mode. If you are in GETINFO mode, your script should use splunk.Intersplunk.outputInfo() to return the properties of your script or splunk.Intersplunk.parseError() if the arguments are invalid. The definition of outputInfo() is as follows:

def outputInfo(streaming, generating, retevs, reqsop, preop, timeorder=False):

Note: You can also set these attributes in commands.conf.

Add an entry to commands.conf

You must create a commands.conf entry for your command in $SPLUNK_HOME/etc/apps/<app_name>/local/commands.conf. To see all the possible settings in commands.conf, check out the command.conf.spec, in the Admin Manual. Here is a very basic example that just enables your script:

[<script_name>] filename = mypyscript.py

The stanza name in commands.conf is the name of the search script. You'll use this name to call your script from your search. Also, you must set the 'filename' key, which is the name of the script file. Your script should be in either
216

or $SPLUNK_HOME/etc/searchscripts. It's best to put your script in the app directory.

$SPLUNK_HOME/etc/apps/<app_name>/bin/

Example
# Copyright (C) 2005-2009 Splunk Inc. import csv import sys import splunk.Intersplunk import string All Rights Reserved. Version 3.0

(isgetinfo, sys.argv) = splunk.Intersplunk.isGetInfo(sys.argv) if len(sys.argv) < 2: splunk.Intersplunk.parseError("No arguments provided") trendInfoList = [] # list of dictionaries of information about trendlines validTypes = ['sma', 'wma', 'ema'] maxPeriod = 10000 i = 1 while i<len(sys.argv): # expect argument in format: <type><period>(<fieldname>) [as <newname>] arg = sys.argv[i] pos = arg.find('(') if (pos < 1) or arg[-1] != ')': splunk.Intersplunk.parseError("Invalid argument '%s'" % arg) name = arg[0:pos] field = arg[pos+1:len(arg)-1] if len(field) == 0 or field[0:2] == '__': splunk.Intersplunk.parseError("Invalid or empty field '%s'" % field) trendtype = None period = 0 try: for t in validTypes: if name[0:len(t)] == t: trendtype = t period = int(name[len(t):]) if (period < 2) or (period > maxPeriod): raise ValueError except ValueError: splunk.Intersplunk.parseError("Invalid trend period for argument '%s'" % arg)

217

if trendtype is None: splunk.Intersplunk.parseError("Invalid trend type for argument '%s'" % arg) newname = arg; if (i+2<len(sys.argv)) and (string.lower(sys.argv[i+1]) == "as"): newname = sys.argv[i+2] i += 3 else: i += 1 trendInfoList.append({'type' : trendtype, 'period' : period, 'field' : field, 'newname' : newname, 'vals': [], 'last': None})

if isgetinfo: splunk.Intersplunk.outputInfo(False, False, True, False, None, True) # outputInfo automatically calls sys.exit()

results = splunk.Intersplunk.readResults(None, None, True) for res in # each for ti if results: res is a dict of fields to values in trendInfoList: ti['field'] not in res: continue

try: ti['vals'].append(float(res[ti['field']])) except ValueError: continue # ignore non-numeric values if len(ti['vals']) > ti['period']: ti['vals'].pop(0) elif len(ti['vals']) < ti['period']: continue # not enough data yet newval = None if ti['type'] == 'sma': # simple moving average newval = sum(ti['vals']) / ti['period'] elif ti['type'] == 'wma': # weighted moving average Total = 0 for i in range(len(ti['vals'])): Total += (i+1)*(ti['vals'][i]) newval = Total / (ti['period'] * (ti['period']+1) / 2)

218

elif ti['type'] == 'ema': # exponential moving average if (ti['last'] is None): newval = ti['vals'][-1] else: alpha = float(2.0 / (ti['period'] + 1.0)) newval = (alpha * ti['vals'][-1]) + (1 - alpha) * ti['last'] ti['last'] = newval res[ti['newname']] = str(newval)

splunk.Intersplunk.outputResults(results)

Answers
Have questions? Visit Splunk Answers to see what questions and answers other Splunk users had about custom search commands.

Splunk's API is RESTful

Splunk's API is RESTful, which means it uses HTTP requests to interact with resources within Splunk. You can use the REST API to configure and manage a Splunk instance, create and run searches in Splunk, or create your own applications that interact with Splunk. You can use any language or tool that supports HTTP calls to access the Splunk REST API. In Splunk 4.2.3, the [Documentation:Splunk:RESTAPI:RESTintro|Splunk REST API Reference]] became available, detailing all available REST endpoints. Splunk for Developers became available at the same time, providing an Overview of the REST API, as well as tutorials, examples, and how-tos.

About the Splunk REST API Reference

The Splunk REST API Reference is now available as a separate manual. Highlights of the Splunk REST API Reference include: Overview page describing the contents of the reference Index page to all publicly available endpoints Series of topics on using the REST API Creating searches using the REST API
219

The Splunk REST API Reference also includes several examples: Authenticating yourself to the Splunk server to access Splunk endpoints Accessing and updating Splunk configurations Some basic examples using the Splunk REST API Create a search and retrieve the results The REST API Overview at Splunk for Developers provides additional tutorials and examples

220

View reference material

Panel reference for Simplified XML
Use the panel reference when building simple dashboards or from searches from Splunk's Simplified XML. It lists configuration options for the various types of panels you can use, plus includes an example configuration for each. There are general settings that can be applied to all panels. Different types of panels have specific configuration options.

General panel configuration

Options for all panels Tag
<title>title</title>

Description
Add a title to your panel, such as

Failed logins. This title display at the top of the panel.

Specify a saved search to load in your panel. Make sure the saved search is shared with all users and roles who access the dashboard. The saved search must exist in savedsearches.conf in the

<searchName>saved search</searchName>

App's default or local directory, the user's directory for private apps, or be set as global.
<searchString>search string</searchString> <fields>comma separated list of fields</fields> <earliestTime>Splunk time format</earliestTime> Specify an inline search to run whenever the dashboard loads. Restrict your search results to specific fields. Restrict your search results to a specific time window, starting with the earliestTime. Specify "rt" to enable real-time searches. Restrict your search results to a specific time window, ending with the latestTime. Specify "rt" to enable real-time searches.

<latestTime>Splunk time format</latestTime>

221

Example Here's an example of a table panel with three general options and two panel specific options.

. . . <table> <title>Look here for errors that you need to care about</title> <searchName>Errors in the last 24 hours</searchName> <fields>host, source, errorNumber</fields> <option name="count">25</option> <option name="displayRowNumbers">true</option> </table> . . .

Table panel
The table panel displays search data as a table. Use the <searchName> tag to specify which saved search results to display as a table. Use other general options as specified above. Options for table panels Tag
<count>integer</count>

Description
The maximum number of rows to display.

Toggle display of row <displayRowNumbers>(true|false)</displayRowNumbers> numbers to the left of results. <showPager>(true|false)</showPager> Show paging in the table.

Example Here's an example of a table panel specifying 25 rows and displaying the row numbers.

. . . <table> <title>Look here for errors that you need to care about</title> <searchName>Errors in the last 24 hours</searchName> <option name="count">25</option> <option name="displayRowNumbers">true</option> </table>

222

. . .

Chart panel
The chart panel displays search data in chart format. Pair the chart panel with a saved report you've already created. Saved reports contain chart formatting parameters. Saved searches, on the other hand, do not. For more information, see "Save reports and share them with others" in the User manual. 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. The table below lists a few of these options. See the Custom Charting Configuration Reference in this Manual for details on specifying chart options. Options for chart panels Tag
<option name="charting.chart">(bar|line|column|area|pie|scatter|bubble)</option> <option name="charting.legend.placement">(top|left|bottom|right|none)</option> <option name="charting.chart.height">CSS dimension</option>

Description
Set the chart type. Indicates the placement of the legend. Set the height of the chart. All of the chart formatting options are supported here; see the

<option name="charting.*"></option>

custom charting configuration reference chapter in this Manual.

Example This example shows a line chart panel for an inline search. It limits results to a specified time window, and provides labels for the X and Y axes.

223

. . . <chart> <searchString> index=_internal metrics group="pipeline" NOT sendout | head 1000 | timechart per_second(cpu_seconds) by processor </searchString> <earliestTime>-30h</earliestTime> <latestTime>-10h</latestTime> <option name="charting.chart">line</option> <option name="charting.primaryAxisTitle.text">Time</option> <option name="charting.secondaryAxisTitle.text">Load (%)</option> </chart> . . .

Event panel
The event panel displays the search results as individual events. Options for event panels Tag
<count>integer</count>

Description
The maximum number of rows to display. Toggle display of row numbers to the left of results. Toggle whether to show events or results. Events are individual events, while results are created by statistical operators. Defaults to results.

<displayRowNumbers>(true|false)</displayRowNumbers>

<entityName>(events|results)</entityName>

Set the segmentation of events displayed. This <segmentation>(none|inner|outer|full)</segmentation> affects what you can and can't click on within the event. <maxLines>Integer</maxLines> The maximum number of lines to display for each result/event. Toggle pagination on or off.

<showPager>(true|false)</showPager>

224

Example The following example shows an event panel specifying which fields to display, showing the pager, display 20 rows per page, and do not display row numbers.

. . . <event> <title>Event view</title> <searchString>changelist | head 1000 | dedup changelist</searchString> <fields>added deleted changed</fields> <option name="showPager">true</option> <option name="count">20</option> <option name="displayRowNumbers">false</option> </event> . . .

Single value panel

The single value panel displays the result of a search that returns a single 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. You can change the color of the panel by specifying a rangemap for the returned values. Options for single value panels Tag
<additionalClass>CSS class name</additionalClass>

Description

An optional additional css class na to add to the result container. Specify which view to execute the linked search against. Defaults to dashboard.

<code><linkView>view</linkView>

<field>field</field>

Field to display. Defaults to first fie returned.

<linkFields>(result|beforeLabel|afterLabel)</linkFields>

Set which part of the text in the sin value to use as a link. To link the re and both labels, set as result,beforeLabel,afterLa Defaults to result

<classField>("class"|severe|elevated|low|None|)</classField> Adds the value of the classField of first result as an additional CSS cla to the result container. Pre-defined

225

classes include severe, elevate low, and None. Default is None <beforeLabel>text</beforeLabel> <afterLabel>text</afterLabel> <linkSearch> search query</linkSearch> Label to display before the result. Label to display after the result.

Specify a valid complete search qu to turn the result into a clickable lin

Example The following example specifies a single value to display with a label after the value.

. . . <single> <searchString>| metadata type="sources" | stats count</searchString> <option name="afterLabel">sources</option> </single>

To change colors of the single results display, specify a range map in your search. Also, add range for the classField option.

<pre> <single> <searchString>index=_internal 404 source="*web_access.log" earliest=-1h | stats count | rangemap field=count low=0-0 elevated=1-100 default=severe</searchString> <title>404s this hour</title> <option name="classField">range</option> </single> . . .

HTML panel
The HTML panel displays inline HTML. The panel interpets the entire contents between the HTML tags literally, displayed 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. Example

. . . <html> This lists all of the data you have loaded into

226

<strong>your</strong> default indexes over all time. </html> . . .

List panel
The list panel displays data in a list. Use this panel to display information from saved searches or search results. This panel supports the following options. Required options for list Tag
<labelField>field name</labelField> <valueField>field name</valueField>

Description
The field you want to use to generate labels for your list. The field you want to use to generate values for the labels in your list.

Optional options for list Tag

<initialSortDir>(asc|desc)</initialSortDir>

Description
The direction to sort the results based on the initialSort field. The search string to generate when the user clicks on the label field. Requires labelFieldTarget to be

<labelFieldSearch>search string</labelFieldSearch>

defined to a valid view. The value of the label field is automatically added to the search.
Required. The name of the result field whose value should be displayed in the label part of the link list. Link lists are generally a combination of a descriptive label and a numeric count or other (value) field. (Optional) The view to target if the label field is setup to generate a clickable link that dispatches a search. (Optional) The field in the result set to sort on when the link list is first

<valueField></valueField>

<labelFieldTarget></labelFieldTarget>

<initialSort></initialSort>

227

rendered.

Example The following example shows a list panel listing the sourcetype for errors, followed by host name for the error:

. . . <list> <searchName>Errors in the last 24 hours</searchName> <option name="labelField">sourcetype</option> <option name="valueField">host</option> </list> . . .

Module Reference
Base class
Splunk.Module This is the abstract base class for all modules.
required params

(none)
optional params

(none) DM_IFrame (extends IFrameInclude) This module provides the Deployment Monitor app with the ability to load a custom controller without a priori knowledge of the app namespace
required params

(none)

228

optional params

check_exists = False | True DEPRECATED This checks to see if the remote or local src exists. It defaults to false. NOTE: Local app static files are skipped if check_exists is set to True. defaults to: False height The numeric pixel value constraint of your iframe or defaults to auto. NOTE: Remote URI's require the appropriate JavaScript document.domain setting for fluid height to work correctly (see http://msdn.microsoft.com/en-us/library/cc196989(VS.85).aspx and https://developer.mozilla.org/en/DOM/document.domain) defaults to: auto src Not required by this module DispatchingModule (extends Splunk.Module) This is the abstract base class for all modules that can only work with dispatched searches.
required params

(none)
optional params

(none) UnixDrilldown (extends Splunk.Module) This module handles custom drilldown for the Unix app
required params

(none)
optional params

drilldownKey Specify the field name for the drilldown, or omit to use just the event search for drilldown

229

Unix_FTR (extends Splunk.Module) This module provides the facility to check if the unix app has been configured, as well as if the ta-unix add-on is concurrently installed, which represents a potential collision
required params

configLink This parameter is the relative URL that admins should be redirected to
optional params

(none) Unix_IFrame (extends IFrameInclude) This module provides the Splunk *nix App with the ability to load a custom controller without a priori knowledge of the app namespace
required params

(none)
optional params

check_exists = False | True DEPRECATED This checks to see if the remote or local src exists. It defaults to false. NOTE: Local app static files are skipped if check_exists is set to True. defaults to: False height The numeric pixel value constraint of your iframe or defaults to auto. NOTE: Remote URI's require the appropriate JavaScript document.domain setting for fluid height to work correctly (see http://msdn.microsoft.com/en-us/library/cc196989(VS.85).aspx and https://developer.mozilla.org/en/DOM/document.domain) defaults to: auto src Not required by this module

230

Converters
ConvertToDrilldownSearch (extends Splunk.Module) EXPERIMENTAL.
required params

(none)
optional params

drilldown.direction = up | down EXPERIMENTAL - this determines whether drilldown intentions are send to downstream modules or to upstream modules. defaults to: down drilldownPrefix Not required. Since this defaults to 'click', by default the module will look for the keys 'click.name', 'click.value', 'click.name2', 'click.value2'. In cases where you are nesting multiple drilldown patterns in the same view, this key is available to look for keys like 'click2.name', or 'hostClick.value' instead. defaults to: click enableDebugOutput = True | False when on, there will be some fields that output the args to the drilldown intention, as well as the timerange and underlying base Search defaults to: False ConvertToIntention (extends Splunk.Module) Converts a setting value to an intention, which it adds to its context and passes to its children.
required params

intention This is the intention to add to the current search context. If 'settingToConvert' is defined, use the "$target$" keyword within the intention somewhere to specify which value in the intention to replace. If 'settingToConvert' is omitted, you do not use "$target$" but instead specify the setting name or names directly , ie "$selectedHost$".
231

optional params

preserveParentIntentions LEGACY. Has no function. this module was changed to *always* preserve existing intentions @62089 in june 2009, but this associated param was never removed. defaults to: False settingToConvert When set, this defines the name of a single setting value that will be set the intention, and which is then specified with a special "$target$" syntax. It's easier to not set this parameter, in which case you're allowed to specify the keys directly like "selectedHost" or "$foo.bar$"; ConvertToRedirect (extends Splunk.Module)
required params

settingToConvert type
optional params

(none)

Form elements
StaticRadio (extends AbstractStaticFormElement)
required params

name settingToCreate staticFieldsToDisplay

optional params

checked label searchWhenChanged

232

 defaults to: True StaticSelect (extends AbstractStaticFormElement)

required params

settingToCreate staticFieldsToDisplay
optional params

label searchWhenChanged defaults to: True selected

Include
AjaxInclude (extends Splunk.Module) EXPERIMENTAL. A simple wrapper for integrating external content via XMLHTTPRequest within the module framework. Note this is limited to same domain constraints. Emulates iframe like behavior (page is not refreshed on clicks) and binds an ajaxForm handler to all forms.
required params

endpoint This determines the initial endpoint.

optional params

data The associated query string name/value pairs to add to the POST/GET request. focus An optional element selector to apply form element focus on. See http://docs.jquery.com/Selectors for selector syntax. Defaults to an auto-focus algorithm if undefined. To disable auto-focus provide an invalid selector such as "foobar" hrefattributes
233

 The regular expression attributes for anchor element href attribute values that should not refresh the page on click/keydown. Defaults to no attributes excluding anchor elements with target or rel values. hrefpattern The regular expression pattern for anchor element href attribute values that should not refresh the page on click/keydown. Defaults to matching everything excluding anchor elements with target or rel values. defaults to: .* method = GET | POST The type of initial request to make "POST" or "GET". defaults to: GET IFrameInclude (extends Splunk.Module) This simple module uses an inline frame (iframe) to show content from another URL.
required params

src This is the URL to a remote resource to be displayed in the module. Supports remote URI's (ie., http://foobar.com/hello), local app static files (ie., hello.html found in $SPLUNK_HOME/etc/apps/$APPNAME/appserver/static) and relative locations (ie., /manager).
optional params

check_exists = False | True DEPRECATED This checks to see if the remote or local src exists. It defaults to false. NOTE: Local app static files are skipped if check_exists is set to True. defaults to: False height The numeric pixel value constraint of your iframe or defaults to auto. NOTE: Remote URI's require the appropriate JavaScript document.domain setting for fluid height to work correctly (see http://msdn.microsoft.com/en-us/library/cc196989(VS.85).aspx and https://developer.mozilla.org/en/DOM/document.domain) defaults to: auto

234

ServerSideInclude (extends Splunk.Module) This module supports the concept of server side includes for custom content. Additionally, the Mako (see: http://www.makotemplates.org/) template language is supported.
required params

src This specifies the static html file that should be displayed in the given view. When you give it a filename, Splunk attempts to fetch the file from the current application static folder: /etc/apps/<app_name>/appserver/static/* (Note: absolute URI's not supported). If the resource can't be found, a simple message inline is displayed.
optional params

(none)

Jobs
JobManager (extends Splunk.Module) This large module dominates the page and is intended to supply management functionality for many previously dispatched searches.
required params

jobStatusSetting namespaceSetting ownerSetting

optional params

count defaults to: 10 offset defaults to: 0 sortDir defaults to: desc sortKey defaults to: dispatch_time
235

JobStatus (extends DispatchingModule) This module is intended to supply basic search management functionality and information/general status information.
required params

(none)
optional params

actionsMenuFilter Sets the filter on which action menu items to show. defaults to: False autoPauseInterval Number of seconds to wait before automatically pausing the running job; only active when the Search.Context object contains a 'auto_pause' setting = true. defaults to: 30 enableWizards = True | False Controls the display of wizard work flows. defaults to: True hideOnJobDone = True | False in certain cases (notably in Report Builder), the JobStatus module is only visible while the search is running, and when the search has finished, it dissappears and a different module takes its place. defaults to: False resultsLink This param itself contains nested params. It is a dictionary of config values that specifies behaviour for a link that should only be shown to the user when the search has completed. The link sends the user to the configured view (within the same app), and Splunk loads that view with these search results. Contains a required 'viewTarget' sub-param that is the view to which the user should be sent. And also an optional 'popup' sub-param that when True will make the link open a new popup window. showCreateMenu Set a bool to determin if the Create menu should be displayed defaults to: True showSaveMenu Set a bool to determin if the Save menu should be displayed defaults to: True

236

Lister
EntityLinkLister (extends AbstractEntityLister)
required params

entityPath This should be a valid entity path such as saved/searches.

optional params

count The number of list elements to list. This value only pertains to the dynamically generated list elements, not to the static elements. In some concrete implementations, this value can be provided by a Paginator module and provide paging behavior. delimiter The character to use to separate each listed field. Some concrete implementations of lists do not use the delimiter, such as the options lister. defaults to: | entityFieldsToDisplay The entity fields to display. These are specified as <list> objects in a view xml specification and must contain at least a "label" definition or a "multiLabel" definition. If "label" is defined it should be set to the name of a field in the entity listing that will become the label of the generated list. If "multiLabel" is defined it must be specified as a Python sprintf string where the tokens should map to fields in the entity list. The <list> object may also contain the following options: "value" definition which is used by child classes to define the lister's behavior. namespace The namespace to use when requesting the list of entities. Normally this defaults to the current application's name. offset The starting offset for the dynamically generated list elements. outputMode This is set to li by default so it need not be declared in a view configuration file. DO NO CHANGE THIS (unless you really know what you're doing). defaults to: li
237

 owner The owner to use when requesting the list of entities. Normally this defaults to the current user. postProcess The post process search to apply to the entity request. searchWhenChanged Usually the concrete Lister modules push their changes to their children when a user has acted on the list of elements. In some cases this is not desirable, such as in the simplified form configurations. defaults to: True settingToCreate The setting to generate and pass down to child modules. sortDir = asc | desc The direction to sort the results. This option may only be defined if the sortKey option is also defined. sortKey The field on which to sort the results. This is often deferred to Python's default sort algorithm and will observe Python's sort behavior. staticFieldsToDisplay A set of <list> objects which define static list elements to add to the dynamically generated list elements. For example a static option with a label of "Any" and a value of "*" might be desired in addition to a list of saved searches generated by the entity lister. Static fields are defined in much the same way as entity fields, as <list> objects with a "label" definition that is set to the explicit label (i.e. "Any") and an optional value definition set to the value (i.e. "*"). EntityRadioLister (extends AbstractEntityLister)
required params

entityPath This should be a valid entity path such as saved/searches. name The name of the form to create. settingToCreate

238

optional params

checked The radio button to select after rending the options from a search. count The number of list elements to list. This value only pertains to the dynamically generated list elements, not to the static elements. In some concrete implementations, this value can be provided by a Paginator module and provide paging behavior. delimiter The character to use to separate each listed field. Some concrete implementations of lists do not use the delimiter, such as the options lister. defaults to: | entityFieldsToDisplay The entity fields to display. These are specified as <list> objects in a view xml specification and must contain at least a "label" definition or a "multiLabel" definition. If "label" is defined it should be set to the name of a field in the entity listing that will become the label of the generated list. If "multiLabel" is defined it must be specified as a Python sprintf string where the tokens should map to fields in the entity list. The <list> object may also contain the following options: "value" definition which is used by child classes to define the lister's behavior. label The label to apply to the set of radio buttons. namespace The namespace to use when requesting the list of entities. Normally this defaults to the current application's name. offset The starting offset for the dynamically generated list elements. outputMode This is set to radio by default so it need not be declared in a view configuration file. DO NO CHANGE THIS (unless you like s as radio buttons). defaults to: radio owner The owner to use when requesting the list of entities. Normally this defaults to the current user. postProcess The post process search to apply to the entity request. searchWhenChanged

239

 Usually the concrete Lister modules push their changes to their children when a user has acted on the list of elements. In some cases this is not desirable, such as in the simplified form configurations. defaults to: True sortDir = asc | desc The direction to sort the results. This option may only be defined if the sortKey option is also defined. sortKey The field on which to sort the results. This is often deferred to Python's default sort algorithm and will observe Python's sort behavior. staticFieldsToDisplay A set of <list> objects which define static list elements to add to the dynamically generated list elements. For example a static option with a label of "Any" and a value of "*" might be desired in addition to a list of saved searches generated by the entity lister. Static fields are defined in much the same way as entity fields, as <list> objects with a "label" definition that is set to the explicit label (i.e. "Any") and an optional value definition set to the value (i.e. "*"). EntitySelectLister (extends AbstractEntityLister)
required params

entityPath This should be a valid entity path such as saved/searches. settingToCreate

optional params

count The initial number of entity items to load. delimiter The character to use to separate each listed field. Some concrete implementations of lists do not use the delimiter, such as the options lister. defaults to: | entityFieldsToDisplay The entity fields to display. These are specified as <list> objects in a view xml specification and must contain at least a "label"
240

definition or a "multiLabel" definition. If "label" is defined it should be set to the name of a field in the entity listing that will become the label of the generated list. If "multiLabel" is defined it must be specified as a Python sprintf string where the tokens should map to fields in the entity list. The <list> object may also contain the following options: "value" definition which is used by child classes to define the lister's behavior. label namespace The namespace to use when requesting the list of entities. Normally this defaults to the current application's name. offset The starting offset for the dynamically generated list elements. outputMode This is set to options by default so it need not be declared in a view configuration file. DO NO CHANGE THIS (unless you like s in your <select>s). defaults to: options owner The owner to use when requesting the list of entities. Normally this defaults to the current user. postProcess The post process search to apply to the entity request. searchWhenChanged Usually the concrete Lister modules push their changes to their children when a user has acted on the list of elements. In some cases this is not desirable, such as in the simplified form configurations. defaults to: True selected The option to show as selected. This is based on the label value, for example "selected = Edit" looks for an option whose label value is also "Edit". sortDir = asc | desc The direction to sort the results. This option may only be defined if the sortKey option is also defined. sortKey The field on which to sort the results. This is often deferred to Python's default sort algorithm and will observe Python's sort behavior. staticFieldsToDisplay A set of <list> objects which define static list elements to add to the dynamically generated list elements. For example a static option
241

with a label of "Any" and a value of "*" might be desired in addition to a list of saved searches generated by the entity lister. Static fields are defined in much the same way as entity fields, as <list> objects with a "label" definition that is set to the explicit label (i.e. "Any") and an optional value definition set to the value (i.e. "*"). SearchLinkLister (extends AbstractSearchLister)
required params

(none)
optional params

applyOuterIntentionsToInternalSearch if set to True, any intentions passed down from an upstream module will be used to drive the internal search of this module. This should be used with caution, but when used carefully allows form elements to drive each others searches in interesting ways. applyOuterTimeRangeToInternalSearch if set to True, any timeRange passed down from an upstream module like TimeRangePicker, in addition to being used to effect the main searches in the page, will also be used to drive the internal search of this module. delimiter defaults to: | earliest The earliest time to bound the search results by. entityName = events | results The type of search result data the module would like to work with. When entityName == results statusBuckets is set to 0, which cannot be overridden, in an attempt to significantly speed up the search. defaults to: results latest namespace outputMode This is set to li by default so it need not be declared in a view configuration file. DO NO CHANGE THIS. defaults to: li owner
242

 postProcess The post process search to apply to the search request. savedSearch A valid saved search name. search A valid Splunk search string used to power the internal representation of the module. searchFieldsToDisplay searchWhenChanged Usually the Lister modules should push their changes to their children. In some cases this is not desirable, such as in the simplified form configurations. defaults to: True settingToCreate sortDir sortKey staticFieldsToDisplay statusBuckets defaults to: 300 tokenPrefix defaults to: click useHistory When "savedSearch" is defined, this dictates whether a new job based on a saved search should be dispatched (useHistory == False), a cached job from a saved search's history should be used (useHistory == True) or if no job is cached in the saved search's history, dispatch a new job (useHistory == auto). defaults to: Auto SearchRadioLister (extends AbstractSearchLister)
required params

name The name of the form to create.

optional params

applyOuterIntentionsToInternalSearch if set to True, any intentions passed down from an upstream module will be used to drive the internal search of this module. This
243

should be used with caution, but when used carefully allows form elements to drive each others searches in interesting ways. applyOuterTimeRangeToInternalSearch if set to True, any timeRange passed down from an upstream module like TimeRangePicker, in addition to being used to effect the main searches in the page, will also be used to drive the internal search of this module. checked The radio button to select after rending the options from a search. delimiter defaults to: | earliest The earliest time to bound the search results by. entityName = events | results The type of search result data the module would like to work with. When entityName == results statusBuckets is set to 0, which cannot be overridden, in an attempt to significantly speed up the search. defaults to: results label The label to apply to the set of radio buttons. latest namespace outputMode This is set to radio by default so it need not be declared in a view configuration file. DO NO CHANGE THIS (unless you like s as radio buttons). defaults to: radio owner postProcess The post process search to apply to the search request. savedSearch A valid saved search name. search A valid Splunk search string used to power the internal representation of the module. searchFieldsToDisplay searchWhenChanged Usually the Lister modules should push their changes to their children. In some cases this is not desirable, such as in the simplified form configurations. defaults to: True settingToCreate
244

 sortDir sortKey staticFieldsToDisplay statusBuckets defaults to: 300 tokenPrefix defaults to: click useHistory When "savedSearch" is defined, this dictates whether a new job based on a saved search should be dispatched (useHistory == False), a cached job from a saved search's history should be used (useHistory == True) or if no job is cached in the saved search's history, dispatch a new job (useHistory == auto). defaults to: Auto SearchSelectLister (extends AbstractSearchLister)
required params

(none)
optional params

applyOuterIntentionsToInternalSearch if set to True, any intentions passed down from a parent module will be used to drive the internal search of this module. This should be used with caution, but when used carefully allows form elements to drive each others searches in interesting ways. applyOuterTimeRangeToInternalSearch if set to True, any timeRange passed down from an upstream module like TimeRangePicker, in addition to being used to effect the main searches in the page, will also be used to drive the internal search of this module. count The initial number of entity items to load. delimiter defaults to: | earliest The earliest time to bound the search results by. entityName = events | results

245

 The type of search result data the module would like to work with. When entityName == results statusBuckets is set to 0, which cannot be overridden, in an attempt to significantly speed up the search. defaults to: results label latest namespace outputMode This is set to options by default so it need not be declared in a view configuration file. DO NO CHANGE THIS (unless you like s in your <select>s). defaults to: options owner postProcess The post process search to apply to the search request. savedSearch A valid saved search name. search A valid Splunk search string used to power the internal representation of the module. searchFieldsToDisplay searchWhenChanged Usually the Lister modules should push their changes to their children. In some cases this is not desirable, such as in the simplified form configurations. defaults to: True selected The option to show as selected. This is based on the label value, for example "selected = Edit" looks for an option whose label value is also "Edit". settingToCreate sortDir sortKey staticFieldsToDisplay statusBuckets defaults to: 300 tokenPrefix defaults to: click useHistory When "savedSearch" is defined, this dictates whether a new job based on a saved search should be dispatched (useHistory == False), a cached job from a saved search's history should be used
246

(useHistory == True) or if no job is cached in the saved search's history, dispatch a new job (useHistory == auto). defaults to: Auto

Messaging
Message (extends DispatchingModule) This module can display all messages to the user, or can be configured to display just a certain class of messages. Messages might come from searches, from alerts firing, from misconfiguration on the backend, from information about indexing status etc. The simplest configuration is a single Message instance with filter set to '*' -- meaning it will display all the messages broadcast. However, you can use multiple Message modules with different 'filter' params displayed in separate layout panels throughout a view. Messages are passed with a defined class, such as splunk.search.error. So if you have two Message instances, one configured with a filter of '*', and another with a filter of splunk.search, the latter will receive the splunk.search.error events, and the "*" instance will not. However when an unexpected message is passed down with the class of splunk.indexing.warn, the splunk.search instance will not display it but the the '*' instance will.
required params

clearOnJobDispatch Set to True to clear messages whenever a new search is dispatched. filter Specify a filter to listen to only certain classes of messages. When blank, the module displays all the messages broadcast. maxSize Set the number of messages to display before throwing away the oldest ones.
optional params

default When present, the module loads with this value showing. level When set, will only emit messages equal to or higher than the specified level. defaults to: *

247

Nav
AccountBar (extends Splunk.Module) The bar at the top of most views, that contains the logo, says logged in as <user>, and contains the logout and admin links.
required params

(none)
optional params

cancelJobsOnLogoClick = True | False Controls if a click on the app logo cancels all jobs or not. defaults to: True mode = popup | full | lite When this is set to 'popup,' there are no links, the logo cannot be clicked, the view name is displayed instead of the app name, and there is a close button in the upper right. 'lite' mode displays only the account links and a back link, no logo or app menu. defaults to: full popupTitle Title shown next to the Splunk logo on AccountBar in popup mode AppBar (extends Splunk.Module) This is the bar second from the top in most views. It contains the top level view categories (by default Dashboards Views Saved Searches), and the auxiliary links section (help | preferences | about).
required params

(none)
optional params

(none) BreadCrumb (extends Splunk.Module) Simple navigation breadcrumb for a multi-view flow.

248

required params

(none)
optional params

goBackOnJobCancelled = True | False If True, whenever any job on the current page is cancelled the module will take the user away from the current view. If the module has no 'earlier' links, it will go to the default view in the current app. If the module does have a link to an 'earlier' view then it will go there. At that point it will make an effort to commit outstanding viewstate changes, swap out the (now dead) 'sid' for a corresponding 'q' arg in the permalink, and preserve any other existing querystring arguments. defaults to: False options This is a list of views to link to as well as labels for the links. When absent, the Breadcrumb module can still print out the saved search name, or saved report name. DashboardTitleBar (extends DispatchingModule) A simple dashboard title bar with edit controls for simple xml dashboards.
required params

(none)
optional params

(none) ManagerBar (extends Splunk.Module) This is a header bar that shows up at the top of the view. Used specifically in Splunk Manager. When present in any view, it will display a header of "Manager: <view name>".
required params

(none)

249

optional params

(none) TitleBar (extends DispatchingModule) Control menu/actions menu. This module is persistent, and contains information such as the name of the dashboard, the name of the view, or the name of the view and associated saved search. The titlebar functions as a place for contextual actions, like saving a new search that has been run after loading a view.
required params

(none)
optional params

actionsMenuFilter Sets the filter on which action menu items to show. defaults to: False showActionsMenu = True | False Toggle whether or not to show the actions menu. defaults to: True

Report builder
AdvancedModeToggle (extends Splunk.Module) this is a class that wont be used outside of report builder, documentation for which is TBD.
required params

(none)
optional params

(none)

250

BaseReportBuilderField (extends Splunk.Module) This is the abstract base class of all of the report_builder modules that effect the underlying search.
required params

(none)
optional params

(none) ReportBuilderSearchField (extends BaseReportBuilderField) this is a class for report builder, that has significantly more complex behaviour than SearchField, and is useful only in the report_builder view
required params

(none)
optional params

(none) ReportSubType (extends BaseReportBuilderField) This module contains a pulldown that allows you to split 'trend over time' and 'correlation' searches by a single field, split them by multiple series, or not split them at all.
required params

(none)
optional params

(none)

251

ReportType (extends BaseReportBuilderField) This module contains a pulldown that allows you to select the general type of report that you are trying to build. Examples of its options are 'trend over time', 'correlation', 'top values of a given field' etc..
required params

(none)
optional params

(none) SingleFieldChooser (extends BaseReportBuilderField) This module contains a pulldown that allows you to select the field that you wish to use on the y-axis. This is generally used in conjunction with StatChooser which specifies the aggregator function for this field chosen here. Eg. if this module is set to 'kbps', and StatChooser is set to 'max', then the overall y-axis value will be max(kbps)
required params

(none)
optional params

(none) SplitByChooser (extends BaseReportBuilderField) This module contains a pulldown that allows you to select the field that you wish to split by, when doing a 'trend over time' or 'correlation' search, and when youve chosen to split by a single field.
required params

(none)
optional params

(none)

252

StatChooser (extends BaseReportBuilderField) This module contains a pulldown that allows you to select the aggregator function that you wish to apply to your y-axis field. Its options include functions like 'sum', 'average', 'count' and 'distinct count', .
required params

(none)
optional params

(none) TimeRangeBinning (extends BaseReportBuilderField) This module contains a text field and a pulldown, that together the user can use to set the size of buckets in 'trend over time' searches. The first field takes an integer, and the pulldown contains options of 'month, day, hour, minute, second'
required params

(none)
optional params

(none)

Paginator
Paginator (extends DispatchingModule) This module displays a series of links to page around in your data. It must be configured to page either through the 'events' or the 'results' of your search.
required params

entityName = events | results | settings This determines whether the paginator builds links based on the number of events, the number of final results, or a settings map change. (While these are often the same, in searches with transforming commands these numbers are generally different.)
253

optional params

count This determines the number of items to be shown per page. defaults to: 10 maxPages This determines the maximum number of page links that the module will display on the page at a time. defaults to: 10

Results
AddTotals (extends DispatchingModule) This module contains a checkbox that toggles whether or not results are previewable.
required params

(none)
optional params

enable This determines whether the control should be checked initially. defaults to: false AxisScaleFormatter (extends BaseChartFormatter) This module contains a pulldown that allows you to choose whether you want the y-axis scale to be scaled logarithmically or linearly. When any other module has set the 'stacked' option, any log scaling becomes meaningless and so this module will both become invisible and revert to 'linear'.
required params

(none)
optional params

default the selected axis scale type defaults to: ""

254

BaseChartFormatter (extends Splunk.Module) this is an abstract base class for other chart formatting modules. This module should never itself be configured within a view.
required params

(none)
optional params

(none) ChartTitleFormatter (extends BaseChartFormatter) This module contains a text field that you can use to set the overall title of your chart.
required params

(none)
optional params

default Can be used to specify the default value for the module. label This is the string it displays. If not present, it defaults to 'Chart Title' (and it passes it through gettext for localization) ChartTypeFormatter (extends BaseChartFormatter) this module contains a pulldown that you can use to change between 'column', 'line', 'area' and various other chart types.
required params

(none)
optional params

default Specifies the chart type that should be initially selected defaults to: column
255

 ensureCompatibleType Ensures that the chart types are compatible with the search. defaults to: false Count (extends DispatchingModule) This module allows the user to determine the number of events that should be displayed at a time.
required params

options This is a list whose items have two required keys, 'text' and 'value'.
optional params

count DEPRECATED. use 'default' instead. If both default and count are specified, count will be ignored. default Indicates the starting count value to broadcast to modules that are listening. DataOverlay (extends DispatchingModule) This module allows the user to determine the data overlay mode for results
required params

(none)
optional params

dataOverlayMode DEPRECATED. use 'default'. If both dataOverlayMode and default are specified, dataOverlayMode will be ignored. defaults to: none default = none | heatmap | highlow Indicates the data overlay mode with values of heatmap, highlow and none. defaults to: none

256

EnablePreview (extends DispatchingModule) This module contains a checkbox that toggles whether or not results are previewable.
required params

(none)
optional params

display = true | false This is used to control whether or not the module is visible to the user. It was originally implemented to allow simple dashboards to have previewable results. defaults to: true enable This determines whether the control should be checked initially. defaults to: false EventsViewer (extends AbstractPagedModule) The EventsViewer module displays events resulting from the search that it's ancestor modules combined to specify. This module is very similar to SimpleEventsViewer, and one of these two modules will in the future be folded into the other.
required params

(none)
optional params

count This determines the number of events to display per page. Note this is almost always overridden by other modules that can set this from above. defaults to: 10 displayRowNumbers = True | False this determines if row numbers are displayed or not. defaults to: False enableBehavior = True | False This determines if mouseover, click, etc.. behavior is on or off. defaults to: True
257

 enableEventActions = True | False This determines if event actions are enabled or not. NOTE: Setting enableEventActions to False will hide all field actions. defaults to: True enableFieldActions = True | False This determines if field actions are enabled or not. NOTE: Setting enableFieldActions to False will hide all field actions. defaults to: True enableTermSelection = True | False This determines if term selection is enabled for time, raw and field name/value pairs. defaults to: True entityName = events | results_preview Indicates the job data feed to use defaults to: events fields This determines the fields that the module should be configured to show. It is commonly overridden by modules above like FieldPicker and HiddenFieldPicker. maxLines This determines the number of lines to display per event. Set to 0 to remove the explicit number of lines to display (use maxLinesConstraint instead). Other modules, such as the MaxLines module, override this property unless you set it explicitly in this module. defaults to: 10 maxLinesConstraint Browser crash control for the maximum lines displayed. defaults to: 500 offset This determines the offset to use when retrieving results for the paged module. defaults to: 0 reportFieldLink When this is present, a field dropdown link enabling a report action is presented. scrollerEnable = True | False When present, this module param enables the scroller. defaults to: False scrollerMaxHeight When scrollerEnable is True, this controls the scroller maximum pixel height constraint. defaults to: 10000
258

 scrollerMinHeight When scrollerEnable is True, this controls the scroller minumum pixel height constraint. defaults to: 0 segmentation = raw | inner | outer | full this determines the segmentation with which the events should be rendered. defaults to: outer Export (extends DispatchingModule) Displays a link that launches the job export utility.
required params

exportType
optional params

(none) FancyChartTypeFormatter (extends ChartTypeFormatter) this module contains a styled pulldown that you can use to change between 'column', 'line', 'area' and various other chart types.
required params

(none)
optional params

default The type of chart to render defaults to: column ensureCompatibleType Ensures that the chart types are compatible with the search. defaults to: false FieldViewer (extends AbstractPagedModule) This simple module shows the top N values for a given field, along with a number in parentheses showing the number of events that had the given value.
259

required params

field This is the name of the search-time or index-time field for which the module will display the top values.
optional params

count This is the number of most common values that the module should display. defaults to: 10 fields not used by this module (but technically it gets inherited from the abstract parent class). link If this option is present, the module will present a link to a view. On click will pass that view the ' | top <field>' search that would generate the corresponding chart. Values are a dictionary of keys: 'viewTarget', 'label' maxLines This determines the number of lines to display per event. Other modules, such as the MaxLines module, override this property unless you set it explicitly in this module. defaults to: 10 offset This determines the offset to use when retrieving results for the paged module. defaults to: 0 FlashChart (extends FlashWrapper) This module contains a Flash object that is capable of charting almost any search results that the Splunk backend can generate.
required params

(none)
optional params

drilldownPrefix Not required. Since this defaults to 'click', by default the keys will come down in the context as 'click.name', 'click.value',
260

'click.name2', 'click.value2'. In cases where you are nesting multiple drilldown patterns in the same view, this key is used so that the second set of keys does not collide with the first. For example if you have a nested config you might set the first to "userClick", and the second to "applicationClick". defaults to: click enableResize = True | False Control whether the flash movies display the vertical resize handle. defaults to: True height This specifies the height of the module. It can be a percentage or a number of pixels. defaults to: 210px maxResultCount This specifies the maximum number of results to render per series. For a single-series chart, this creates up to <maxResultCount> data points; for a multi-series chart with m series, this creates up to (m * <maxResultCount>) data points. In general, the practical limit should be set to the number of horizontal pixels available to the chart. For example, setting this to a value like 5000, when the available space for the chart on an average screen is around 500 pixels, will have an adverse performance effect on the UI with no visible difference in the chart. defaults to: 1000 maxRowsForTop This specifies how many rows of the data should be rendered for 'top' and 'rare' results. This value overrides maxResultCount when rendering results from the special-cased results. swfFile This is the path, relative to $SPLUNK_HOME/share/splunk/search_mrsparkle/exposed/flash, that specifies the swf to load. The swf must conform to a very strict and thus-far undocumented spec that is not for external consumption. defaults to: charting.swf width This specifies the width of the module. It can be a percentage or a number of pixels. Typically this is set to "100%" meaning it should fill all available space. It can also be set to a number of pixels by using a value like "500px". defaults to: 100%

261

FlashTimeline (extends DispatchingModule) This module contains a JavaScript object that is capable of displaying a chart of number of events over time. This chart will be updated asynchronously while the search is running.
required params

height This specifies the height of the module. It can be a percentage or a number of pixels. width This specifies the width of the module. It can be a percentage or a number of pixels. Typically this is set to "100%" meaning it should fill all available space. It can also be set to a number of pixels by using a value like "500px".
optional params

enableResize = True | False Control whether the module displays the vertical resize handle. defaults to: True maxBucketCount Specifies the maximum number of buckets to render. This is mostly a failsafe mechanism to prevent the browser from crashing if the server returns an excessive number of buckets. defaults to: 1000 minimized = True | False when set to True, the timeline will be in a collapsed or minimized state. The user is free to open it or minimize it at any point, and any change they make will be remembered when they return to the given view. defaults to: False renderer = auto | canvas | flash Specifies the renderer to use for the timeline. When set to auto, the module will use canvas if available, otherwise it will use flash. defaults to: auto statusBuckets This is the maximum number of time buckets that the backend is can persist while it runs the search. When present, it overrides the default of 300. Values lower than 300 will result in slightly faster search times, but displays less information to the user. defaults to: 300
262

 swfFile This is the path, relative to $SPLUNK_HOME/share/splunk/search_mrsparkle/exposed/flash, that specifies the swf to load. The swf must conform to a very strict and thus-far undocumented spec that is not for external consumption. defaults to: timeline.swf FlashWrapper (extends DispatchingModule) This is the base class for all Flash modules. Unlike FlashChart and FlashTimeline, this simple module makes no assumptions about the swf it is asked to load.
required params

height This specifies the height of the module. It can be a percentage or a number of pixels. swfFile This is the path, relative to $SPLUNK_HOME/share/splunk/search_mrsparkle/exposed/flash, that specifies the swf to load. width This specifies the width of the module. It can be a percentage or a number of pixels. Typically this is set to "100%" meaning it should fill all available space. It can also be set to a number of pixels by using a value like "500px".
optional params

enableResize = True | False Control whether the flash movies display the vertical resize handle. defaults to: True Gimp (extends Splunk.Module) Listens to all instructions and says nothing.
required params

(none)

263

optional params

(none) HiddenChartFormatter (extends Splunk.Module) this module contains a pulldown that you can use to change between 'column', 'line', 'area' and various other chart types.
required params

(none)
optional params

chart = area | bar | column | line | pie | scatter Use this to change the overall type of chart you wish to generate. chart.nullValueMode = connect | gaps | zero Use this to that control how 'line' and 'area' charts should behave when there are gaps in the data. You can either treat null values as '0', leave an explicit gap, or interpolate between the values. chart.stackMode = default | stacked | stacked100 Use this to make bar and area charts display in 'stacked' mode. chartTitle Use this to set the overall HTML title for the Flashchart module. charting.* This is a wildcard handler for dynamic charting properties; all must be prefixed by 'charting.' legend.placement = right | bottom | left | top | none Use this to change where the chart's legend is displayed relative to the chart itself primaryAxisTitle.text Use this to set the X-axis title. Note: in Bar chart this currently this sets the Y-axis title. secondaryAxis.scale = log | Use this to make the y-axis scale logarithmically or linearly. Values can be 'log' or (empty string). secondaryAxisTitle.text Use this to set the Y-axis title. Note: in Bar chart this currently this sets the X-axis title.

264

HiddenSoftWrap (extends DispatchingModule) This module is the SoftWrap module that has no HTML component, and thus it is hidden.
required params

(none)
optional params

enable This determines whether the control should be checked initially. defaults to: true JSChart (extends DispatchingModule) This module contains a Javascript-based object that is capable of charting almost any search results that the Splunk backend can generate.
required params

(none)
optional params

drilldownPrefix Not required. Since this defaults to 'click', by default the keys will come down in the context as 'click.name', 'click.value', 'click.name2', 'click.value2'. In cases where you are nesting multiple drilldown patterns in the same view, this key is used so that the second set of keys does not collide with the first. For example if you have a nested config you might set the first to "userClick", and the second to "applicationClick". Defaults to: click enableResize = True | False Control whether the chart displays the vertical resize handle. Defaults to: True height This specifies the height of the module. It can be a percentage or a number of pixels. Defaults to: 210px maxResultCount
265

 This specifies the maximum number of results to render per series. For a single-series chart, this creates up to <maxResultCount> data points; for a multi-series chart with m series, this creates up to (m * <maxResultCount>) data points. In general, the practical limit should be set to the number of horizontal pixels available to the chart. For example, setting this to a value like 5000, when the available space for the chart on an average screen is around 500 pixels, will have an adverse performance effect on the UI with no visible difference in the chart. Defaults to: 500 maxRowsForTop This specifies how many rows of the data should be rendered for 'top' and 'rare' results. This value overrides maxResultCount when rendering results from the special-cased results. Defaults to: 20 rows width This specifies the width of the module. It can be a percentage or a number of pixels. Typically this is set to "100%" meaning it should fill all available space. It can also be set to a number of pixels by using a value like "500px". Defaults to: 100% LegendFormatter (extends BaseChartFormatter) this module contains a pulldown that you can use to change how the chart legend is displayed relative to the chart itself.
required params

(none)
optional params

default Specifies the legend position that should be initially selected. defaults to: right LineMarkerFormatter (extends BaseChartFormatter)

266

required params

(none)
optional params

default Specifies the line marker behavior that should be initially selected. defaults to: false LinkList (extends DispatchingModule) DEPRECATED. This module is no longer supported, and should be replaced with one of the *Lister modules in the /lists subdirectory.
required params

labelField This is the name of the result field whose value should be displayed in the label part of the link list. Link lists are generally a combination of a descriptive label and a numeric count or other (value) field. valueField This is the name of the result field whose value should be displayed in the value part of the link list. This is often a count or numeric value relevant to the "label" portion of the link list.
optional params

initialSort The field in the result set to sort on when the link list is first rendered. initialSortDir = asc | desc The direction to sort the results based on the initialSort field. defaults to: asc labelFieldSearch This is the search string to generate when the user clicks on the label field. It requires labelFieldTarget to be defined to a valid view. The value of the label field is automatically added to the search. labelFieldTarget This is the view to target if the label field is setup to generate a clickable link that dispatches a search. valueFieldSearch

267

 This is the search string that is generated when the user clicks on the value field. It requires valueFieldTarget to be defined to a valid view. The value of the label field is automatically added to the search. valueFieldTarget This is the view to target if the value field is setup to generate a clickable link that dispatches a search. MaxLines (extends DispatchingModule) This module creates a control that allows the user to set the maximum number of lines to display per event.
required params

options This is a list whose items have two required keys, 'text' and 'value'
optional params

default Indicates the default setting for max lines per event. The value here must match one of the values in the options param. defaults to: 10 maxLines DEPRECATED. use 'default' instead. if both default and maxLines are specified, maxLines will be ignored. defaults to: 10 MultiFieldViewer (extends AbstractPagedModule) This module is typically for use within the sidebar, and shows a set of field names, with distinct counts next to them in parentheses. When the user clicks on the field names, a popup layer will open showing the top 10 values for that field. Clicking then on one of those values will add the proper field=value term and re run the search.
required params

(none)

268

optional params

count This determines the number of events to display per page. Note this is almost always overridden by other modules that can set this from above. defaults to: 10 field This field was a parameter on the parent class, but is not required for this class. fields This determines the fields that the module should be configured to show. It is commonly overridden by modules above like FieldPicker and HiddenFieldPicker. link If this option is present, a link will be presented. This is used for things like 'see top values over time' in the individual layers. maxDisplayLength Indicates the maximum number of characters of the field name to show in the main view. Excess characters will be stripped from the middle of the string. The tooltip on the field name will display the full field name value. defaults to: 25 maxLines This determines the number of lines to display per event. Other modules, such as the MaxLines module, override this property unless you set it explicitly in this module. defaults to: 10 offset This determines the offset to use when retrieving results for the paged module. defaults to: 0 NotReporting (extends Splunk.Module) Displayed when your search does not include a command to generate statistical results.
required params

(none)

269

optional params

(none) NullValueFormatter (extends BaseChartFormatter) This module contains a pulldown that controls how 'line' and 'area' charts should behave when there are gaps in the data. You can either treat null values as '0', leave an explicit gap, or interpolate between the values.
required params

(none)
optional params

default This specifies the null value behavior that should be initially selected. defaults to: gaps ResultsActionButtons (extends Splunk.Module) Implements a set of buttons with which the user can save, print, export and share the results of their search or report.
required params

(none)
optional params

editView When this is present, and when the module is displaying a saved search or saved report, it allows the module to present an 'edit' link that launches the given 'editing' view in a popup window. eventsView When this is present, and when the module has loaded a specific set of results, it allows the module to present a 'view events' link that will take the user to the specified view to run the portion of their search before the first transforming command.

270

ResultsHeader (extends SimpleResultsHeader) This module displays a header like '23,420 events' and is for placement generally above a FlashTimeline or above a set of modules implementing paging controls
required params

entityLabel This specifies what should appear after the displayed number. Typically this will be a value like 'events', or 'results', but for very narrowly defined views it could be 'pages edited'. entityName = events | results | scanned This specifies how the module should get the number that it displays.
optional params

entityLabelSingular This is the singular form of the 'entityLabel' parameter. It is displayed when there is 1 result row returned from the search. headerFormat This is used by SimpleResultsHeader but it is not used here where we have different containers and possibly different styles for the count, the 'label' and the time header. link This is a dictionary of config values specifying behaviour for a link that the module can display. This link sends the user to a different view where this search result is displayed instead. It contains a 'label' key that is the link text, and a 'viewTarget' key that is the search result view to which the user should be sent, and a 'popup' key that, when set to True, makes the link open the search result view in a new popup window. prefix When this option is present, the value of this key will be displayed before the number displayed. For example you can set it to 'Found', for the overall display to come out as 'Found 23,420 events' RowNumbers (extends DispatchingModule) This module allows the user to determine if row numbering is enabled/disabled

271

required params

(none)
optional params

default This determines whether the control should be checked initially. defaults to: true displayRowNumbers DEPRECATED. use 'default' instead. if both default and displayRowNumbers are specified, displayRowNumbers will be ignored. defaults to: true SavedSearches (extends Splunk.Module) this module has a custom python implementation that it uses to display the list of saved searches for the current user.
required params

(none)
optional params

(none) SearchTextSetting (extends TextSetting) A search text input field that passes its contents down to its children as part of the settings map, styled to have a mag glass icon.
required params

elementName The name of the input element to be added to the UI. settingName This is the name of the setting to be added to a settings map and passed to a module's children.

272

optional params

label An html label element that can be set for the given input text element. Segmentation (extends DispatchingModule) This module allows the user to determine the segmentation type to be displayed for events.
required params

options This is a list whose items have two required keys, 'text' and 'value'. 'value can be one of raw,inner,outer,full.
optional params

default Indicates the segmentation value to broadcast to modules that are listening. defaults to: full segmentation DEPRECATED. Use default instead. If both default and segmentation are specified, segmentation will be ignored. defaults to: full Selector (extends Splunk.Module) Creates a selction list from a set of options. Options can either be configured manually or by defining an entity endpoint from which to generate its options.
required params

name The name of the html select element generated.

optional params

label The test to appear to the left of the selector form element. listEndpoint
273

 This is required if mode=list. Relatively defined list endpoint to communicate with in order to generate the options list. For example if you want a list of all the local applications set listEndpoint to "entities/apps/local". mode = static | list This is the mode in which the Select should work. "static" implies that it will only use the list of options provided to it to render this list. "list" designates the use of a listing endpoint to generate the option elements. defaults to: static options This is the list of options that Splunk displays in the dropdown selector. When in 'list' mode, Splunk displays the options defined here first and then displays options received from the listEndpoint beneath them. Each option includes a text key which is the text of the option, a value key which is the value of the option and an optional selected key which, when set to True sets the current option to selected. Selected should NOT be set manually when mode=list unless no selected option has been defined for the list. selected If the selected value is present in the option results, this sets that option to selected. This is optional in list mode. Note, setting selected manually in the options param may conflict with this setting. text This is the name of the field in the list endpoint's results that should be used to generate the text of the option elements. It is required in list mode. For example, if the list returns a field called name, setting text = name means that the name field will be used to generate the visible text of the option. value The name of the field from the list endpoint's results that should be used to set the value of an option element. It is required in list mode. ShowSource (extends DispatchingModule) This module waits for the search to complete and then renders a single field from the first row of the results

274

required params

(none)
optional params

maxLinesConstraint Browser crash control for the maximum lines displayed. defaults to: 500 SimpleResultsHeader (extends DispatchingModule) This module displays a header like '23,420 events' and is for placement generally above a FlashTimeline or above a set of modules implementing paging controls
required params

entityName = events | results | scanned This specifies how the module should get the number that it displays. headerFormat This specifies how the module should get the number that it displays.
optional params

(none) SimpleResultsTable (extends AbstractPagedModule) this module waits for the search to complete, and then renders its final results in a tabular format.
required params

(none)
optional params

allowTransformedFieldSelect This indicates whether or not Splunk should observe any field list setting while it renders transformed results. It is generally only used in fixed configuration situations like dashboards. It defaults to false,
275

which results in all fields in a transforming search being displayed. defaults to: false count This determines the number of events to display per page. Note this is almost always overridden by other modules that can set this from above. defaults to: 10 dataOverlayMode This indicates the default data overlay mode with values of heatmap, highlow and none. defaults to: none displayMenu This controls whether table cells have a dropdown menu with search suggestions when clicked on. defaults to: False displayRowNumbers If this is set to true then row numbers are displayed alongside each row in the table. defaults to: on drilldown = all | row | none This indicates whether the module allows the user to select a particular cell. The behaviour is abstract though, and the specifics are determined by the child modules in the view. defaults to: none drilldownPrefix Not required. Since this defaults to 'click', by default the keys will come down in the context as 'click.name', 'click.value', 'click.name2', 'click.value2'. In cases where you are nesting multiple drilldown patterns in the same view, this key is used so that the second set of keys does not collide with the first. For example if you have a nested config you might set the first to "userClick", and the second to "applicationClick". defaults to: click entityName = events | results | auto This determines whether the viewer should build table row/columns based on events, results or auto detect. defaults to: auto fieldFormats Override presentation options for specific fields. This is currently used to specify display options for sparklines. defaults to: none fields

276

 This determines the fields that the module should be configured to show. It is commonly overridden by modules above like FieldPicker and HiddenFieldPicker. maxLines This determines the number of lines to display per event. Other modules, such as the MaxLines module, override this property unless you set it explicitly in this module. defaults to: 10 offset This determines the offset to use when retrieving results for the paged module. defaults to: 0 SingleValue (extends DispatchingModule) This module waits for the search to complete and then renders a single field from the first row of the results
required params

(none)
optional params

additionalClass An optional additional css class name to add to the result container afterLabel Label to display after the result beforeLabel Label to display before the result classField Adds the value of the classField of the first result as an additional css class to the result container. Pre-defined classes include 'severe', 'elevated', 'low', and 'None' (default). field Field to display - Defaults to first field returned format = number | decimal | percent | unixtime | none Specifies the data formatting method to apply to the value. Locale aware. Defaults to none. linkFields Specify whether to just link the result, or include labels. To link the result and both labels, specify "result,beforeLabel,afterLabel" defaults to: result
277

 linkSearch Specify a valid complete search query to turn the result into a clickable link linkView Specify which view to execute the linked search against defaults to: dashboard SoftWrap (extends DispatchingModule) This module contains a checkbox that toggles whether or not events are soft-wrapped. When off, event text will break in the page only where there is a linebreak in the actual data, and scrollbars will appear as necessary. When on, the event text will also break at the edge of the window.
required params

(none)
optional params

enable This determines whether the control should be checked initially. defaults to: true Sorter (extends Splunk.Module) Sorter displays a list of fields that can be sorted upon. Given a list of field names, Sorter will create a set of delimited links which the user can click on. Clicking on these links will pass a "sort" setting down to Sorter's child modules which can iterpret how to preform the sort on their own.
required params

(none)
optional params

delimiter The delimiter used to seperate each displayed field label. defaults to: | fields This is a list of comma delimited field labels which are displayed. If the optional param field_values isn't provided, clicking a field label passes the field label as the field value. Order is preserved in the
278

field label list display. sortDir = asc | desc This provides the direction to push a sort when a Sorter module is initiated. defaults to: asc sortKey If this is provided, it initiates the Sorter with the defined label. When undefined, this defaults internally to the first field name defined in the view config. SplitModeFormatter (extends BaseChartFormatter) This module contains a pulldown that indicates whether or not to show multi-series data on a single combined plot vs. a separate plot for every series. For example, a search like "search error | timechart count by host" would render a separate chart for every "host" found.
required params

(none)
optional params

default = true | false Specifies if the chart is to be split on series defaults to: false StackModeFormatter (extends BaseChartFormatter) This module contains a pulldown that can be used to make bar and area charts display in 'stacked' mode. When the chart type is set to a value other than 'area' or 'column', this module becomes invisible and turns off the stacked mode if it was on.
required params

(none)
optional params

default This specifies the default stack mode defaults to: default

279

SuggestedFieldViewer (extends MultiFieldViewer) This module shows fields that are not selected by FieldPicker (and thus not displayed in MultiFieldViewer or other modules) but which look like they might be interesting to the user.
required params

(none)
optional params

count This determines the number of events to display per page. Note this is almost always overridden by other modules that can set this from above. defaults to: 10 exclude field This field was a parameter on the parent class, but is not required for this class. fields This determines the fields that the module should be configured to show. It is commonly overridden by modules above like FieldPicker and HiddenFieldPicker. link If this option is present, a link will be presented. This is used for things like 'see top values over time' in the individual layers. maxDisplayLength Indicates the maximum number of characters of the field name to show in the main view. Excess characters will be stripped from the middle of the string. The tooltip on the field name will display the full field name value. defaults to: 25 maxFields defaults to: 20 maxLines This determines the number of lines to display per event. Other modules, such as the MaxLines module, override this property unless you set it explicitly in this module. defaults to: 10 minDistinctCount defaults to: 1
280

 minFrequency defaults to: 0.2 offset This determines the offset to use when retrieving results for the paged module. defaults to: 0 TextSetting (extends AbstractFormSettingModule) A text input field that passes its contents down to its children as part of the settings map.
required params

elementName This is the name of the input element to be added to the UI. settingName This is the name of the setting to be added to a settings map and passed to a module's children.
optional params

label An html label element that can be set for the given input text element. ViewstateAdapter (extends Splunk.Module) Injects settingsMap settings contained within a viewstate set into the current module branch
required params

(none)
optional params

savedSearch suppressionList viewstateId

281

XAxisTitleFormatter (extends BaseChartFormatter) this module contains a text field that you can use to change the title for the x-axis of your chart.
required params

(none)
optional params

default Can be used to specify the default value for the module. YAxisRangeMaximumFormatter (extends BaseChartFormatter) this module contains a text field that takes an integer, that determines the maximum y-axis value that should be displayed.
required params

(none)
optional params

default Specifies the default for the module defaults to: "" YAxisRangeMinimumFormatter (extends BaseChartFormatter) This module contains a text field that takes an integer, that determines the minimum y-axis value that should be displayed.
required params

(none)
optional params

default This specifies the module default. defaults to: ""

282

YAxisTitleFormatter (extends BaseChartFormatter) this module contains a text field that you can use to change the title for the y-axis of your chart.
required params

(none)
optional params

default Can be used to specify the default value for the module.

Search
DisableRequiredFieldsButton (extends Splunk.Module) EXPERIMENTAL
required params

(none)
optional params

enabled The intention to add to the Search, for downstream modules. defaults to: True ExtendedFieldSearch (extends FieldSearch) The basis for the form elements that add or remove intentions.
required params

field Use this to specify a field (such as a sourcetype, clientip, or any other valid field) to scope results.

283

optional params

default This is the default value that will appear in the text field. intention The intention to add to the Search, for downstream mdoules. label This sets alternate text to display next to the input field. If it is omitted, the text defaults to the field parameter q DEPRECATED. use the 'default' param instead. If both q and default are specified, the q value will be ignored. replacementMap This is a map to the shortest path to values in an intention that should be replaced with the user added value. FieldPicker (extends HiddenFieldPicker) This module launches the field picker, a list of all available fields from which a user can select the fields to display. Descendants of this module that display events and summary information will pick up the field list specified or chosen here.
required params

fields This provides a space-separated list of fields that are selected by default when the page loads.
optional params

link This enables the display of links such as 'see top values over time' in the individual layers. sidebarDisplay = True | False Indicates if the sidebar is open or closed provided it is available in the layout. defaults to: True strictMode "This indicates whether the list provided in the 'fields' param should be interpreted literally. When set to true, no additional fields are passed along. When set to false, standard fields like _time and _raw are automatically appended to the outgoing 'fields' setting.
284

 defaults to: false FieldSearch (extends Splunk.Module) Restrict searches to a specific field. Use this module to configure a form search with only one form field. To configure form searches with multiple forms, use ExtendedFieldSearch.
required params

field Use this to specify a field (such as a sourcetype, clientip, or any other valid field) to scope results.
optional params

default Specify a default value to display when the page loads. label This sets alternate text to display next to the input field. If it is omitted, the text defaults to the field parameter. q DEPRECATED. use the 'default' param instead. If both q and default are specified, the q value will be ignored. HiddenFieldPicker (extends DispatchingModule) This module implements an invisible control that hardwires which fields the user will see and what order those fields are in. When they are descendants of this module, other modules that display events and summary information will pick up the field list specified or chosen here.
required params

(none)
optional params

fields This is a space-separated list of the fields that are displayed with events by default when the page loads. strictMode "This indicates whether the list provided in the 'fields' param should be interpreted literally. When set to true, no additional fields are
285

passed along. When set to false, standard fields like _time and _raw are automatically appended to the outgoing 'fields' setting. defaults to: false HiddenIntention (extends Splunk.Module) Adds the given intention to any search it receives from upstream modules. There are several kinds of intentions, 'addterm', 'negateterm', 'stringreplace', and 'plot' are the main ones. A complete reference is beyond the scope of this description but one will hopefully be added to the documentation soon.
required params

intention This layers an intention on top of the base search. If no module upstream has specified a base search, the intention will layer on top of 'search *'.
optional params

(none) HiddenPostProcess (extends DispatchingModule) Adds a post-process search into the data tree.
required params

search Set a post processing query.

optional params

(none) HiddenSavedSearch (extends Splunk.Module) Given a saved search name, either finds the last run search for that saved search or runs a new search depending on its configuration.

286

required params

savedSearch This is the name of the saved search to use when looking up a searches from the saved search's history or when dispatching a new search.
optional params

useHistory = Auto | None | True | False useHistory defines the savedSearch module's saved search dispatch method. The default useHistory method is None, which means that savedSearch first tries to find a previously run job if one exists in the saved search's history. If it can't find a previously run job, savedSearch dispatches a new job based on the saved search and returns that job's sid. If useHistory is set to True, savedSearch looks only for previously run jobs dispatched by the saved search. If useHistory is set to False, savedSearch dispatches a new job based on the saved search and returns that job's sid, regardless of the presence of jobs within the saved search's history. defaults to: Auto HiddenSearch (extends Splunk.Module) Runs a search behind the scenes. Passes results on to any children. You must set autoRun to true so that the search actually runs.
required params

(none)
optional params

earliest This is used to define a beginning time range. It is expected if 'latest' is also defined. It sets the start point of the time range to search within. latest This is used to define an ending time range. It is expected if 'earliest' is also defined. It sets the ending point of the time range to search within. maxCount Use this when you have a search that never reports more than 10,000 events or results, and you want it to report a higher number.
287

Specifically, this overrides the default value which is specified per generating search command in limits.conf. NOTE: when you're using the 'search' command as your generating command, and the search is being dispatched with status_buckets>=1, the resultCount/eventCount numbers were never bounded to begin with, and this setting will be equally ignored by the API. maxEvents This will set the auto_finalize_ec property in the Splunkd Search API when the search is dispatched. See REST API reference on splunk.com for more details. search The literal search string HiddenSearch passes onto its child modules. PostProcessBar (extends FieldSearch) This module lets you add a post-process search on any results you have returned. It doesnt re-run any search, but it will use that search language to do post-processing filtering on the results data.
required params

(none)
optional params

default Set a default post processing query to appear in the search bar. field Overwrites default settings for field in the abstract class. label This sets alternate text to display next to the input field. If it is omitted, the text defaults to the field parameter. q Deprecated. Use the 'default' param instead. If both 'default' and 'q' are specified, 'q' will be ignored. PostProcessFilter (extends FieldSearch) This module lets you add a post-process search on any results you have returned. It doesnt re-run any search, but it will use that search language to do post-processing filtering on the results data.

288

required params

(none)
optional params

beforeLabel Label to display before the searchfilter defaults to: Filter: default Set a default post processing query to appear in the search filter. field Overwrites default settings for field in the abstract class. friendlySearch = True | False If 'True' and the post-process search string does not start with "search" or "|", prefix the search with "search " defaults to: True label This sets alternate text to display next to the input field. If it is omitted, the text defaults to the field parameter. prefixSearch String to prefix the post search with. For example "eval _raw=source" to allow user to search source rather than _raw. q DEPRECATED. use the 'default' param instead. If both q and default are specified, the q value will be ignored. RadioButtonSearch (extends FieldSearch) This module creates a set of radio buttons with submit and cancel buttons.
required params

label This appears next to the radio buttons, as the overall label for the whole control. options This is a list of two items: text and value. "Text" is the text to display next to the radio button. "Value" is the value that is selected upon clicking the radio button. You can optionally add selected to specify which button should be checked upon page load.

289

optional params

default NOT supported. In the 'options' param, if you given an item a 'selected' param with True as the value it will be selected on page load. field When present, this module adds key value searchTerms in the form <field>=<radioButtonValue> to the search. When absent, the module adds just <radioButtonValue> to the search. q NOT supported SearchBar (extends FieldSearch) This module creates a search bar with submit and cancel buttons.
required params

(none)
optional params

assistantDelay Number of milliseconds to wait after a user keystroke to update the assistant defaults to: 200 autoOpenAssistant = true | false Indicates if the search assistant will open automatically when typing in the search bar defaults to: true default Specify a default search to display upon page load. field Overwrites default settings for field in the abstract class. label This sets alternate text to display next to the input field. If it is omitted, the text defaults to the field parameter. q DEPRECATED. use the 'default' param instead. If both q and default are specified, the q value will be ignored. showCommandHelp = true | false
290

 Indicates if search command help is shown showCommandHistory = true | false Indicates if search command history is shown showFieldInfo = true | false Indicates if interesting field information should be calculated and shown useAssistant = true | false Indicates if the search assistant is active useAutoFocus Will autofocus the input box so you can type your search keywords without having to position the cursor in the search box. defaults to: False useOwnSubmitButton = True | False defaults to: True useTypeahead = true | false Indicates if typeahead content is rendered inside the search assistant SubmitButton (extends Splunk.Module) Creates a submit button that collects changes from its parent modules, and runs them when the user clicks the button.
required params

(none)
optional params

allowSoftSubmit = True | False When this is present and set to 'True', any upstream modules can effectively submit the search by calling pushContextToChildren. When this is present and set to 'False' (or omitted) the user has to click the SubmitButton to submit the search. defaults to: False label This is the button label. If the button label is blank, you'll get a small green button in the normal search view. Note that its design may change slightly in different layoutPanels and different views. updatePermalink = True | False When this is present and set to 'True', any search context will be persisted to the URL and the back button will work. defaults to: False
291

TimeRangePicker (extends Splunk.Module) This module creates a drop-down menu that users can use to change the timerange. Timerange values and labels are pulled from the configuration in times.conf.
required params

(none)
optional params

default When this is set to one of the time range labels in times.conf, the system sets that time range option when the page loads. label Optional label to display above time range picker searchWhenChanged = True | False Launch search whenever the time range is changed. defaults to: True selected DEPRECATED. use 'default' instead. When both default and selected are specified, selected will be ignored. ViewRedirector (extends Splunk.Module) This module takes the context and settings information provided by its ancestors, dispatches the search and redirects the user to see that search in the specified view. When ViewRedirector receives a new context, and onContextChange() is called, it WILL REDIRECT to the specified view.
required params

viewTarget Set the view that the module should redirect the user's search to.
optional params

dispatchBeforeRedirect = True | False This sets whether to dispatch a search before redirecting. When set to True, the system redirects to a 'sid' url. When set to False the system redirects to a 'q' url and the other view then dispatches the search. defaults to: False
292

 popup Set as a boolean to determine whether to launch the view in a popup window, or use the same window. If set to a value besides True/False, we assume True and we pass the literal value as the optional arguments to window.open(). defaults to: False sendBaseSID = True | False Toggle whether to send a base search ID. defaults to: False uriParam.* Wildcard parameter setting to allow additional URI GET parameters to be specified on redirect. As of this writing short of custom wiring you might be doing in application.js, 'earliest', 'latest' and 'auto_pause' are the only arguments that will have any effect. defaults to: False ViewRedirectorLink (extends ViewRedirector) This module puts a link in the view with the given label. When clicked it will take the context information provided by its ancestors, dispatch the search and redirects the user to see that search in the specified view.
required params

viewTarget Set the view that the module should redirect the user's search to.
optional params

dispatchBeforeRedirect = True | False This sets whether to dispatch a search before redirecting. When set to True, the system redirects to a 'sid' url. When set to False the system redirects to a 'q' url and the other view then dispatches the search. defaults to: False label In link and button modes, this is the label of the link or button. If it is omitted, the link or button label says 'View results.' popup Set as a boolean to determine whether to launch the view in a popup window, or use the same window. If set to a value besides True/False, we assume True and we pass the literal value as the
293

optional arguments to window.open(). defaults to: False sendBaseSID = True | False Toggle whether to send a base search ID. defaults to: False uriParam.* Wildcard parameter setting to allow additional URI GET parameters to be specified on redirect. As of this writing short of custom wiring you might be doing in application.js, 'earliest', 'latest' and 'auto_pause' are the only arguments that will have any effect. defaults to: False

Static
GenericHeader (extends Splunk.Module) This simple module just displays the configured text as a header element on the page.
required params

label this is the text of the header

optional params

(none) NullModule (extends Splunk.Module) This is just a null module, used when we need a placeholder. Takes up no space and tries to remain inconspicuous.
required params

(none)
optional params

(none)

294

Switchers
ButtonSwitcher (extends TabSwitcher) This is a subclass of AbstractSwitcher, and when configured to have N children (and thus N subtrees of descendant modules), it will display the a button for each child. The button style is determined by a class set on the group name. When the user clicks a different button, the corresponding child and its descendant modules will be shown on screen and all other child modules (and descendants thereof) will be hidden.
required params

mode = independent | serializeAll The mode can be one of two values: 'independent', and 'serializeAll'. Independent is the most common setting. In independent mode, the module's N subtrees are all distinct and independent child branches. SerializeAll mode lets you switch between different aspects of a single shared search or report. In this mode, the last child is not represented in the switcher's options and the last child tree is always visible.
optional params

disableOnNull = True | False When this is present, the module is disabled until it is given an explicit search, or when its search is cancelled. defaults to: False hideChildrenOnLoad = True | False Indicates if child modules are hidden via CSS by default defaults to: False selected This specifies the group of the child that is selected when the page loads. (Group name is the group = name attribute set on the parent module.) When absent, the first child module and its ancestor tree are shown initially. ConditionalSwitcher (extends TabSwitcher) This is a subclass of AbstractSwitcher. When the given condition is true, it will display the first child tree. When false it will display the second child tree.

295

required params

condition this is the expression (written in Javascript, executed by the module), that will determine which child is present. mode = independent | serializeAll The mode can be one of two values: 'independent', and 'serializeAll'. Independent is the most common setting. In independent mode, the module's N subtrees are all distinct and independent child branches. SerializeAll mode lets you switch between different aspects of a single shared search or report. In this mode, the last child is not represented in the switcher's options and the last child tree is always visible.
optional params

disableOnNull = True | False When this is present, the module is disabled until it is given an explicit search, or when its search is cancelled. defaults to: False hideChildrenOnLoad = True | False Indicates if child modules are hidden via CSS by default defaults to: False requiresDispatch = False | True if True, the module framework will force a search to be kicked off at that point in the view hierarchy, (unless the search has already been dispatched by an upstream module). This determination is normally made automatically but with ConditionSwitchers you often want to make the conditional determination based on a running job. defaults to: False selected This specifies the group of the child that is selected when the page loads. (Group name is the group = name attribute set on the parent module.) When absent, the first child module and its ancestor tree are shown initially. LinkSwitcher (extends TabSwitcher) This is a subclass of AbstractSwitcher, and when configured to have N children (and thus N subtrees of descendant modules), it will display the a link for each child. When the user clicks a different link, the corresponding child and its descendant modules will be shown on screen and all other child modules (and descendants thereof) will be hidden.
296

required params

label This specifies the text that should appear to the left of the links. mode = independent | serializeAll The mode can be one of two values: 'independent', and 'serializeAll'. Independent is the most common setting. In independent mode, the module's N subtrees are all distinct and independent child branches. SerializeAll mode lets you switch between different aspects of a single shared search or report. In this mode, the last child is not represented in the switcher's options and the last child tree is always visible.
optional params

disableOnNull = True | False When this is present, the module is disabled until it is given an explicit search, or when its search is cancelled. defaults to: False hideChildrenOnLoad = True | False Indicates if child modules are hidden via CSS by default defaults to: False selected This specifies the group of the child that is selected when the page loads. (Group name is the group = name attribute set on the parent module.) When absent, the first child module and its ancestor tree are shown initially. PulldownSwitcher (extends AbstractSwitcher) Creates a pull-down menu populated with results from its children. Shows one set of child modules at a time. Children can be serialized -- they pass results on -- or independent.
required params

label This specifies the text that should appear to the left of the pulldown. mode = independent | serializeAll The mode can be one of two values: 'independent', and 'serializeAll'. Independent is the most common setting. In independent mode, the module's N subtrees are all distinct and independent child branches. SerializeAll mode lets you switch
297

between different aspects of a single shared search or report. In this mode, the last child is not represented in the switcher's options and the last child tree is always visible.
optional params

disableOnNull = True | False When this is present, the module is disabled until it is given an explicit search, or when its search is cancelled. defaults to: False hideChildrenOnLoad = True | False Indicates if child modules are hidden via CSS by default defaults to: False selected This specifies the group of the child that is selected when the page loads. (Group name is the group = name attribute set on the parent module.) When absent, the first child module and its ancestor tree are shown initially. ShowHideHeader (extends AbstractSwitcher) This is a somewhat restrictive switcher class, in that it should only ever have two children, and the second child tree should be either a null module, or in theory some short text like '(click the link above to show formatting options)'
required params

label Specify the text that should appear in the header. mode = independent | serializeAll The mode can be one of two values: 'independent', and 'serializeAll'. Independent is the most common setting. In independent mode, the module's N subtrees are all distinct and independent child branches. SerializeAll mode lets you switch between different aspects of a single shared search or report. In this mode, the last child is not represented in the switcher's options and the last child tree is always visible.
optional params

disableOnNull = True | False When this is present, the module is disabled until it is given an
298

explicit search, or when its search is cancelled. defaults to: False headerType = primary | secondary This sets whether or not the header should be the large or the smaller version. Currently only the two existing styles are possible. defaults to: primary hideChildrenOnLoad = True | False defaults to: False selected This specifies the group of the child that is selected when the page loads. (Group name is the group = name attribute set on the parent module.) When absent, the first child module and its ancestor tree are shown initially. TabSwitcher (extends AbstractSwitcher) This is a subclass of AbstractSwitcher, and when configured to have N children (and thus N subtrees of descendant modules), it will display the 'group' params of those modules in a set of tabs. Like PulldownSwitcher, this module shows only one child at a time. Displays the results of its child modules in a set of tabs. When the user clicks a different tab, the corresponding child and its descendant modules are shown on screen and all other child modules (and descendants thereof) are hidden.
required params

mode = independent | serializeAll The mode can be one of two values: 'independent', and 'serializeAll'. Independent is the most common setting. In independent mode, the module's N subtrees are all distinct and independent child branches. SerializeAll mode lets you switch between different aspects of a single shared search or report. In this mode, the last child is not represented in the switcher's options and the last child tree is always visible.
optional params

disableOnNull = True | False When this is present, the module is disabled until it is given an explicit search, or when its search is cancelled. defaults to: False hideChildrenOnLoad = True | False Indicates if child modules are hidden via CSS by default
299

 defaults to: False selected This specifies the group of the child that is selected when the page loads. (Group name is the group = name attribute set on the parent module.) When absent, the first child module and its ancestor tree are shown initially.

setup.xml
The following is the spec file for setup.xml.

setup.xml.spec
This file describes the setup XML config and provides some examples. setup.xml provides a Setup Screen that you provide to users to specify configurations for an app. The Setup Screen is available when the user first runs the app or from the Splunk Manager: Splunk > Manager > Apps > Actions > Set up Place setup.xml in the app's default directory: $SPLUNK_HOME/etc/apps/<app>/default/setup.xml The basic unit of work is an <input>, which is targeted to a triplet (endpoint, entity, field) and other information used to model the data. For example data type, validation information, name/label, etc. The (endpoint, entity, field attributes) identifies an object where the input is read/written to, for example: endpoint=saved/searches entity=MySavedSearch field=cron_schedule The endpoint/entities addressing is relative to the app being configured. Endpoint/entity can be inherited from the outer blocks (see below how blocks work). Inputs are grouped together within a <block> element: (1) blocks provide an iteration concept when the referenced REST entity is a regex

300

(2) blocks allow you to group similar configuration items (3) blocks can contain <text> elements to provide descriptive text to the user. (4) blocks can be used to create a new entry rather than edit an already existing one, set the entity name to "_new". NOTE: make sure to add the required field 'name' as an input. (5) blocks cannot be nested See examples below.

Block Node attributes: endpoint - The REST endpoint relative to "https://hostname:port/servicesNS/nobody/<app-name>/" of entities/object the block/input addresses. Generally, an endpoint maps to a Splunk configuration file. entity - An object at the endpoint. Generally, this maps to a stanza name in a configuration file. NOTE: entity names should be URI encoded. mode - (bulk | iter) used if the entity attribute is a regular expression: o iter - (default value for mode) Iterate over all matching entities and provide a separate input field for each. o bulk - Update all matching entities with the same value. NOTE: splunk interprets '*' as the regex '.*' eai_search - a search to filter entities returned by an endpoint. If not specified the following search is used: eai:acl.app="" OR eai:acl.app="<current-app>" This search matches only objects defined in the app which the setup page is being used for. NOTE: if objects from another app are allowed to be configured, any changes to those objects will be stored in the current app. enabled - (true | false | in-windows | in-unix | in-linux) whether this block is enabled or not

301

o o o installations o installations

true false in-windows

- (default) this block is enabled - block disabled - block is enabled only in windows

in-linux/unix - block is enabled in non-windows

Input Node Attributes: endpoint entity field - see description above (inherited from block) - see description above (inherited from block) - <string> the field which is being configured

old_style_disable - <bool> whether to perform entity disabling by submiting the edited entity with the following field set: disabled=1. (This is only relevant for inputs whose field=disabled|enabled). Defaults to false. Nodes within an <input> element can display the name of the entity and field values within the entity on the setup screen. Specify $name$ to display the name of the entity. Use $<field_name>$ to specify the value of a specified field. <setup> <block title="Basic stuff" endpoint="saved/searches/" entity="foobar"> <text> some description here </text> <input field="is_scheduled"> <label>Enable Schedule for $name$</label> <type>bool</type> </input> <input field="cron_scheduled"> <label>Cron Schedule</label> <type>text</type> </input> <input field="actions"> <label>Select Active Actions</label> <type>list</type> </input>

<input entity="*" field="is_scheduled" mode="bulk"> <label>Enable Schedule For All</label> <type>bool</type> </input> </block>

302

<block title="Configure search" endpoint="saved/eventypes/" entity="*" mode="iter"> <input field="search"> <label>$name$ search</label> <type>string</type> </input> <input field="disabled"> <label>disable $name$</label> <type>bool</type> </input> </block> <block title="Create a new eventtype" endpoint="saved/eventtypes/" entity="_new"> <input target="name"> <label>Name</label> <type>text</type> </input> <input target="search"> <label>Search</label> <type>text</type> </input> </block> <block title="Add Account Info" endpoint="admin/passwords" entity="_new"> <input field="name"> <label>Username</label> <type>text</type> </input> <input field="password"> <label>Password</label> <type>password</type> </input> </block>

<block title="Collect local event logs" endpoint="admin/win-eventlogs/" eai_search="" > <text> Splunk for Windows needs at least your local event logs to demonstrate how to search them. You can always add more event logs after the initial setup in Splunk Manager. </text> <input entity="System" field="enabled" old_style_disable="true"> <label>Enable $name$</label> <type>bool</type> </input>

303

<input entity="Security" field="enabled" old_style_disable="true"> <label>Enable $name$</label> <type>bool</type> </input> <input entity="Application" field="enabled" old_style_disable="true"> <label>Enable $name$</label> <type>bool</type> </input> </block> <block title="Monitor Windows update logs" endpoint="data/inputs/monitor"> <text> If you monitor the Windows update flat-file log, Splunk for Windows can show your patch history. You can also monitor other logs if you have them, such as IIS or DHCP logs, from Data Inputs in Splunk Manager </text> <input entity="%24WINDIR%5CWindowsUpdate.log" field="enabled"> <label>Enable $name$</label> <type>bool</type> </input> </block> </setup>

304

Custom charting configuration reference

Overview of the custom chart configuration reference
We've designed the default look and feel of Splunk charts to combine simplicity of design with strong usability. We want you to be able to easily generate your charts, incorporate them into dashboards, and share them with interested parties without needing to spend time "tinkering under the hood" to make things look just right. But we also understand that the default chart design options in the Panel Editor won't fit everyone's needs all of the time. This is why we've also made it possible for you to customize just about every aspect of the charting UI, from the choice of chart colors, fonts, and line thicknesses to the formatting of legends and axis labels and controlling the way chart elements are laid out in the dashboard panel. All you have to do is adjust the properties for the charting elements in the underlying panel XML. The topics in this reference chapter provide details on the various Splunk charting elements and properties that you can use to customize just about every aspect of your dashboard charts. Use this reference to customize charts whether they are built using the simplified or advanced dashboard XML. (For more information about the two kinds of XML, see "About Advanced XML" in this manual.)

Chart customization introduction and tutorial

While the topics in this reference chapter provide numerous small examples of how chart customization can be managed in simple dashboard XML with the Splunk charting controls, elsewhere in this manual you can find a comprehensive introduction to advanced chart customization. It includes: longer and more detailed chart customization examples, with some additional background on how they work. coverage of the slight syntax differences for chart customization in simple and advanced view XML. information about Splunk's two charting modules, JSChart and FlashChart. Splunk uses JSChart, a JavaScript-based charting library, to support graphics displays on iOS mobile devices. Charts in dashboards
305

that use simple XML are displayed with JSChart by default. If your dashboard uses advanced XML, you need to manually specify which charting module each chart uses (JSChart or FlashChart). Note: Certain chart customization properties are not supported by JSChart. If you use one of these unsupported chart customization properties with a chart in a dashboard that uses simpleXML, Splunk will use FlashChart to render the chart, which means that the chart will not display correctly in devices that do not support Flash. If you do the same thing with a chart that uses the JSChart module in an advanced XML dashboard, Splunk ignores the unsupported property setting. For more information, see "Advanced charting options". To learn more about adding charts to your dashboard see the "Add a chart" topic in this manual.

What you'll find in this reference

The topics in this reference provide tables for the Splunk charting elements that you can customize. The tables contain definitions of the properties available for those elements. They also tell you which properties are supported by JSChart, the JavaScript-based charting module mentioned above. There are also tables for elements whose properties are either referred to by other elements (for example, a chart element might refer to a particular brush palette element, which in turn refers to a set of brush elements) or inherited by certain elements (for example, all chart elements inherit properties from the layoutSprite element, which in turn inherits a base set of properties from the sprite element). This reference provides details on the following Splunk charting elements: Charts - The chart element controls properties specific to individual chart types. For example, when chart has a value of line, you can specify properties for a line chart, such as lineStyle or stackMode. Legends - You use the legend element to control aspects of the visual appearance of chart legends, including legend placement, label text, and text formatting. Axes - The axis element controls how data is mapped to the chart grid (but not how it appears--for that see the axisLabels element). It is set up to handle three types of chart axes: category axes (which map categorical values), numeric axes (which plot data along a numeric range), and time
306

axes (which plot data along a range of time). Axis labels - The axisLabels element controls the visualization of chart axes. It places tick marks and labels at locations along chart axes that are appropriate depending upon the state of those axes. Axis titles - The axisTitle element is mainly used for Cartesian (dual axis) charts such as bar, column, area, and line charts. It enables placement of the x- and y-axis titles within the chart layout. Grid lines - The gridLines element is used to control the display and appearance of chart grid lines in cartesian (dual axis) chart types, such as bar, column, area, and line charts. Grid lines correspond to axis tick marks from axis labels and extend across the span of the chart. Tool tips - Tool tips are the visual elements that appear on chart mouseover, displaying information that corresponds to the chart data sprite underneath the mouse pointer. Fonts - Font properties enable you to set a number of characteristics for the fonts used in the charts, such as the font size and style. Colors - Color properties enable you to set basic chart color characteristics, such as the color of the chart background. Brushes - You can apply a variety of different brushes for the purpose of rendering chart lines and fills in different ways. For example, if you want a line chart to render its lines with a dashed stroke instead of a solid one, you can use a brush element of the dashedStroke variety. Color palettes - The color palette element is used to control the colors used by brushes, which in turn are used to paint things like chart lines and series swatches in legends. You can define a set list of colors that the palette applies to series, or you can arrange to have the palette generate colors by interpolating between a range of colors (from red to yellow to blue for example). Brush palettes - Brush palettes match a series index to a brush type. This can come in handy for things like line charts, where you might want a different type of dashed or solid line for each series represented in the chart. Shapes and shape palettes - Shapes are used for markers in several cart types. You can have one shape be used throughout a chart, or you can use a shape palette to assign different shapes to different series. Layouts - The layout element controls the layout of all visual chart elements in a dashboard. In most cases you won't need to work with it, but you might use it to set up something like two charts that share the same xor y-axis. Data - The data element enables you to tweak the tabular format that contains the reporting data from which the chart is generated. In most cases you won't need to adjust the data settings.

307

 Text blocks - textBlock elements control text display in legend and axis labels as well as axis title and message text. Layout sprites and sprites - The layoutSprite and sprite elements are formatting elements that feed Flash display properties to many other elements throughout the charting system. In most cases you won't need to adjust these settings.

Chart and legend properties

This section covers properties for chart and legend, two of the more commonly modified flash charting elements.

Chart
Usage: charting.chart.* Use chart to define properties specific to the type of chart being displayed. For an overview of the charts and other visualization options offered by Splunk, see the "Visualization reference" topic in the User Manual. For more information about the data structures required by the various visualizations, see "Data structure requirements for visualizations" in the User Manual. Note: All charts have data and legend properties. There are also properties that are specific to single axis charts, and properties that are particular to Cartesian charts (charts with two axes, in other words). See the table below for details. Values The chart object has 12 possible values: area bar bubble column fillerGauge histogram line markerGauge pie radialGauge rangeMarker ratioBar scatter valueMarker
308

See the table below for detail on the parameters available for each chart type. Example 1 - Forcing categories for a column chart

<option name="charting.chart">column</option> <option name="charting.chart.useAbsoluteSpacing">true</option> <option name="charting.chart.columnSpacing">5</option> <option name="charting.axisX.categories">[pine,beech,mahogany,white,black]</option>

This example sets up a column chart with five preset categories to plot on the x-axis, and a space of five pixels between each column (useAbsoluteSpacing = true ensures that the columnSpacing values are measured in terms of pixels). Example 2 - Changing colors and color order in a gauge With gauge charts there are certain customizations that you can only make by editing the dashboard panel xml. This example exposes the parameters that you would use to both pick the colors used and indicate the order in which they display. It also exposes the parameter you would use to make the minimal version of the gauge display if you desired ("shiny" is the default). Note: When you specify range values in the xml, they override range values that are specified through the search upon which the dashboard panel is based.

<param <param <param <param

name="charting.chart">radialGauge</param> name="charting.chart.style">shiny</param> name="charting.chart.rangeValues">[0,30,70,100]</param> name="charting.gaugeColors">[0xBF3030,0xFFE800,0x84E900]</param>

In this example, the default colors are reversed (the order is red-yellow-green rather than the other way around). You can specify any number of colors with gaugeColors. If your gauge has more or less range intervals than the number of colors you specify, Splunk will interpolate the colors as necessary. Also used by layout.charts. Enables you to specify chart layouts. See "Advanced configuration - Layout and data table properties" for more information.

309

Properties for all charts All charts All chart types inherit properties from layoutSprite and have the following additional properties (see the tables above for full definitions). Property Value name type Definition Default
Affects the form of the data table that Splunk uses to plot the chart. See the data

Supported by JSChart?

data

dataTable

table for Yes specific defaults. Yes (see the legend table for details)

legend

legend

defaults. Properties for all single axis charts All single axis charts

See the Affects the legend display of the table for legend for specific the chart.

The following property is applicable only to single axis chart types, such as such as range marker and value marker charts. Property Value Definition Default name type
Properties that affect the axis on which report data is plotted. See the axis

Supported by JSChart?
Some axis

properties are tables for unsupported. axis axis specific (See the axis defaults. tables for details.) Properties for all cartesian (dual axis) charts All cartesian (dual axis) charts

310

The following properties are applicable only to cartesian chart types, such as bar, column, area, line, and scatter charts. Property Value Definition Default name type
Properties that affect the x-axis upon which data is plotted. The x-axis is horizontal. Properties that affect the y-axis upon which data is plotted. The y-axis is vertical. See the axis

Supported by JSChart?
Some axis

axisX

axis

properties are unsupported. tables for (See the axis specific tables for defaults. details.)
See the axis Some axis

axisY

axis

properties are unsupported. tables for (See the axis specific tables for defaults. details.)

Area chart properties Area chart properties The following properties are applicable only to area charts. The area chart is a cartesian chart that renders each series in a data set as a filled area with an optional line. The data table upon which the chart is structured must contain at least two columns, where the first column contains the values to be plotted on the x-axis (such as _time values for a timechart) and each additional column contains a series of values to be plotted on the y-axis. Property name Value type Definition Default Supported by JSChart?

areaBrushPalette

brushPalette

Indicates the brush palette used for See the painting the filled brushPalette areas in area charts. No Reference an existing table for specific palette with the @

symbol:
@mybrushpalette. areaStyle style<sprite>

defaults.
No

311

Indicates the properties to apply to area sprites in area charts. Indicates the brush palette to use for painting lines in area charts. Reference an existing palette with the @ symbol: @mybrushpalette.

See the sprite

table for specific defaults.

See the brushPalette

lineBrushPalette

brushPalette

table for specific defaults.

No

lineStyle

style<sprite>

See the The properties to sprite table apply to line sprites in for specific area charts.

No

defaults.

showLines

boolean

Indicates whether or not lines should be true painted in area charts. Used to set up stacked area charts. Valid values are default, stacked, stacked100.

Yes

stackMode

string

default

Yes

nullValueMode

string

Determines how the area chart handles null values. Valid gaps values are gaps, zero, and connect.

Yes

Bar chart properties Bar chart properties The following properties are applicable only to bar charts. The bar chart is a cartesian chart that renders data as horizontal bars. The data set must contain at least two columns, where the first column contains the values to be plotted on the y-axis and each additional column contains a series of values to be plotted on the x-axis. Property name
barBrushPalette

Value type brushPalette

Definition

Default

Supported by JSChart?

Indicates he brush See the No palette used for painting brushPalette

312

the bars in bar charts. Reference an existing palette with the @

symbol:
@mybrushpalette.

table for specific defaults.

barShapePalette

shapePalette

Indicates the shape palette that defines the See the shapePalette shapes of bars in bar charts. Reference an table for No existing palette with the specific @ symbol: defaults. @myshapepalette. The properties to apply to bar sprites in bar charts. Controls the alignment of bars relative to their position on the y axis. Typical values are between 0 (top aligned) and 1 See the sprite

barStyle

style<sprite>

table for specific defaults.

No

barAlignment

number

(a middle No alignment)
0.5

(bottom aligned).
Controls the spacing between bars in a bar chart. Whether this property is measured in pixels or is relative to 1. the bar heights depends on the setting of useAbsoluteSpacing

barSpacing

number

Yes

(below).
seriesSpacing number Controls the spacing between clustered series in a bar chart when stackMode = default. Whether 0

Yes

this property is measured in pixels or is relative to the bar heights depends on the setting of
useAbsoluteSpacing

313

(below).
Determines whether the values of barSpacing and seriesSpacing false are pixels (true) or

useAbsoluteSpacing

boolean

No

relative to the bar heights (false)

string Sets up stacked bar charts. Valid values are default default, stacked, and stacked100.

stackMode

Yes

Bubble chart properties Bubble chart properties The following properties are applicable only to bubble charts. The bubble chart is a cartesian chart that renders data as scattered "bubbles" whose size is determined by a third dimension of data. There are two possible forms for the data set upon which the chart is based: 1. A single series structure that contains 3 columns. The first column (column 0) contains the values to be plotted on the x-axis. The second column (column 1) contains the values to be plotted on the y-axis. And the third column (column 2) contains the values to be plotted on the z-axis. 2. A multiple series structure with 4 columns. Column 0 contains the series names, and the next 3 columns contain the values to be plotted on each axis (as in the first form, above). Property name Value type Definition Default
See the axis

Supported by JSChart?

axisZ

axis

A third axis used for plotting the bubble values.

table for specific defaults.

No

bubbleBrushPalette

brushPalette

Indicates the brush See the No palette used for brushPalette painting the bubbles table for in bubble charts. specific Reference an existing defaults. palette with the @

314

symbol:
@mybrushpalette. Indicates the shape palette that defines See the the shapes of bubbles shapePalette in bubble charts. No Reference an existing table for specific palette with the @

bubbleShapePalette

shapePalette

symbol:
@myshapepalette. The properties to apply to bubble sprites in bubble charts. The minimum size of bubbles in pixels. The maximum size of bubbles in pixels. The series name to use for indexing into palettes and legends when only 3 columns are present in the data.

defaults.
See the sprite

bubbleStyle

style<sprite>

table for specific defaults.

10 50

No

bubbleMinimumSize bubbleMaximumSize

number number

No No

defaultSeriesName

string

bubble

No

Column chart properties Column chart properties The following properties are applicable only to column charts. The column chart is a Cartesian chart that renders data as vertical columns. The data table upon which the chart is structured must contain at least two columns, where the first column contains the values to be plotted on the x-axis, and each additional column contains a series of values to be plotted on the y-axis. Property name
columnBrushPalette

Value type brushPalette

Definition

Default

Supported by JSChart?

Indicates the brush See the No palette used for brushPalette painting the columns table for in column charts. specific Reference an existing defaults. palette with the @

symbol:
315

@mybrushpalette. Indicates the shape palette that defines the shapes of columns in column charts. Reference an existing palette with the @ symbol: @myshapepalette. The properties to apply to column sprites in column charts. The alignment of columns relative to their position on the x-axis. Typical values are between 0 (left aligned) and 1 See the shapePalette

columnShapePalette

shapePalette

table for specific defaults.

See the sprite

No

columnStyle

style<sprite>

table for specific defaults.

No

columnAlignment

number

(a centered alignment)
0.5

No

(right aligned).
columnSpacing number Controls the spacing between columns in a 1 column chart Controls the spacing between clustered series in a column chart when stackMode = default Determines whether the values of columnSpacing

Yes

seriesSpacing

number

Yes

and
useAbsoluteSpacing boolean seriesSpacing are false pixels (true) or No

relative to the column heights (false)

Sets up stacked column charts. Valid values are default, stacked, and stacked100.

stackMode

string

default

Yes

316

Filler gauge properties Filler gauge properties

The following properties are applicable only to fillerGauge charts. The filler gauge, like the other g enables the visualization of a single numerical value mapped against a range of colors that may ha meaning or logic. The filler gauge is similar in appearance to a thermometer, with a liquid-like filler color as it rises or lowers and passes range boundaries. The gauge range can be provided in the s using the rangeValues property (which overrides any range values present in the data). At least tw required to define a minimum and maximum range; additional values can be supplied to define inte minimum and maximum. By default Splunk assigns colors to each defined interval within the range on the color of the interval that the gauge value belongs to. For more information, see the "Chart g User Manual. Property name Value type Definition
Sets the gauge orientation. Valid values are x (horizontal) and y

Default

orientation

string

(vertical).
Enables the choice between two basic gauge appearances. The shiny style is a graphically

style

string

stylized version of the gauge with with chrome, shading, and so on so that it mimics those in shiny the real world. The minimal style is a stripped-down "just the basics" version of the gauge.
Indicates the brush palette to use for drawing the variable colored fill within the indicator. If null, a solid black fill is See the brushPalette drawn. Reference an existing palette specific defaults. with the @ symbol: @myfillerbrushpalette. The style to apply to the filler. The starting placement of the filler indicator, in pixels centered around the orientation axis. The ending placement of the filler indicator, in pixels centered around See the sprite

fillerBrushPalette

brushPalette

ta

fillerStyle

style<sprite>

table for

defaults.
-20 20

fillerPlacement1 fillerPlacement2

number number

317

the orientation axis. 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] would

rangeValues

array<number>

indicate that the gauge starts at zero, ends at 100, and has three subranges that are each identified by another filler color. If the search returns a value of Not assigned. 71, the filler rises to that value on the gauge and takes on the color assigned to the middle range (61-85). Note: When you specify range values in the xml, they override range values that are specified through the search upon which the dashboard panel is based.
The padding to place on either end of 20 the range, in pixels. A list 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 sequence by changing the gaugeColors value

rangePadding

Number

to
[0xBF3030,0xFFE800,0x84E900]. gaugeColors array<number>

You can specify any number of [0x84E900,0xFFE800,0x colors. If your gauge has more or less range intervals (either specified via the search language or the rangeValues parameter) than the number of rangeColors, Splunk will interpolate the colors as necessary.
The brush that is used to draw the major tick marks. See the brush

majorTickBrush

brush

table for s

defaults.

318

majorTickStyle

style<sprite>

Indicates the style properties that are See the sprite applied to major tick marks. defaults. The starting placement of the major tick marks, in pixels centered around the orientation axis. The ending placement of the major tick marks, in pixels centered around the orientation axis. The spacing at which major tick marks are placed. The brush that draws the minor tick marks. The style properties that are applied to minor ticks. The starting placement of the minor tick marks, in pixels centered around the orientation axis. The ending placement of the minor tick marks, in pixels centered around the orientation axis. The spacing at which minor tick marks are placed. The style properties to apply to tick labels. 20

table for

majorTickPlacement1

number

majorTickPlacement2

number

40

majorUnit minorTickBrush

number

auto See the brush

brush
style<sprite>

table for s

defaults.
See the sprite

minorTickStyle

table for

defaults.
20

minorTickPlacement1

number

minorTickPlacement2

number

30

minorUnit labelStyle

number style<textBlock>

auto See the textBlock

table

specific defaults.

labelPlacement

number

The placement of the tick labels, in pixels centered around the orientation 40 axis. Provides the style properties for the value at the bottom of the gauge. Note that valueStyle can be used to change the way the value displays (font, bolding, italicization, and so on.), but it can't be used to actually change the text itself. For example, you can't use valueStyle to replace the value with a specific text string. The placement of the value, in pixels centered around the orientation axis. The brush to use when drawing the warning indicator. The shape to use when drawing the warning indicator.

valueStyle

style<textBlock>

See the textBlock

table

specific defaults.

valuePlacement warningBrush

number

-20 See the brush

brush shape
319

table for s

defaults.
See the shape

warningShape

table for s

defaults.

warningStyle

style<sprite>

The style properties to apply to the warning indicator. The placement of the warning indicator, in pixels centered around the orientation axis. The size of the warning indicator, in pixels. The brush to use for drawing the gauge foreground. The style properties to apply to the gauge foreground. The starting placement of the gauge foreground, in pixels around the orientation axis. The ending placement of the gauge foreground, in pixels around the orientation axis.

See the sprite

table for

defaults.
70

warningPlacement

number

warningSize foregroundBrush

number

20 See the brush

brush
style<sprite>

table for s

defaults.
See the sprite

foregroundStyle

table for

defaults.
-20

foregroundPlacement1

number

foregroundPlacement2

number

20

foregroundPadding backgroundBrush

number

The padding to place on either end of 20 the gauge foreground, in pixels. The brush to use for drawing the gauge background. The style properties to apply to the gauge background. The starting placement of the gauge background, in pixels around the orientation axis. The ending placement of the gauge background, in pixels around the orientation axis. See the brush

brush
style<sprite>

table for s

defaults.
See the sprite

backgroundStyle

table for

defaults.
-20

backgroundPlacement1

number

backgroundPlacement2

number

20

backgroundPadding

number

The padding to place on either end of 20 the gauge background, in pixels.

layers

array<string>

The layering order of the visual elements that make up the filler gauge. The elements are presented as a list; the element order [ background, minorTi determines how the elements are majorTicks, labels, w layered on top of one another (first on filler, value, foregr bottom, last on top). Elements not specified in this list remain in their default order below all the specified elements. false

usePercentageRange

boolean

320

Determines whether the range values should be formatted as percentages. usePercentageValue showMajorTicks showMinorTicks showLabels showValue boolean boolean boolean boolean boolean Determines whether to format the gauge value as a percentage. Determines whether the gauge should display major tick marks. Determines whether the gauge should display minor tick marks. Determines whether the gauge should display labels. Determines whether the gauge should show its value. false true true true true

Histogram properties Histogram properties The following properties are applicable only to histogram charts. The histogram chart is a cartesian chart that renders data as vertical columns whose width is determined by separate start and end values. The data table upon which the chart is structured must contain at least three columns, where column 0 contains the starting values to be plotted on the x-axis, column 1 contains the ending values to be plotted on the x-axis, and column 2 contains the values to be plotted on the y-axis. Multiple series are currently unsupported and additional columns are ignored. Property name Value type Definition Default Supported by JSChart?

columnBrushPalette

brushPalette

Indicates the brush palette used for See the painting the columns brushPalette in histogram charts. No Reference an existing table for specific palette with the @

symbol:
@mybrushpalette. Indicates the shape palette that defines the shapes of columns in histogram charts. Reference an existing palette with the @ symbol: @myshapepalette.

defaults.

columnShapePalette

shapePalette

See the shapePalette

for specific defaults.

No

321

columnStyle

style<sprite>

The properties to apply to column sprites in histogram charts.

See the sprite

table for specific defaults.

No

Line chart properties Line chart properties The following properties are applicable only to line charts. The line chart is a cartesian chart that renders each series in a data set as a line with optional markers. The data table upon which the chart is structured must contain at least two columns, where the first column contains the values to be plotted on the x-axis (such as _time values for a timechart) and each additional column contains a series of values to be plotted on the y-axis. Property name Value type Definition Default
See the brushPalette

Supported by JSChart?

lineBrushPalette

brushPalette

The brush palette to use for painting lines in line charts.

table for specific defaults.

No

lineStyle

style<sprite>

See the The properties to sprite table apply to line sprites in for specific line charts.

No

defaults.

markerBrushPalette

brushPalette

Indicates the brush See the palette to use for brushPalette painting markers in line charts. Reference table for No an existing palette specific with the @ symbol: defaults. @mybrushpalette. Indicates the shape palette that defines See the the shape of markers shapePalette in line charts. No Reference an existing table for specific palette with the @

markerShapePalette

shapePalette

symbol:
@myshapepalette. markerStyle style<sprite>

defaults.
No

322

The properties to apply to marker sprites in line charts.

See the sprite

table for specific defaults. Yes

showMarkers

boolean

Indicates whether or not markers should be false painted in line charts. Used to set up stacked line charts. Valid values are default, stacked, stacked100.

stackMode

string

default

Yes

nullValueMode

string

Determines how the line chart handles null values. Valid values gaps are gaps, zero, and connect.

Yes

Marker gauge properties Marker gauge properties

The following properties are applicable only to markerGauge charts. The marker gauge, like the othe enables the visualization of a single numerical value mapped against a range of colors that may ha meaning or logic. The marker gauge is similar in appearance to a slide rule, with a linear range sca that rests at the value returned by the search. The gauge range can be provided in the search lang using the rangeValues property (which overrides any range values present in the search language) values are required to define a minimum and maximum range; additional values can be supplied to between the minimum and maximum. By default Splunk assigns colors to each defined interval wit running in parallel with the range maps these colors to specific sections of the range. For more info gallery" topic in the User Manual and look for the subtopic on marker gauges. Property name Value type Definition
Sets the gauge orientation. Valid values are x (horizontal) and y

Default

orientation style

string string

y shiny

(vertical).
Enables the choice between two basic gauge appearances. The shiny style is a graphically

stylized version of the gauge with with chrome, shading, and so on so that it mimics those in
323

the real world. The minimal style is a stripped-down "just the basics" version of the gauge.
markerBrush

brush shape
style<sprite>

The brush to use for drawing the gauge marker. The shape to use when drawing the gauge marker. The properties to apply to the gauge marker. The placement of the base of the gauge marker, in pixels centered around the orientation axis.

See the brush

table for

defaults.
See the shape

markerShape

table for

defaults.
See the sprite

markerStyle

table fo

defaults.
-20

markerPlacement1

number

markerPlacement2

number

The placement of the tip of the gauge marker, in pixels centered around the 20 orientation axis. The thickness of the gauge marker, in 5 pixels. 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] would

markerThickness

number

rangeValues

array<number>

indicate that the gauge starts at zero, ends at 100, and has three subranges that are each identified by a different color on the range band. If the search Not assigned. returns a value of 71, the gauge marker moves to the spot where 71 would be on the gauge, and where the range band has the color assigned to the middle range (61-85). Note: When you specify range values in the xml, they override range values that are specified through the search upon which the dashboard panel is based.
The padding to place on either end of 20 the range, in pixels.

rangePadding

Number

324

A list 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 sequence by changing the gaugeColors value

to
[0xBF3030,0xFFE800,0x84E900]. gaugeColors array<number>

You can specify any number of [0x84E900,0xFFE800,0 colors. If your gauge has more or less range intervals (either specified via the search language or the rangeValues parameter) than the number of rangeColors, Splunk will interpolate the colors as necessary.
Indicates the brush palette to use for drawing the variable colored range band. Reference an existing palette with the @ symbol: @mybrushpalette. The style properties to apply to the variable colored range band. See the brushPalette

rangeBandBrushPalette

brushPalette

specific defaults.
See the sprite

rangeBandStyle

style<sprite>

table fo

defaults.

rangeBandPlacement1

number

The placement of the first edge of the variable colored range band, in pixels -20 centered around the orientation axis. The placement of the second edge of the variable colored range band, in 20 pixels centered around the orientation axis. The brush that is used to draw the major tick marks. See the brush

rangeBandPlacement2

number

majorTickBrush

brush
style<sprite>

table for

defaults.

majorTickStyle

Indicates the style properties that are See the sprite applied to major tick marks. defaults. The starting placement of the major tick marks, in pixels centered around the orientation axis. The ending placement of the major tick marks, in pixels centered around the orientation axis. 20

table fo

majorTickPlacement1

number

majorTickPlacement2 majorUnit

number number

40 auto

325

The spacing at which to place major tick marks. minorTickBrush

brush
style<sprite>

The brush that is used to draw the minor tick marks.

See the brush

table for

defaults.

minorTickStyle

Indicates the style properties that are See the sprite applied to minor tick marks. defaults. The starting placement of the minor tick marks, in pixels centered around the orientation axis. The ending placement of the minor tick marks, in pixels centered around the orientation axis. The spacing at which to place minor tick marks. The style properties to apply to tick labels. 20

table fo

minorTickPlacement1

number

minorTickPlacement2

number

30

minorUnit labelStyle

number style<textBlock>

auto See the textBlock

tabl

specific defaults.

labelPlacement

number

The placement of the tick labels, in pixels centered around the orientation 40 axis. Provides the style properties for the value at the bottom of the gauge. Note that valueStyle can be used to change the way the value displays (font, bolding, italicization, and so on.), but it can't be used to actually change the text itself. For example, you can't use valueStyle to replace the value with a specific text string. The placement of the value, in pixels centered around the orientation axis. The brush to use when drawing the warning indicator. The shape to use when drawing the warning indicator. The style properties to apply to the warning indicator. The placement of the warning indicator, in pixels centered around the orientation axis. The size of the warning indicator, in pixels.

valueStyle

style<textBlock>

See the textBlock

tabl

specific defaults.

valuePlacement warningBrush

number

-20 See the brush

brush shape
style<sprite>

table for

defaults.
See the shape

warningShape

table for

defaults.
See the sprite

warningStyle

table fo

defaults.
70

warningPlacement

number

warningSize

number

20

326

foregroundBrush

brush
style<sprite>

The brush to use for drawing the gauge foreground. The style properties to apply to the gauge foreground. The starting placement of the gauge foreground, in pixels around the orientation axis. The ending placement of the gauge foreground, in pixels around the orientation axis.

See the brush

table for

defaults.
See the sprite

foregroundStyle

table fo

defaults.
-20

foregroundPlacement1

number

foregroundPlacement2

number

20

foregroundPadding backgroundBrush

number

The padding to place on either end of 20 the gauge foreground, in pixels. The brush to use for drawing the gauge background. The style properties to apply to the gauge background. The starting placement of the gauge background, in pixels around the orientation axis. The ending placement of the gauge background, in pixels around the orientation axis. See the brush

brush
style<sprite>

table for

defaults.
See the sprite

backgroundStyle

table fo

defaults.
-20

backgroundPlacement1

number

backgroundPlacement2

number

20

backgroundPadding

number

The padding to place on either end of 20 the gauge background, in pixels. The layering order of the visual elements that make up the filler gauge. The elements are presented as a list; the element order determines how the elements are layered on top of one another (first on bottom, last on top). Elements not specified in this list remain in their default order below all the specified elements.

layers

array<string>

[ background, rangeB minorTicks, majorTic labels, warning, mar value, foreground ]

usePercentageRange usePercentageValue

boolean boolean

Determines whether the range values false should be formatted as percentages. Determines whether to format the gauge value as a percentage. Determines whether the gauge should display the variable colored range band. Determines whether the gauge should display major tick marks. false

showRangeBand

boolean

true

showMajorTicks

boolean

true

327

showMinorTicks showLabels showValue

boolean boolean boolean

Determines whether the gauge should display minor tick marks. Determines whether the gauge should display labels. Determines whether the gauge should show its value.

true true true

Pie chart properties Pie chart properties The following properties are applicable only to pie charts. The pie chart is a basic chart that renders data as a circle divided into "slices." The data table upon which the chart is structured must contain at least two columns, where the first column contains the labels for each pie chart slice, and the second column contains the values for those slices. Splunk pie charts do not currently support multiple series, and additional columns are not supported. Property name Value type Definition Default Supported by JSChart?

sliceBrushPalette

brushPalette

The brush palette to use for painting slices See the in pie charts. brushPalette Reference an existing table for No palette with the @ specific

symbol:

@mybrushpalette. The properties to apply to slice sprites in line charts.

defaults.
See the sprite

sliceStyle

style<sprite>

table for specific defaults.

No

sliceCollapsingThreshold

number

The threshold at which smaller slices should be collapsed 0.01 (slices into a consolidated slice. Valid values are smaller than 1% of the between 0 (no collapsing) and 1 whole pie are

Yes

(all slices are collapsed into a single pie).

sliceCollapsingLabel labelStyle string style<textBlock> The label for the consolidated slice.

collapsed)

other

Yes
No

328

Applies properties to pie slice labels

See the textBlock

table for specific defaults.

Indicates the brush to use for painting label See the brush lines. Reference an table for existing palette with specific the @ symbol: defaults. @mybrushpalette. Determines whether or not pie chart labels true are displayed. Determines whether percentage values are false shown along with the labels.

labelLineBrush

brush

No

showLabels

boolean

Yes

showPercent

boolean

Yes

Radial gauge properties Radial gauge properties

The following properties are applicable only to radialGauge charts. The radialGauge, like the other enables the visualization of a single numerical value mapped against a range of colors that may ha meaning or logic. The radial gauge is similar in appearance to a speedometer in appearance; it ha and a rotating needle. The gauge range can be provided in the search or hardcoded using the rang (which overrides any range values present in the data). At least two range values are required to d maximum range; additional values can be supplied to define intervals between the minimum and m Splunk assigns colors to each defined interval within the range. For more information, see the "Cha User Manual and look for the subtopic on radial gauges. Property name
style

Value type
string

Definition
Enables the choice between two basic gauge appearances. The shiny style is a graphically

Default
shiny

stylized version of the gauge with with chrome, shading, and so on so that it mimics those in the real world. The minimal style is a stripped-down "just the basics" version of the

329

gauge.
needleBrush

brush shape
style<sprite>

The brush to use for drawing the gauge needle. The shape to use when drawing the gauge needle. The properties to apply to the gauge needle. The radius of the base of the gauge needle, in relative coordinates (typically between -1 and 1). The radius of the tip of the gauge needle, in relative coordinates (typically between 0 and 1).

See the brush

table for

defaults.
See the shape

needleShape

table for

defaults.
See the sprite

needleStyle

table fo

defaults.
0

needleRadius1

number

needleRadius2

number

0.9

needleThickness rangeValues

number array<number>

The thickness of the gauge needle, in in relative coordinates (typically 0.05 between 0 and 1). Not assigned. 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] would

indicate that the gauge starts at zero, ends at 100, and has three subranges that are each identified by a different color on the range band. If the search returns a value of 71, the gauge needle moves to the spot where 71 would be on the gauge, and where the radial gauge is shaded with the color assigned to the middle range (61-85). If the value ever falls outside of the top or bottom range of the gauge, the needle "flutters" at the boundary and a warning icon appears.

330

Note: When you specify range values in the xml, they override range values that are specified through the search upon which the dashboard panel is based.
A list 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 sequence by changing the gaugeColors value

to
[0xBF3030,0xFFE800,0x84E900]. gaugeColors array<number>

You can specify any number of [0x84E900,0xFFE800,0 colors. If your gauge has more or less range intervals (either specified via the search language or the rangeValues parameter) than the number of rangeColors, Splunk will interpolate the colors as necessary.
The angle (clockwise starting from the bottom of the gauge) at which to begin drawing the range arc, in degrees. The length of the range arc, in degrees (positive values are clockwise, negative values are counterclockwise). Indicates the brush palette to use for drawing the variable colored range band. Reference an existing palette with the @ symbol: @myrangebandbrushpalette. The style properties to apply to the variable colored range band. The inner radius of the variable colored range band, in relative coordinates (typically between 0 and 1). 45

rangeStartAngle

number

rangeArcAngle

number

270

rangeBandBrushPalette

brushPalette

See the brushPalette

specific defaults.
See the sprite

rangeBandStyle

style<sprite>

table fo

defaults.
0.8

rangeBandRadius1

number

rangeBandRadius2

number

0.9

331

The outer radius of the variable colored range band, in relative coordinates (typically between 0 and 1). majorTickBrush

brush
style<sprite>

The brush that is used to draw the major tick marks.

See the brush

table fo

defaults.

majorTickStyle

Indicates the style properties that are See the sprite applied to major tick marks. defaults. The inner radius of the major tick marks, in relative coordinates (typically between 0 and 1). The outer radius of the major tick marks, in relative coordinates (typically between 0 and 1). The spacing at which to place major tick marks. The brush that is used to draw the minor tick marks. 0.7

table fo

majorTickRadius1

number

majorTickRadius2

number

0.8

majorUnit minorTickBrush

number

auto See the brush

brush
style<sprite>

table for

defaults.

minorTickStyle

Indicates the style properties that are See the sprite applied to minor tick marks. defaults. The inner radius of the minor tick marks, in relative coordinates (typically between 0 and 1). The outer radius of the minor tick marks, in relative coordinates (typically between 0 and 1). The spacing at which to place minor tick marks. 0.75

table fo

minorTickRadius1

number

minorTickRadius2

number

0.8

minorUnit labelStyle

number style<textBlock>

auto

The style properties to apply to labels See the textBlock along the range arc. specific defaults. The radius at which to place labels, in relative coordinates (typically 0.7 between 0 and 1). Provides the style properties for the value at the bottom of the gauge. Note that valueStyle can be used to change the way the value displays (font, bolding, italicization, and so on.), but it can't be used to actually change the text itself. For example, you can't use valueStyle to replace the value with a specific text string.

tabl

labelRadius

number

valueStyle

style<textBlock>

See the textBlock

tabl

specific defaults.

332

valueRadius

number

The radius at which to place the value, in relative coordinates (typically between 0 and 1). The brush to use when drawing the warning indicator. The shape to use when drawing the warning indicator. The style properties to apply to the warning indicator. The radius at which to place the warning indicator, in relative coordinates (typically between 0 and 1). The size of the warning indicator, in relative coordinates (typically between 0 and 1). The brush to use for drawing the gauge foreground. The style properties to apply to the gauge foreground. The radius of the gauge foreground, in relative coordinates (typically between 0 and 1). The brush to use for drawing the gauge background. The style properties to apply to the gauge background. The radius of the gauge background, in relative coordinates (typically between 0 and 1). The layering order of the visual elements that make up the radial gauge. The elements are presented as a list; the element order determines how the elements are layered on top of one another (first on bottom, last on top). Elements not specified in this list remain in their default order below all the specified elements.

0.8 See the brush

warningBrush

brush shape
style<sprite>

table for

defaults.
See the shape

warningShape

table for

defaults.
See the sprite

warningStyle

table fo

defaults.
1

warningRadius

number

warningSize

number

0.1 See the brush

foregroundBrush

brush
style<sprite>

table for

defaults.
See the sprite

foregroundStyle

table fo

defaults.
1 See the brush

foregroundRadius

number

backgroundBrush

brush
style<sprite>

table for

defaults.
See the sprite

backgroundStyle

table fo

defaults.
1

backgroundRadius

number

layers

array<string>

[ background, rangeB minorTicks, majorTic labels, value, warni needle, foreground ]

usePercentageRange

boolean

Determines whether the range values false should be formatted as percentages.

333

usePercentageValue

boolean

Determines whether to format the gauge value as a percentage. Determines whether the gauge should display the variable colored range band. Determines whether the gauge should display major tick marks. Determines whether the gauge should display minor tick marks. Determines whether the gauge should display labels. Determines whether the gauge should display its value.

false

showRangeBand

boolean

true

showMajorTicks showMinorTicks showLabels showValue

boolean boolean boolean boolean

true true true true

Range marker properties Range marker properties The following properties are applicable only to rangeMarker charts. The range marker is a single-axis chart that renders a fill spanning the area between two points on an axis. The data table upon which the chart is structured must contain at least one column with two rows, where the first row contains the minimum value to be plotted on the axis, and the second row contains the maximum value. The minimumValue and maximumValue properties may optionally be used in place of the data set. Range marker charts are related to value marker charts in that they are mainly useful as overlays above another chart, such as a line chart. Value Property name Definition type
minimumValue string

Default

Supported by JSChart?
No

The optional minimum Not value to plot. assigned. The optional maximum value to plot. Not assigned.

maximumValue

string

No

orientation

string

Determines the range marker orientation. Valid values are x x (horizontal) and y

No

(vertical).
lineBrush

brush

Indicates the brush to See the use for painting label brush

No

334

lines. Reference an existing palette with the @ symbol: @mybrushpalette.

table for specific defaults.

innerFillBrush

brush

Indicates the brush to use for painting the fill See the inside the minimum and maximum range brush marker values. table for Reference an existing specific palette with the @

No

symbol:
@mybrushpalette.

defaults.

outerFillBrush

brush

Indicates the brush to use for painting the fill outside the minimum See the and maximum range brush marker values. table for Reference an existing specific palette with the @

No

symbol:
@mybrushpalette.

defaults.

Ratio bar chart properties Ratio bar chart properties The following properties are applicable only to ratioBar charts. The ratio bar chart is a basic chart that renders data as a divided bar. The data table upon which the chart is structured must contain at least two columns, where the first column contains the labels for each bar and the second column contains the values that correspond to each label. Multiple series are currently not supported, and additional columns are ignored. Property name Value type Definition
Determines the ratio bar orientation. Valid values are x (horizontal) and y

Default

Supported by JSChart?

orientation

string

No

(vertical).
barBrushPalette

brushPalette

Indicates the brush See the No palette used for brushPalette painting the bars in table for ratio bar charts. specific Reference an existing

335

palette with the @

defaults.

symbol:
@mybrushpalette. The properties that can be applied to bar sprites in ratio bar charts. See the sprite

barStyle

style<sprite>

table for specific defaults.

No

barCollapsingThreshold

number

Controls the threshold at which smaller ratio bars are collapsed 0.01 (bars into a consolidated bar. Valid values are smaller than 1% of the between 0 (no collapsing) and 1 whole are

No

collapsed). (all bars are collapsed into a consolidated bar).

sliceCollapsingLabel string The label for the other consolidated ratio bar. See the textBlock No

labelStyle

style<textBlock>

Applies properties to ratio bar labels

table for specific defaults.

No

labelLineBrush

brush

Indicates the brush to use for painting label See the brush lines. Reference an table for existing palette with specific the @ symbol: defaults. @mybrushpalette. Determines whether ratio bar chart labels are displayed. Determines whether percentages are displayed along with the labels. true

No

showLabels

boolean

No

showPercent

boolean

true

No

Scatter chart properties Scatter chart properties The following properties are applicable only to scatter charts. The scatter chart is a Cartesian chart that renders data as scattered markers. The data must be in one of
336

two forms: 1. A single series setup, where the chart is structured on a data table that contains 2 columns, where the first column (column 0) contains the values to be plotted on the x-axis, and the second column (column 1) contains the values to be plotted on the y-axis. 2. A multiple series setup, where the chart is structured on a data table that contains 3 columns. The first column (column 0) contains the series names, and the next two columns contain the values to be plotted on the x- and y-axes, respectively (see form 1, above). Property name Value type Definition Default Supported by JSChart?

markerBrushPalette

brushPalette

Indicates the brush See the palette to use for painting markers. brushPalette Reference an existing table for No palette with the @ specific

symbol:

@mybrushpalette. Indicates the shape palette that defines the shapes of markers. Reference an existing palette with the @ symbol: @myshapepalette. Applies properties to marker sprites.

defaults.
See the shapePalette

markerShapePalette

shapePalette

table for specific defaults.

See the sprite

No

markerStyle

style<sprite>

table for specific defaults.

No

markerSize

number

The size of the scatter chart markers, in 4 pixels. The series name to use for indexing into palettes and legends when only 2 columns can be present in the data.

Yes

defaultSeriesName

string

scatter

No

337

Value marker properties Value marker properties The following properties are applicable only to valueMarker charts. Value marker charts are are single-axis charts that render a line at a single point on an axis. The data table upon which the chart is structured must contain at least one column with one row, where the row contains the value to be plotted on the axis, and the second row contains the maximum value. The value property can optionally be used in place of the data set. Value marker charts are related to range marker charts in that they are mainly useful as overlays above another chart, such as a line chart. Property name
value

Value Definition type

string The optional value to plot. Determines the value marker orientation. Valid values are x (horizontal) and y

Default
Not assigned.

Supported by JSChart?
No

orientation

string

No

(vertical).
Indicates the brush to See the use for painting the value marker line. brush Reference an existing table for palette with the @ specific

lineBrush

brush

No

symbol:

@mybrushpalette.

defaults.

Legend
Usage: charting.legend.* The legend element controls the chart legend. It is used by all chart types. Note: You can also take advantage of a predefined external legend element called externalLegend. externalLegendis a non-visual object that connects to an external source responsible for synchronizing legends across multiple charting modules in a view. It has no additional properties. It is referenced by the masterLegend parameter (see below). You can also refer to it directly if necessary
338

using the @ symbol: @externalLegend. For more information about making element and property references see "Advanced charting options" in this manual. Values legend Example

<option name="charting.legend">legend</option> <option name="charting.legend.placement">left</option> <option name="charting.legend.labelStyle.maximumWidth">500</option> <option name="charting.legend.labelStyle.defaultTextFormat">{italic:true,size:14}</option>

These settings have the legend appearing to the left of the chart, with a maximum allowable width of 500 pixels, and text that is 14 points in size and italicized. and maximumWidth are textBlock properties. maximumWidth is a property that is ultimately inherited from layoutSprite. defaultTextFormat enables you to set a variety of text formatting properties in one line. See the table below for the full list of legend properties.
defaultTextFormat

Also used by layout.legends Enables you to specify a list of legend types. See "Advanced configuration Layout and data table properties" for more information. Properties Legend properties The legend is the main visual legend type that displays labels and their corresponding color swatches. It inherits properties from layoutSprite and has the following additional properties. Property name Value type Definition Supported Default by JSChart?

339

labels

array<string>

A comma-separated list of labels to pre-populate the legend with.

Not assigned

No

defaultSwatchBrushPalette

brushPalette

The brush palette to use for painting swatches that have not been provided by Not a chart. Reference an assigned existing palette with the @ symbol: @mybrushpalette. If you want all charts in a particular dashboard view to use the same colors in their legends, you can use masterLegend to

No

masterLegend

legend

act as a "master legend" for each of them. You can reference an existing legend for your charts with the @ symbol: Not No @mylegend. assigned Note: This parameter influences series color mappings made with seriesColors. For more information, see the Chart colors subtopic of the "Advanced charting" topic, in this manual.

placement

string

The placement of the right legend within a cartesian layout. Valid values are left,

Yes

340

right, top, bottom, center, and none. Controls the orientation of the legend in relation to the chart axes. Valid values are x, y, and auto.

orientation

string

auto

No

swatchPlacement

string

Controls the placement of legend swatches in relation to legend labels. Valid left values are left, right, top, and bottom. Applies properties to legend labels. See the Not textBlock assigned

No

labelStyle

style<textBlock>

No

properties for more information.

style<layoutSprite> Applies layoutSprite

swatchStyle

properties to legend swatches.

Applies layoutSprite

Not assigned

No

itemStyle

style<layoutSprite>

properties to legend items.

Not assigned

No

Axis and grid line properties

This topic lists the properties for the axis, axisLabels, axisTitle, and gridLines elements.

Axis
Usage: charting.axisX.* and charting.axisY.* An axis is a non-visual object that maps data to some relative location depending on its type and various options. The visual part of an axis is handled by a separate element - axis labels.
341

If you are working with a single-axis chart (range marker, value marker), then you just use axisX to work with its axis properties. If you are working with a cartesian (dual axis) chart (area, bar, bubble, column, histogram, line, and scatter) you use axisX and axisY to set properties for the xand y-axes, respectively. Note: Keep in mind that for bar charts, axisY is reversed so that values descend from top to bottom vertically:
<option name="charting.axisY.reverse">true</option> For more information, see the documentation of the reverse

parameter, below.

Values has three main values that depend on the type of values being plotted on the axis:
axis

category: For the plotting of categorical values, like a series of host names in a column chart. numeric: For the plotting of numeric values, such as a range from 1-1000. time: For the plotting of time values along a timeline. Example

<option <option <option <option <option

name="charting.axisX">numeric</option> name="charting.axisX.minimumNumber">10</option> name="charting.axisX.maximumNumber">200</option> name="charting.axisY">category</option> name="charting.axisY.categories">[red,white,blue]</option>

This code sets up a numeric x-axis scale that starts at 10 and stops at 200. Values below and above that range are not plotted on the chart. It also hard-codes three categories for the y-axis: red, white, and blue. If the search upon which the chart is based is charting values of a colors field, this ensures that only events with red, white, and blue values get plotted. (Note that you can also arrange this behavior through search language.) Also used by
axis

is not used by other elements.

342

Properties for all axis types All axis types The following properties affect all axis types. Property Value name type Supported Definition Default by JSChart?

reverse

Determines whether or not the axis is reversed. Bar chart Y axes are boolean reversed so that values descend from top to bottom vertically.

false

No

Properties for category (non-numeric) axes Category axes The following properties apply only to category axes, which plot categorical values (values that are string-based in nature, but are not time values). Property name Value type Definition
The list of categories to plot on the axis, delimited by commas array<string> without spaces and formatted within brackets. comparator

Supported Default by JSChart?

categories

auto

No

comparator

The comparator to use none to sort the list or categories. Comparators can be alphabetic

No

(values are sorted alphabetically), natural (values

343

are sorted according to their natural ordering), numeric (values are sorted numerically), or
sequentialNumeric

(values are sorted according to the sequence of numbers contained within them--useful for IP addresses, version strings, and similar numeric sequences). Properties for numeric axes Numeric axes The following properties apply only to numeric axes, which plot numeric values. Property name
scale

Value type
scale

Supported Definition Default by JSChart?

The scale to apply to the axis. When set to true this false

Yes

includeZero

boolean

forces the false axis range to include zero.

Sets the minimum number for the visible axis range. Sets the maximum

Yes

minimumNumber

number

auto

Yes

maximumNumber

number

auto

Yes

344

number for the visible axis range.

Properties for time axes Time axes The following properties apply only to time axes, which plot time values along a timeline. Property name Value type Definition Supported Default by JSChart?

minimumTime

Sets the minimum time for the visible axis range. Value should be an datetime ISO-8601 date time string in the following format: YYYY-MM-DDTHH:MM:SS.MMM-HH:MM Sets the maximum time for the visible axis range. Value should be an datetime ISO-8601 date time string in the following format: YYYY-MM-DDTHH:MM:SS.MMM-HH:MM

auto

No

maximumTime

auto

No

Axis labels
Usage: charting.axisLabelsX.* and charting.axisLabelsY.* The axisLabels element enables the visualization of chart axes. It places tick marks and labels at locations along chart axes that are appropriate depending upon the state of those axes. The separation between the axis and axisLabels element allows a single axis to have multiple sets of labels and tick marks, which is useful if you want duplicate labels on both sides of a chart (in other words, a chart with an X axis at the bottom, and duplicate Y axes on the left and right side). The Search app timeline is an example of just such a chart. This separation also enables the setup of charts with labels in different unit resolutions (such as one in years and one in months). Values The axisLabels element has three values that relate to the three types of axes that Splunk supports (see the axis element for more information).
345

 category numeric time It's important to note that most axisLabels parameters belong to all axis types. Example

<option name="charting.axisLabelsX">numeric</option> <option name="charting.axisLabelsX.integerUnits">true</code> <option name="charting.axisLabelsX.minorTickSize">10</option> <option name="charting.axisLabelsX.majorTickSize">20</option> <option name="charting.axisLabelsX.majorLabelAlignment">afterTick</option> * <option name="charting.axisLabelsX.minorLabelStyle.margin">(3,3,2,2)</option> <option name="charting.axisLabelsX.minorLabelStyle.alignmentX">0</option> <option name="charting.axisLabelsX.minorLabelAlignment">afterTick</option> *

This sets up a variety of parameters for numeric x-axis labels. It sets the small and large tick size in pixels, defines the x-axis margins, and gives the labels an alignment that places them after their corresponding tick mark. It also indicates that the major unit labels for the numeric x-axis should be rounded to the nearest integer. Also used by layout.axisLabels.* See the "Layout properties" discussion for more details. Axis label properties all axis labels

The following properties apply to all three axis label types. All axis label types inherit properties fro Property name Value type
string

Definition

placement

Controls the placement of the axis labels within a cartesian chart la values are left, right, top, and bottom.

346

axis

axis

Indicates the axis to label. For example, to indicate the y-axis, use: name="charting.axislabelsY.axis"> @axisY</option>

axisBrush

brush

Indicates the brush to use to paint the line that runs along the lengt (perpendicular to the tick marks). For example, to use the predefine axisLineBrush element, which provides the standard ax properties: <option name="charting.axisLabelsX.axisBrush">@axisLineBru

axisVisibility

string

Determines whether or not the axis line is visible or not. Valid value hide

majorTickBrush

brush

Indicates the brush to use to paint the major axis tick marks. For ex the predefined axisLineBrush element, which provides the line properties: <option name="charting.axisLabelsX.majorTickBrush"> @axisLineBrush</option> The size of the major tick marks in pixels.

majorTickSize

number

Determines whether the major tick marks are visible or not. Valid va majorTickVisibility string

(shows a major tick only if the corresponding label is vis (forces all major ticks to be visible, regardless of label vi hide (forces all major ticks to be hidden).

minorTickBrush

brush

Indicates the brush to use to paint the minor axis tick marks. For ex the predefined axisLineBrush element, which provides the line properties: <option name="charting.axisLabelsX.minorTickBrush"> @axisLineBrush</option> The size of the minor tick marks in pixels.

minorTickSize

number

Determines whether the minor tick marks are visible or not. Valid va minorTickVisibility string

(shows a minor tick only if the corresponding label is vis (forces all minor ticks to be visible, regardless of label vi hide (forces all minor ticks to be hidden).
Applies properties to major tick mark labels.

majorLabelStyle

style<textBlock>

347

majorLabelAlignment

string

Controls the alignment of the major labels relative to their correspo Valid values are atTick, afterTick, and beforeTick.

Controls the visibility of the major tick mark labels. Valid values are

majorLabelVisibility

string

(automatically shows or hides individual major labels to readability in the available space without overlapping), s major labels to be visible even when there isn't enough display them without overlapping), and hide (hides all m Set majorLabelVisibility to show if you always want la appear, even when a large number of results are display

minorLabelStyle

style<textBlock>

Applies properties to minor tick mark labels.

minorLabelAlignment

string

Controls the alignment of the minor labels relative to their correspo Valid values are atTick, afterTick, and beforeTick.

Controls the visibility of the minor tick mark labels. Valid values are

minorLabelVisibility

string

(automatically shows or hides individual minor labels to readability in the available space without overlapping), s minor labels to be visible even when there isn't enough display them without overlapping), and hide (hides all m Set minorLabelVisibility to show if you always want la appear, even when a large number of results are display

extendsAxisRange

boolean

Determines whether the range of the axis should be extended to sn major tick marks.

Category axis label properties There are currently no properties that are specific to this axis label type. Numeric axis label properties Numeric axis labels The numeric axis labels place labels for a corresponding numeric axis. The following properties are specific to the numeric axis label type.
348

Value Property name type

Definition

Supported Default by JSChart?

majorUnit

number

The spacing unit at which to place major tick marks along the numeric axis. By default, this auto value is automatically calculated based on the scale of

Yes

the related axis.

The spacing at which to place minor tick marks. Possible values vary depending on the scale you are working auto with. By default, this value is automatically calculated based on the scale of

minorUnit

number

No

the related axis.

Determines whether the major unit is boolean true relative to the scale of the numeric axis. boolean Determines false whether the minor unit is relative to the scale of the

scaleMajorUnit

No

scaleMinorUnit

No

349

numeric axis. (The minor unit of a numeric axis is usually relative to the major unit.) Indicates whether the major unit boolean should be rounded to the nearest integer.

integerUnits

false

Yes

Time axis label properties Time axis labels The time axis labels place labels for a corresponding time axis. The following properties are specific to the time axis label type. Property name Value type Definition Default
By default timeZone The time zone in which labels are computed. Can be: 1) the character z or Z, indicating UTC time

Supported by JSChart?

timeZone

(constant offset 0); or 2) A numeric value, indicating the time zone offset in seconds, or 3) a string in serialized time zone format, timeZone indicating the offset changes for the time zone on the Splunk server. Any other value is interpreted as the local time in whatever browser is being used to view the chart. For more information see the zoneinfo (TZ) database.

is assigned a serialized string from the Splunk server that contains all No the information about where the time zone offset changes occur.
auto No

majorUnit

duration

Determines the spacing at which to place major tick marks, in terms of duration. By default this is determined automatically. To define a specific spacing, use an ISO-8601 duration string in the following format: PnYnMnDTnHnMnS. Note:

350

Splunk will ignore your setting for this property unless you force the chart to display in Flash. To do this, add a line for another unsupported property such as scaleX to your chart definition. This forces the chart to display in Flash with your majorUnit setting displaying appropriately along the time axis. Example: You want to force the time axis to be marked in 1 hour increments. If you just put in <option
name="charting.axisLabelsX.majorUnit"> P0Y0M0DT1H0M0S</option>, Splunk will ignore the setting. But if you add <option name="charting.scaleX>1</option>,

Splunk will be forced to display the chart in Flash with the desired 1 hour unit setting on the X axis.
Determines the spacing at which to place minor tick marks, in terms of duration. By default this is determined automatically. To define a specific spacing, use an ISO-8601 duration string in the following format: PnYnMnDTnHnMnS

minorUnit

duration

auto

No

Axis title
Usage: charting.axisTitleX.* and charting.axisTitleX.* The axisTitle element is designed to enable the placement of the axis title within a cartesian (dual axis) chart layout. Note: While axisTitle is mainly to be used for Cartesian charts, you could create an axisTitle element and place it within the layout.axisTitles list for a single-axis chart or pie chart. Values axisTitle Example
<option name="charting.axisTitleX.text">Source type</option> <option name="charting.axisTitleY.text">KB indexed</option>

351

Also used by layout.axisTitlesX.*, layout.axisTitlesY.* See the "Layout properties" discussion for more details. Properties All axis titles The axis title element inherits properties from textBlock and has one additional property: placement. Property name Supported Value Definition Default by type JSChart?
Determines the placement of the axis title within a cartesian (dual axis) bottom chart layout. Valid values are left, right, top,

placement

string

No

and
bottom.

Grid lines
Usage: charting.gridLinesX.* and charting.gridLinesY.* The gridLines element is used by cartesian (dual axis) charts to control the display and appearance of chart grid lines, which correspond to axis tick marks from axis labels and extend across the span of the chart. Values gridLines

352

Also used by layout.gridLines.* See the "Layout properties" discussion for more details. Properties All grid lines

Grid lines inherit properties from layoutSprite and have the following additional properties as well Property name Value type Definition Default

Suppor by JSChar
No

axisLabels

Indicates the axis labels for which to generate the grid axisLabels lines. Axis labels should use the @ sign to reference the axis labels. For example: @myAxisX.

Not assigned.

Indicates the brush to use to paint the major grid lines See the (corresponds to the major tick marks). For example, to use brush the predefined gridLineBrush element, which majorLineBrush

brush

section for provides the standard grid line brush properties: properties No <option and name="charting.gridLinesY.majorLineBrush"> defaults. @gridLineBrush</option>
Indicates the brush to use to paint the minor grid lines See the (corresponds to the minor tick marks). For example, to use brush the predefined gridLineBrush element, which

minorLineBrush

brush

section for provides the standard grid line brush properties: properties No <option and name="charting.gridLinesY.minorLineBrush"> defaults. @gridLineBrush</option>
Determines whether major grid lines are visible. Determines whether minor grid lines are visible. true false

showMajorLines showMinorLines

boolean boolean

Yes Yes

Tooltip properties
This topic covers the properties for the tooltip element.

353

Tooltip
Usage: charting.tooltip.content.* Tooltips are the visual elements that appear during chart mouse over, displaying information about different aspects of the chart. For example, in a bar chart, tooltips appear when you roll your mouse pointer over a specific bar. The tooltip presents information about the data represented by that bar, such as the period of time it spans or the number of events counted in it, along with a color swatch. Similarly, a tooltip for a pie chart wedge displays the field value and the percentage of the whole that the wedge represents, along with a color swatch. Example This changes the maximum width of a chart tooltip to 500 pixels:
<option name="charting.tooltip.maximumWidth">500</option> The maximumWidth property is inherited from the layoutSprite object.

Meanwhile, these properties configure the manner in which the tooltip content displays, from its internal margins to the font and style of the text:

<option name="charting.tooltip.content.margin">(5,5,2,2)</option> <option name="charting.tooltip.content.swatchStyle.margin">(0,5,0,0)</option> <option name="charting.tooltip.content.swatchStyle.height">10</option> <option name="charting.tooltip.content.fieldStyle.defaultTextFormat">{font:@fontFace,size:@fontS <option name="charting.tooltip.content.fieldStyle.margin">(0,5,0,0)</option> <option name="charting.tooltip.content.valueStyle.defaultTextFormat">{font:@fontFace,size:@fontS @fontFace and @fontSize are references to defaultTextFormat properties that

have been previously defined. Tooltip properties element is an interactive control that displays content such as field names, values, and percentages--as well as a swatch--that correspond to the chart data sprite underneath the mouse pointer. Inherits properties from layoutSprite.
The tooltip

Property name

Value type

Definition

Default

Supported by JSChart?

354

backgroundBrush

brush

Indicates the brush to use for painting the tooltip background. Use the @ symbol to

No reference an section for prexisting brush, like properties so: and defaults. @myBackgroundBrush See the layoutSprite

No brush assigned. See the brush

content.swatchStyle

style<layoutSprite>

The properties to apply to the swatch sprite.

section for No properties and defaults.

See the textBlock

content.fieldStyle

style<textBlock>

Affects the appearance of the field label text.

for No properties and defaults.

See the textBlock

content.valueStyle

style<textBlock>

Affects the appearance of the value label text.

section for No properties and defaults.

Font, color, brush, shape and related palette properties

This section covers properties for basic font, color, brush, shape, and palettes, which are used to design the appearance of the charting objects. For example, you use brushes to determine the line thickness of the lines in line charts, set up gradient fills for area charts, and paint pie chart wedges with images rather than colors. Splunk delivers a set of pre-configured brushes, color palettes, and brush palettes with different standardized settings. You can adjust those settings or define brushes and palettes of your own and reference them. For example, the predefined lineBrushPalette element inherits all of its properties from the brushPalette element, but the values of those properties have been set to paint a standardized line in Splunk line and area charts. The predefined areaBrushPalette element, on the other hand also inherits its properties from the brushPalette but has been designed to paint a standardized
355

fill for area charts. When you set up a line chart, the lineBrushPalette is associated with it by default. But what if you want to use a line brush palette with settings that are different than the standard one? You can create a new one--that you might call myLineBrushPalette--and then reference it like so:

<option name="charting.chart">line</option> <option name="charting.chart.lineBrushPalette">@myLineBrushPalette</option>

For more information about designing custom brushes and palettes, see "Advanced charting options," in this manual.

Supported by JSChart?
It's important to note that currently none of the font, color, brush, shape, and related palette properties are supported by the JSChart module. For more information, see the "Advanced charting options" topic in this manual.

Font and color

Usage: charting.fontFace, charting.foregroundColor, and so on. Use the font and color properties to define the baseline font and color aspects of your chart. Examples Setting font properties:

<option name="charting.fontFace">_sans</option> <option name="charting.fontSize">11</option> <option name="charting.fontColor">0x000000</option>

Setting color properties:

<option name="charting.foregroundColor">0x000000</option> <option name="charting.backgroundColor">0xFFFFFF</option> <option name="charting.seriesColors">[0x6CB8CA,0xFAC61D,0xD85E3D,0x956E96, 0xF7912C,0x9AC23C,0x998C55,0xDD87B0,0x5479AF,0xE0A93B,0x6B8930,0xA04558, 0xA7D4DF,0xFCDD77,0xE89E8B,0xBFA8C0,0xFABD80,0xC2DA8A,0xC2BA99,0xEBB7D0, 0x98AFCF,0xECCB89,0xA6B883,0xC68F9B,0x416E79,0x967711,0x823825,0x59425A,

356

0x94571A,0x5C7424,0x5C5433,0x85516A,0x324969,0x866523,0x40521D,0x602935]</option>

Note: If you want to apply static colors to specific fields we suggest you use the fieldColors property (see documentation of the fields color palette, below). Properties Font properties The following properties enable you to set basic font characteristics. Property name Value type Definition
Identifies the default font for the chart. Determines the type of font used for the text. Valid values are _sans (for the

Default

default sans-serif font), _serif (for the default serif font) and
_typewriter

fontFace

string

(for the default monospaced font). _sans Additionally you can assign popular fonts by name, such as verdanna--if the font is unavailable the browser will use the machine's default font, which is usually something like Times New Roman.

357

fontSize

number

Identifies the font size in pixels. For example, choose 11 14 to have a 14px

font size.
fontColor number Uses a hexadecimal value 0x000000 to define the font color.

(black)

Color properties The following properties enable you to set basic color characteristics.
Used to color the foreground elements that aren't fonts or chart series elements (which are colored with fontColor and seriesColors

foregroundColor

number

properties, respectively. 0x000000 (black) Foreground elements include axis lines, grid lines, or the lines for pie chart labels. Uses a hexadecimal value to define the color.
Controls the color of the background of the flash chart 0xFFFFFF area. Uses a hexadecimal value to define the color.

backgroundColor

number

(white)

seriesColors

array<number> Uses an array of hexadecimal values to define the colors of chart series (surrounded by

[0x6CB8CA,0xFAC61D,0xD85E3D,0x956E96, 0xF7912C,0x9AC23C,0x998C55,0xDD87B0, 0x5479AF,0xE0A93B,0x6B8930,0xA04558, 0xA7D4DF,0xFCDD77,0xE89E8B,0xBFA8C0,

358

brackets and separated by commas, no spaces). See the Define series colors subtopic in the Charting configurations overview for more information.

0xFABD80,0xC2DA8A,0xC2BA99,0xEBB7D0, 0x98AFCF,0xECCB89,0xA6B883,0xC68F9B, 0x416E79,0x967711,0x823825,0x59425A, 0x94571A,0x5C7424,0x5C5433,0x85516A, 0x324969,0x866523,0x40521D,0x602935]

Note: The
masterLegend

parameter influences series color mappings made with

seriesColors.

For more information, see the Chart colors subtopic of the "Advanced charting options" topic, in this manual. If you want to apply static colors to specific fields we suggest you use the
fieldColors

property (see documentation of the fields color palette, below).

359

Brush
Usage: charting.backgroundBrush.*, charting.axisLineBrush.*, and so on. You can use brush properties to define a new brush type, or to change the defaults of an existing brush type that you're applying to a chart. Values The different kinds of brushes that you can apply include: cameraFill dashedStroke gradientFill gradientStroke group imageFill movieFill solidFill solidStroke videoFill Examples Applying the solidFill brush to the backgroundBrush brush type and setting it so that it has a solid red fill with 50% transparency:

<option name="charting.backgroundBrush">solidFill</option> <option name="charting.backgroundBrush.color">0xFF0000</option> <option name="charting.backgroundBrush.alpha">0.5</option>

Setting up a radial gradient fill in the background:

<option name="charting.backgroundBrush">gradientFill</option> <option name="charting.backgroundBrush.type">radial</option> <option name="charting.backgroundBrush.colors">[0xFF0000,0x0000FF]</option> <option name="charting.backgroundBrush.alphas">[1,1]</option> <option name="charting.backgroundBrush.ratios">[0,255]</option> <option name="charting.backgroundBrush.focalPointRatio>.5</option>

Used by The following brush types inherit their properties from brush: backgroundBrush - paints the chart background
360

chart objects: innerFillBrush - paints the inner fill of range marker charts labelLineBrush - paints pie chart and ratio bar chart label lines lineBrush - paints range marker and value marker chart lines outerFillBrush - paints the outer fill of range marker charts axis label objects: axisBrush - paints the line that runs the length of the axis majorTickBrush - paints the major tick marks along the axis minorTickBrush - paints the minor tick marks along the axis grid line objects: majorLineBrush - paints the major grid lines (corresponds with major tick marks) minorLineBrush - paints the minor grid lines (corresponds with minor tick marks) Properties Camera fill brush The cameraFill brush paints with live video captured from a computer-mounted camera. Property name
cameraIndex

Value type
number

Definition

Default

The zero-based index of the camera to use if auto multiple cameras are available. Determines whether the image should be repeated when it is tiled. Go here for more information about the repeat

repeat

boolean

false

parameter.
smooth boolean Determines whether the image is smoothed when it is scaled. Go here for more information false

361

about the repeat

parameter.
Determines how the image tile is stretched relative to the drawing bounds. Valid values are none, fill, fill uniform, uniformToFill, uniformToWidth

stretchMode

string

and
uniformToHeight. The horizontal alignment of the image tile within the drawing bounds. Typical values are between 0

alignmentX

number

0.5

(centered)

(left-aligned) and 1 (right-aligned).

The vertical alignment of the image tile within the drawing bounds. Typical values are 0.5 between 0 (centered)

alignmentY

number

(top-aligned) and
1

(bottom-aligned).
tileTransform matrix Defines the transformation matrix to apply to the image tile. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). No default defined. You must set this value

The resulting transformation

362

matrix object is a 3x3 matrix with the following contents:

[ a c tx ] [ b d ty ] [ 0 0 1 ] Defines the transformation matrix to apply to the final rendered fill. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis without spaces, corresponding to a, b, c, d, tx, and ty respectively: No default (a,b,c,d,tx,ty). defined.

renderTransform

matrix

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Determines whether the image tile should be scaled to the drawing boundaries (true) or to the

fitToDrawing

boolean

false

boundaries of the entire graphics area (false). Dashed stroke brush The dashedStroke brush paints with dashed lines. Go here for more information about dashed stroke parameters.
363

dashSize

number

Determines the size of 4 each dash in pixels. Sets the size of the spaces between each 4 dash in pixels. Determines the thickness of the stroke in pixels. A value of 0 0

dashSpacing

number

thickness

number

indicates hairline thickness.

color number Determines the hexadecimal color of the stroke. Sets the alpha transparency of the stroke. Valid values are between 0 0x000000

(black)

alpha

number

(transparent) and 1 (opaque).

pixelHinting boolean Indicates whether the stroke should be hinted to full pixels. Identifies the stroke scaling mode. Valid values are normal, none, horizontal, and vertical. Determines the type of stroke end caps to use. Valid values are none, round, and square. Determines the type of joints to use at stroke angles. Valid values are miter, round, and bevel. false

scaleMode

string

normal

caps

string

round

joints

string

round

miterLimit

number

Determines the limit at 3 which miter joints

are cut off. The value expresses a factor of the stroke thickness (see
364

above). It is measured in pixels. Gradient fill brush The gradientFill brush paints fills with a color gradient. For more information about the gradient fill brush and its Flash parameters, go here.
Indicates the type of gradient to use. Valid values are linear

type

string

(where color changes uniformly in a linear direction, vertically, horizontally, or linear diagonally) and radial (where where color changes in a circular fashion in all directions from a central point to the gradient edge) .

colors

array<number> Defines the list of No default hexadecimal color defined. values to use in the gradient. Must be comma-delimited and within brackets.

Note: The colors, alphas, and ratios properties are used simultaneously to define how the gradient should be drawn. If you do not give values to

365

these properties a solid black fill will be drawn. If you define two colors values, you must also define two corresponding values each for the alphas and
ratios

parameters.
alphas array<number> Provides the list of alpha transparency values corresponding to the colors list. No defaults.

Valid values are between 0 (transparent) and 1 (opaque). Must be comma-delimited and within brackets. Note: The colors, alphas, and ratios properties are used simultaneously to define how the gradient should be drawn. If you do not give values to these properties a solid black fill will be drawn. If you define two alphas values, you must also define two corresponding values each for the colors and
ratios

366

parameters.
Provides the list of color distribution ratios corresponding to the colors list

(see above). The ratios define the percentage of the

gradientWidth

where the color is sampled at 100%. Valid values are between 0 (left) and 255 (right). Must be comma-delimited and within brackets. Note: The colors, No default array<number> alphas, and defined. ratios properites are used simultaneously to define how the gradient should be drawn. If you do not give values to these properties a solid black fill will be drawn. If you define two ratios values, you must also define two corresponding values each for the colors and
alphas

ratios

parameters.
spreadMethod string Indicates the method pad to use for spreading the gradient when it is tiled. Valid values are

367

(use the terminal colors of the gradient to fill the remainder of the region), reflect (reflect the gradient pattern start-to-end, end-to-start, start-to-end, and so on continuously until the region is filled), and repeat (repeat the gradient pattern start-to-end, start-to-end, start-to-end until the region is filled).
pad Determines the method to use for interpolating between the colors in the rgb gradient. Valid values are rgb and linearRGB. Determines the location of the gradient focal point. Valid values are between -1 (left) and 1 (right). Determines the width of the gradient tile in pixels.

interpolationMethod

string

focalPointRatio

number

(center)

gradientWidth

number

100

gradientHeight stretchMode

number string

Determines the height of the gradient tile in 100 pixels. Determines the manner in which the gradient tile is stretched relative to fill

368

the drawing bounds. Valid values are none, fill, uniform, uniformToFill,

and
uniformToWidth,

and
uniformToHeight. Sets the horizontal alignment of the gradient tile within the drawing bounds. 0.5 Typical values are (centered) between 0 (left-aligned) and 1

alignmentX

number

(right-aligned).
Sets the vertical alignment of the gradient tile within the drawing bounds. 0.5 Typical values are (centered) between 0

alignmentY

number

(top-aligned) and
1

(bottom-aligned).
tileTransform matrix Defines the No default transformation matrix defined. to apply to the gradient tile. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty).

The resulting transformation matrix object is a 3x3 matrix with

369

the following contents:

[ a c tx ] [ b d ty ] [ 0 0 1 ] Defines the transformation matrix to apply to the final rendered fill. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). No default defined.

renderTransform

matrix

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Determines whether the gradient tile should be scaled to the drawing boundaries (true) or false

fitToDrawing

boolean

to the boundaries of the entire graphics area (false)

Gradient stroke brush The gradientStroke brush paints strokes with a color gradient. For more details on the gradient stroke brush and its brush Flash parameters, go here (for information about gradients) and here (for information about line parameters).
370

Indicates the type of gradient to use. Valid values are linear

type

string

(where color changes uniformly in a linear direction, vertically, horizontally, or linear diagonally) and radial (where where color changes in a circular fashion in all directions from a central point to the gradient edge) .

colors

The list of hexadecimal color values to use in the No default array<number> gradient. Must be defined. comma-delimited and within brackets. The list of alpha transparency values corresponding to the colors list. Valid

alphas

values are between 0 No default array<number> (transparent) and defined. 1 (opaque). Must be comma-delimited and bracket-enclosed.
array<number> The list of color distribution ratios corresponding to the colors list (see No default defined.

ratios

above). The ratios define the percentage of the

gradientWidth

371

where the color is sampled at 100%. Valid values are between 0 (left) and 255 (right). Must be comma-delimited and bracket-enclosed.
The method to use for spreading the gradient when it is tiled. Valid values are pad (use

spreadMethod

string

the terminal colors of the gradient to fill the remainder of the stroke), reflect (reflect the gradient pattern pad start-to-end, end-to-start, start-to-end, and so on continuously), and repeat (repeat the gradient pattern start-to-end, start-to-end, start-to-end).
Determines the method to use for interpolating between the colors in the rgb gradient. Valid values are rgb and linearRGB. Determines the location of the gradient focal point. Valid values are between -1 (left) and 1 (right).

interpolationMethod

string

focalPointRatio

number

(center)

372

thickness

number

Determines the stroke thickness in pixels. A 0 value of 0 indicates

hairline thickness.
pixelHinting boolean Indicates whether the stroke should be hinted to full pixels. Identifies the stroke scaling mode. Valid values are normal, none, horizontal, and vertical. false

scaleMode

string

normal

caps

string

Determines the type of caps to use at stroke ends. Valid round values are none, round, and square. Determines the type of joints to use at stroke angles. Valid values are miter, round, and bevel. Determines the limit at which miter joints

joints

string

round

miterLimit

number

are cut off. The value expresses a factor of the stroke 3 thickness (see above). It is measured in pixels.
Determines the width of the gradient tile in pixels. 100

gradientWidth

number

gradientHeight stretchMode

number string

Determines the height of the gradient tile in 100 pixels. Determines the manner in which the gradient tile is stretched relative to the drawing bounds. Valid values are none, fill, fill

373

uniform, uniformToFill,

and
uniformToWidth,

and
uniformToHeight. Sets the horizontal alignment of the gradient tile within the drawing bounds. 0.5 Typical values are (centered) between 0 (left-aligned) and 1

alignmentX

number

(right-aligned).
Sets the vertical alignment of the gradient tile within the drawing bounds. 0.5 Typical values are (centered) between 0

alignmentY

number

(top-aligned) and
1

(bottom-aligned).
tileTransform matrix Defines the No default transformation matrix defined. to apply to the gradient tile. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty).

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ]

374

[ b d ty ] [ 0 0 1 ] Defines the transformation matrix to apply to the final rendered fill. This is represented as a comma-delimited and bracket-enclosed list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: No default (a,b,c,d,tx,ty). defined.

renderTransform

matrix

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Determines whether the gradient tile should be scaled to the drawing boundaries (true) or false

fitToDrawing

boolean

to the boundaries of the entire graphics area (false)

Group brush The group brush paints with a set of layered brushes simultaneously. For example, you could add outlines around the columns of a column chart by using a group brush consisting of a solidStroke brush on top of a gradientFill brush. Or you could paint with a semi-transparent gradientFill brush on top of an imageFill brush. (Note: To apply these effects to the series in a chart, however, you
375

eventually have to use a brush palette. Depending on what your ultimate goal is, you could put a bunch of custom defined group brushes into a list brush palette, or it may be easier to define a couple of brush palettes and put them into a group brush palette.)
brushes array<brush> The list of brushes to paint with. Must be No default comma-delimited and defined. bracket-enclosed.

Image fill brush The imageFill brush fills an area with a JPG, PNG, or GIF image file.
source string The URL of the fill image. No default defined.

repeat

boolean

Indicates whether the image should be repeated when tiled. false Go here for more information about the repeat parameter. Indicates whether the image should be smoothed when it is scaled. Go here for more information about the smooth

smooth

boolean

false

parameter.
Determines the manner in which the image tile is stretched relative to the drawing bounds. Valid values are none, fill, fill uniform, uniformToFill,

stretchMode

string

and
uniformToWidth,

and
uniformToHeight. alignmentX number Sets the horizontal alignment of the image tile within the drawing bounds. Typical values are between 0 0.5

(centered)

376

(left-aligned) and 1 (right-aligned).

Sets the vertical alignment of the image tile within the drawing bounds. Typical values are between 0

alignmentY

number

0.5

(centered)

(top-aligned) and
1

(bottom-aligned).
Defines the transformation matrix to apply to the image tile. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). No default defined.

tileTransform

matrix

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] renderTransform matrix Defines the No default transformation matrix defined. to apply to the final rendered fill. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis corresponding to a, b, c, d, tx, and ty

377

respectively: (a,b,c,d,tx,ty).

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Determines whether the image tile should be scaled to the drawing boundaries (true) or to the

fitToDrawing

boolean

false

boundaries of the entire graphics area (false) Movie fill brush The movieFill brush fills an area with a Flash movie (SWF).
source string The URL of the Flash movie. No default defined.

repeat

boolean

Indicates whether the Flash movie should be repeated when it is tiled. Go here for false more information about the repeat

parameter.
Indicates whether the Flash movie should be smoothed when it is scaled. Go here for more information about the smooth

smooth

boolean

false

parameter.
stretchMode string Determines the manner in which the Flash movie tile is stretched relative to fill

378

the drawing bounds. Valid values are none, fill, uniform, uniformToFill,

and
uniformToWidth,

and
uniformToHeight. Sets the horizontal alignment of the Flash movie tile within the drawing bounds. 0.5 Typical values are (centered) between 0 (left-aligned) and 1

alignmentX

number

(right-aligned).
Sets the vertical alignment of the Flash movie tile within the drawing bounds. 0.5 Typical values are (centered) between 0

alignmentY

number

(top-aligned) and
1

(bottom-aligned).
tileTransform matrix Defines the No default transformation matrix defined. to apply to the Flash movie tile. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty).

The resulting transformation matrix object is a 3x3 matrix with

379

the following contents:

[ a c tx ] [ b d ty ] [ 0 0 1 ] Defines the transformation matrix to apply to the final rendered fill. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). No default defined.

renderTransform

matrix

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Determines whether the Flash movie tile should be scaled to the drawing boundaries (true) or false

fitToDrawing

boolean

to the boundaries of the entire graphics area (false)

Solid fill brush The solidFill brush fills an area with a solid color.
color number The hexadecimal color of the fill. 0x000000

(black)

380

alpha

number

The alpha transparency of the fill. Valid values are between 0

(transparent) and 1 (opaque). Solid stroke brush The solidStroke brush paints strokes with a solid color. Go here for more information about solid stroke parameters.
number Sets the thickness of the stroke in pixels. A value of 0 indicates

thickness

hairline thickness.
color number Determines the hexadecimal color of the stroke brush. The alpha transparency of the fill. Valid values are between 0 0x000000

(black)

alpha

number

(transparent) and 1 (opaque).

pixelHinting boolean Indicates whether the stroke should be hinted to full pixels. Identifies the stroke scaling mode. Valid values are normal, none, horizontal, and vertical. Determines the type of stroke end caps to use. Valid values are none, round, and square. Determines the type of joints to use at stroke angles. Valid values are miter, round, and bevel. false

scaleMode

string

normal

caps

string

round

joints

string

round

miterLimit

number

Determines the limit at 3 which miter joints

381

are cut off. The value expresses a factor of the stroke thickness (see above). It is measured in pixels. Video fill brush The videoFill brush paints fills with video. It supports video files derived from the standard MPEG-4 format, including F4V, MP4, M4A, MOV, MP4V, 3GP, and 3G2 (if they contain H.264 video and/or HEAAC v2 encoded audio.
A Flash Player security limitation requires static video The URL of the video files to be you want to paint with. located in the same directory as the SWF file or in a subdirectory. Indicates whether the video should be repeated when it is tiled. Go here for more information about the repeat

source

string

repeat

boolean

false

parameter.
Indicates whether the video should be smoothed when it is scaled. Go here for more information about the smooth

smooth

boolean

false

parameter.
stretchMode string Determines the fill manner in which the video is stretched relative to the drawing bounds. Valid values

382

are none, fill, uniform, uniformToFill,

and
uniformToWidth,

and
uniformToHeight. Sets the horizontal alignment of the video tile within the drawing 0.5 bounds. Typical values are between 0 (centered) (left-aligned) and 1

alignmentX

number

(right-aligned).
Sets the vertical alignment of the video tile within the drawing bounds. Typical 0.5 values are between 0 (centered)

alignmentY

number

(top-aligned) and
1

(bottom-aligned).
tileTransform matrix Defines the No default transformation matrix defined. to apply to the video tile. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty).

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ]

383

[ 0 0 1 ] Defines the transformation matrix to apply to the final rendered video fill. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). No default defined.

renderTransform

matrix

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Determines whether the video tile should be scaled to the drawing boundaries (true) or to the

fitToDrawing

boolean

false

boundaries of the entire graphics area (false)

Color palette
Usage: charting.colorPalette.*, charting.colorPaletteDark.*, and so on. Use color palettes to control the colors used by brush palettes, which in turn are used to paint things like chart lines and series swatches in legends. For example, color palettes map colors to the series in a series index for a brush palette. If you associate a color palette to a brush palette, then the brush palette uses it to determine the color of each brush it generates. For example, when a brush palette generates a new brush for each series in a chart (to paint a line in a line
384

chart, fill a column in a column chart, or paint a swatch in a chart legend), it uses a color palette to determine the color of those lines, columns, and swatches. While you can define colors at the individual brush level, this method enables you to set up one set of colors for all of the brushes used in each chart of a dashboard. For example, a list color palette maps a series index directly to a color from a list of colors defined in the palette. By default, if the series index contains more items than the list of colors in the color palette, it is wrapped around to the beginning of the list, repeating the colors. If most of your charts present 10 series or less, then you might create a color palette with twice that number of specified colors so that colors are repeated very infrequently. However, the list color palette can be configured to interpolate between the colors in its list, instead of wrapping, to produce a range of colors that span over the total number of series in an index. With this setup, no colors will repeat. Values The different kinds of color palettes that you can apply include: brightness - modifies the brightness of colors generated from another color palette field - provides colors from a specified field-->color map list - generates brush colors from a specified list of colors random</color> - generates random colors Example This example provides properties for a new <code>list color palette called "myColorPalette," which interpolates between red, green, and blue:

<option name="charting.myColorPalette">list</option> <option name="charting.myColorPalette.colors">[0xFF0000,0x00FF00,0x0000FF]</option> <option name="charting.myColorPalette.interpolate">true</option>

This example references the "myColorPalette" defined above and creates a brighter version of it called "myBriteColorPalette":

<option name="charting.myBriteColorPalette">brightness</option> <option name="charting.myBriteColorPalette.colorPalette">@myColorPalette</option>

385

<option name="charting.myBriteColorPalette.brightness">0.5</option> And finally, this example uses the fieldColors parameter of the field color

palette type to map specific colors to specific fields:

<option name="charting.fieldColors">{"UserIP":0x3399CC, "Referrer_URL":0x00F66, "Browser":0xFFFF33,"SKU":0xFF0000}</option>

Note: If you want to apply static colors to specific fields we suggest you use the fieldColors property (see documentation of the fields color palette type, below). For more information about using fieldColors, see the Chart colors subtopic of the "Advanced charting options" topic, in this manual. Used by The following predefined palette types inherit their properties from colorPalette: colorPalette - defines the standard range of colors used for series indexes in Splunk. charts. colorPaletteDark - defines a range of colors that is the same as that of colorPalette, except darker. Properties Brightness The brightness color palette modifies the brightness of colors generated from another color palette. Property name Value type Definition Default
No default defined. See the colorPalette

colorPalette

colorPalette

References the color palette to use for base color generation. Reference an existing color palette with the @ symbol: @myColorPalette

element for properties and defaults. (no brightness change)

0

brightness

number

The brightness adjustment to apply to the base color. Valid values are between -1 (darkest) and 1 (brightest).

Field The field color palette provides colors from a specified color-->field map.
fieldColors map<number>

386

No default The map of hexadecimal color values to use for specified. each field. 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: {key1:value1,key2:value2,?,keyN:valueN}.

If a key or string value in the map contains any of these special characters - []{}(),:" - the special character should be surrounded by double quotes. Existing double quotes or backslashes should be escaped with a preceding backslash.

Note: For more information about using fieldColors, see the Chart colors subtopic of the "Advanced charting options" topic, in this manual.
defaultColorPalette

colorPalette

The color palette to use for unspecified fields.

No default specified.

List The list color palette contains the list of color values that should be applied to chart series.
colors The list of hexadecimal color values from which No default array<number> series colors are generated. Should be defined. comma-delimited, bracket-enclosed, without spaces. Determines whether Splunk should interpolate between the colors in the color list. When set true, Splunk will assign a series index for

to a

chart a continuous gradient of colors between each color in the list. So if you choose red and blue for the colors list and have more than two series false in your chart, the first series will be red, the last series will be blue, and the intervening series will be assigned colors on the gradient scale between red and blue. Set interpolate to false to use only the colors in the colors list without intermediate gradients, repeating colors if necessary.

interpolate

boolean

Random

387

The random color palette generates random colors.

minimumColor maximumColor number number The minimum (darkest) hexadecimal color value to generate. The maximum (lightest) hexadecimal color value to generate 0x000000 0xFFFFFF

Brush palette
Usage: charting.lineBrushPalette.*, charting.myBrushPalette.*, and so on. Use brush palettes to map a series index to a brush type. The brush palette then generates a brush for each series in that index when Splunk draws the chart. For example, if you are using a solidStroke brush to generate a line for a line chart, you would use a solidStroke brush palette to generate a solidStroke brush, which would in turn paint a solid color for the series (as determined by the associated color palette). Values The different kinds of brush palettes that you can apply include: field - provides brushes from a specified field->brush mapping. fieldImageFill generates imageFill brushes based on field name. gradientFill - generates gradientFill brushes gradientStroke - generates gradientStroke brushes group - generates group brushes from other brush palettes imageFill - generates imageFill brushes from a list of source URLs. listbp - provides brushes from a specified list solidFill - generates solidFill brushes solidStroke - generates solidStroke brushes Example This example creates a brush palette called myBrushPalette that produces solidFill brushes for an area chart. It references a predefined color palette that is essentially a darker version of the standard palette (colorPaletteDark) and arranges for the solidFill brushes that it generates to be partially transparent.

<option name="charting.myBrushPalette">solidFill</option> <option name="charting.myBrushPalette.colorPalette">@colorPaletteDark</option> <option name="charting.myBrushPalette.alpha">0.6</option>

388

Predefined brush palettes

The following predefined brush palettes inherit their root properties from brushPalette: fillBrushPalette - generates brushes for color fills in charts, such as the solidFill brush lineBrushPalette - generates brushes for lines in charts, such as the
solidStroke

barBrushPalette - generates brushes for bar charts You can create other brush palletes of your own. Properties Field brush palette The field brush palette provides brushes from a specified brush->field map. Property name Value type Definition
The map of brushes to use for each field. 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: {key1:value1,key2:value2,?,keyN:valueN}. fieldBrushes map<brush>

Default

If a key or string value in the map contains No defau any of these special characters - []{}(),:" specified - the special character should be surrounded by double quotes. Existing double quotes or backslashes should be escaped with a preceding backslash.

defaultBrushPalette

BrushPalette

No defau specified

Field image fill brush palette The fieldImageFill brush palette generates imageFill brushes based on field name.
fieldSources map<string> The explicit map of image source URLs for each field. The final URL used for each image is sourcePath + fieldSources[field] + sourceExtension. A map is a

No defau specified

comma-delimited list of key/value pairs, enclosed in curly braces. Keys are separated from their values by a colon.
389

Example:
{key1:value1,key2:value2,?,keyN:valueN}.

If a key or string value in the map contains any of these special characters - []{}(),:" - the special character should be surrounded by double quotes. Existing double quotes or backslashes should be escaped with a preceding backslash.
sourcePath sourceExtension <string> <string>

The common path shared among all image sources. No defau This value is prepended to all source URLs. specified

The common file extension shared among all image No defau sources. This value is appended to all source URLs. specified Indicates whether to use the field name itself to construct each image source URL. When set to true, any fields that have not been assigned an image source in fieldSources

useFieldAsSource

boolean

will use the URL-encoded field name as the false source. The final URL used for each image is sourcePath + fieldSources[field] + sourceExtension.
Indicates whether to repeat the image when it is tiled. Go here for more information about the repeat parameter. Indicates whether the image should be smoothed when it is scaled. Go here for more information about the smooth parameter. false

repeat

boolean

smooth

boolean

false

stretchMode

string

Indicates how to stretch the image tile relative to the drawing bounds. Valid values are none, fill, fill uniform, uniformToFill, uniformToWidth and uniformToHeight. The horizontal alignment of the image tile within the drawing bounds. Typical values are between 0 (left-aligned) and 1 (right-aligned). The vertical alignment of the image tile within the drawing bounds. Typical values are between 0 (top-aligned) and 1 (bottom-aligned). 0.5

alignmentX

number

(centere
0.5

alignmentY tileTransform

number matrix

(centere

Defines the transformation matrix to apply to the No defau image tile. This is represented as a comma-delimited defined. list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). This produces a 3x3

transformation matrix object.

390

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Defines the transformation matrix to apply to the final rendered fill. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). This

produces a 3x3 transformation matrix object.

renderTransform matrix

No defau defined.

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Determines whether the image tile should be scaled to the drawing boundaries (true) or to the

fitToDrawing

boolean

boundaries of the entire graphics area (false).

The brush palette to use for unspecified fields when useFieldAsSource is set to false.

defaultBrushPalette

brush palette

No defau specified

Gradient fill brush palette The gradientFill brush palette generates gradientFill brushes.
Indicates the type of gradient to use. Valid values are linear (where color changes uniformly type string

in a linear direction, vertically, horizontally, or diagonally) and radial (where where color changes in a circular fashion in all directions from a central point to the gradient edge) .
The list of color palettes from which gradient colors are retrieved. Must be comma-delimited without spaces, and within brackets.

linear

colorPalettes

array<colorPalette>

No defau defined. S the colorpa

elemen
391

info on parame and def

alphas

array<number>

The list of alpha transparency values corresponding to the colorPalettes list (see this parameter above). Valid values are between 0 No defau (transparent) and 1 (opaque). Must be

comma-delimited and bracket-enclosed.

The list of color distribution ratios corresponding to the colorPalettes list (see this parameter ratios array<number>

above). The ratios define the percentage of No defau the gradientWidth (see below) where the defined. color is sampled at 100%. Valid values are between 0 (left) and 255 (right). Must be comma-delimited and bracket-enclosed.
The method to use for spreading the gradient when it is tiled. Valid values are pad (use the terminal

spreadMethod

string

colors of the gradient to fill the remainder of the region), reflect (reflect the gradient pattern start-to-end, end-to-start, pad start-to-end, and so on continuously until the region is filled), and repeat (repeat the gradient pattern start-to-end, start-to-end, start-to-end until the region is filled).
Determines the method to use for interpolating between the colors in the gradient. Valid values are rgb and linearRGB. Determines the location of the gradient focal point. Valid values are between -1 (left) and 1 (right). Determines the width of the gradient tile in pixels. Determines the height of the gradient tile in pixels. Determines the manner in which the gradient tile is stretched relative to the drawing bounds. Valid values are none, fill, uniform, uniformToFill, and uniformToWidth, and uniformToHeight. rgb

interpolationMethod

string

focalPointRatio gradientWidth gradientHeight

number number number

(cente

100 100

stretchMode

string

fill

aligmentX alignmentY

number number

Sets the horizontal alignment of the gradient tile 0.5 within the drawing bounds. Typical values are (centere between 0 (left-aligned) and 1 (right-aligned). Sets the vertical alignment of the gradient tile within the drawing bounds. Typical values are between 0 0.5

(centere

392

(top-aligned) and 1 (bottom-aligned).

Defines the transformation matrix to apply to the gradient tile. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). tileTransform matrix

No defau defined.

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Defines the transformation matrix to apply to the final rendered fill. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). renderTransform matrix

No defau defined.

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Determines whether the gradient tile should be scaled to the drawing boundaries (true) or to

fitToDrawing

boolean

the

boundaries of the entire graphics area (false)

false

Gradient stroke brush palette The gradientStroke brush palette generates gradientStroke brushes.
Indicates the type of gradient to use. Valid values are linear (where color changes uniformly type string

in a linear direction, vertically, horizontally, or diagonally) and radial (where where color changes in a circular fashion in all directions from a central point to the gradient edge) .
The list of color palettes from which gradient colors are retrieved. Should be comma-delimited and bracket-enclosed.

linear

colorPalettes

array<colorPalette>

No defau defined. S the

393

colorPa

elemen parame and def

The list of alpha transparency values corresponding to the colorPalettes list. Valid values are between 0 (transparent) and 1 (opaque).

alphas

array<number>

Should be comma-delimited and bracket-enclosed.

The list of color distribution ratios corresponding to the colorPalettes list (see above). The ratios array<number>

No defau defined.

ratios define the percentage of the No defau gradientWidth where the color is sampled defined. at 100%. Valid values are between 0 (left) and 255 (right). Should be comma-delimited and bracket-enclosed.
The method to use for spreading the gradient when it is tiled. Valid values are pad (use the terminal

spreadMethod

string

colors of the gradient to fill the remainder of the stroke), reflect (reflect the gradient pad pattern start-to-end, end-to-start, start-to-end, and so on continuously), and repeat (repeat the gradient pattern start-to-end, start-to-end, start-to-end).
Determines the method to use for interpolating between the colors in the gradient. Valid values are rgb and linearRGB. Determines the location of the gradient focal point. Valid values are between -1 (left) and 1 (right). rgb

interpolationMethod

string

focalPointRatio thickness pixelHinting scaleMode caps joints miterLimit

number number boolean string string string number

(cente

Determines the stroke thickness in pixels. A value of 0 0 indicates hairline thickness. Indicates whether the stroke should be hinted to full pixels. Identifies the stroke scaling mode. Valid values are normal, none, horizontal, and vertical. Determines the type of caps to use at stroke ends. Valid values are none, round, and square. false normal round

Determines the type of joints to use at stroke angles. round Valid values are miter, round, and bevel. 3

394

joints are cut off. The value expresses a factor of the stroke thickness (see above). It is measured in pixels.
Determines the limit at which miter gradientWidth gradientHeight number number Determines the width of the gradient tile in pixels. Determines the height of the gradient tile in pixels. Determines the manner in which the gradient tile is stretched relative to the drawing bounds. Valid values are none, fill, uniform, uniformToFill, and uniformToWidth, and uniformToHeight. 100 100

stretchMode

string

fill

aligmentX

number

Sets the horizontal alignment of the gradient tile 0.5 within the drawing bounds. Typical values are (centere between 0 (left-aligned) and 1 (right-aligned). Sets the vertical alignment of the gradient tile within the drawing bounds. Typical values are between 0 (top-aligned) and 1 (bottom-aligned). Defines the transformation matrix to apply to the gradient tile. This is represented as a comma-delimited list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). 0.5

alignmentY

number

(centere

tileTransform

matrix

No defau defined.

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Defines the transformation matrix to apply to the final rendered fill. This is represented as a comma-delimited and bracket-enclosed list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). renderTransform matrix

No defau defined.

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ]

395

fitToDrawing

boolean

Determines whether the gradient tile should be scaled to the drawing boundaries (true) or to

the

boundaries of the entire graphics area (false).

false

Group brush palette The group brush palette generates brushes from other brush palettes.

brushPalettes

array<brushPalette>

The list of brush palettes from which to generate brushes for the group. Should be comma-delimited and bracket-enclosed.

No defau defined. S the brushPa

elemen properti and def

Image fill brush palette The imageFill brush palette generates imageFill brushes from a list of source URLs.
array<string> The list of image source URLs to choose from. The final URL used for each image is sourcePath+sources[i]. Should be

sources

No defau specified

comma-delimited and bracket-enclosed.

sourcePath string The common filepath shared among all image sources. The sourcePath value is prepended

to all source URLs.

repeat boolean Determines whether to repeat the image when it is tiled. Go here for more information about the repeat parameter. Determines whether to smooth the image when it is scaled.

No defau specified

false

smooth

boolean

false

stretchMode

string

The mode to use for stretching the tile relative to the drawing bounds. Valid values are none, fill, fill uniform, uniformToFill, uniformToWidth and uniformToHeight.

alignmentX

number

The horizontal alignment of the image tile within its 0.5 drawing bounds. Typical values are between 0 (left (centere aligned) and 1 (right aligned). Typical values are between 0

alignmentY tileTransform

number matrix

(bottom-aligned).

(top-aligned) and 1 0.5 (centere

Defines the transformation matrix to apply to the No defau gradient tile. This is represented as a defined. comma-delimited list of six numeric values enclosed

396

in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty).

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Defines the transformation matrix to apply to the final rendered fill. This is represented as a comma-delimited and bracket-enclosed list of six numeric values enclosed in a parenthesis, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). renderTransform matrix

No defau defined.

The resulting transformation matrix object is a 3x3 matrix with the following contents:
[ a c tx ] [ b d ty ] [ 0 0 1 ] Determines whether the image tile should be scaled to the drawing boundaries (true) or to the

fitToDrawing

Boolean

boundaries of the entire graphics area (false).

false

List brush palette The list brush palette provides brushes from a specified list.
brushes array<brush> The list of brushes to choose from. Should be comma-delimitedShould be comma-delimited and bracket-enclosed.

No defau defined.

Solid fill brush palette The solidFill brush palette generates solidFill brushes.

colorPalette

colorPalette

The color palette from which to retrieve the color of the fill.

No defau defined. S the colorPa

elemen parame and def

397

alpha

number

Determines the alpha transparency of the fill. Valid values are between 0 (transparent) and 1

(opaque). Solid stroke brush palette The solidStroke generates solidStroke brushes.
thickness number Defines the stroke thickness in pixels. A value of 0

indicates hairline thickness.

0x00000

(black) the
colorPalette

colorPalette

Determines the color palette from which to retrieve the colors of the generated solid stroke brushes.

colorPa

elemen parame and defaults

1

alpha

number

Determines the alpha transparency of the stroke. Valid values are between 0 (transparent) and 1

(opaque).
pixelHinting scaleMode caps joints boolean string string string Indicates whether the stroke should be hinted to full pixels. Identifies the stroke scaling mode. Valid values are normal, none, horizontal, and vertical. false normal

Determines the type of stroke end caps to use. Valid round values are none, round, and square. Determines the type of joints to use at stroke angles. round Valid values are miter, round, and bevel.

miterLimit

number

joints are cut off. The value expresses a factor of the 3 stroke thickness (see above). It is measured in pixels.
Determines the limit at which miter

Shape and shape palette

Usage: charting.shape.* You use shape properties to define shape objects for shape palettes, which are designed primarily to enable the assignation of specific shapes to chart markers. For example, you could arrange for each series in a line chart to have markers of different shapes. To do this you would define a list shape palette that sets up a specific shape object for each series, and then assign that to the
398

markerShapePalette

property.

Note: By default the shape properties on charts that can use them are not assigned any value. In the case of no value, most chart types use the rectangle shape. The exception is the bubble chart type, which uses the ellipse shape. Values diamond ellipse group line polygon rectangle triangle wedge Example This defines a shape palette that contains ellipses.

<option name="charting.ellipseShapePalette">list</option> <option name="charting.ellipseShapePalette.shapes">[ellipse]</option> This assigns the new ellipseShapePalette to a bubble chart.

<option name="charting.chart">bubble</option> <option name="charting.chart.bubbleShapePalette">@ellipseShapePalette</option> This creates an "upwards pointing" triangle defined as myShape:

<option <option <option <option

name="charting.myShape">triangle</option> name="charting.myShape.p1">(0.5,0)</option> name="charting.myShape.p2">(1,1)</option> name="charting.myShape.p3">(0,1)</option>

Used by objects are referenced in shapePalettes of the list type. Or, to put it another way, shapePalettes are populated by lists of shape objects.
shape

Shape properties Property name Value type Definition

399

Default

Diamond shape The diamond shape draws a diamond-shaped parallelogram.

snap boolean Indicates whether to snap the shape to whole false pixels.

Ellipse shape The ellipse shape draws an ellipse.

snap boolean Indicates whether to snap the shape to whole false pixels.

Group shape The group shape draws a group of shapes simultaneously.

The list of shapes to draw. Should be comma-delimited and bracket-enclosed.

shapes

If a key or string value in the map contains any of these special characters array<shape> []{}(),:" - the special character should be surrounded by double quotes. Existing double quotes or backslashes should be escaped with a preceding backslash.
array<brush> An optional list of brushes that correspond to each shape in the shapes list. Should

No default defined. See the shape

element for properties and defaults.

brushes

No default defined. See the brush

element for be comma-delimited information and about its bracket-enclosed. properties and
400

defaults. If a key or string value in the map contains any of these special characters []{}(),:" - the special character should be surrounded by double quotes. Existing double quotes or backslashes should be escaped with a preceding backslash. Line shape The line shape draws a line between two points.
Sets the starting point of the line in relative coordinates (0 to 1.

p1

point

Presented as a comma delimited list of two numeric (0,0.5) values (corresponding to x and y, respectively) enclosed in parenthesis.
Sets the ending point of the line in relative coordinates (0 to 1.

p2

point

Presented as a comma delimited list of two numeric (0,0.5) values (corresponding to x and y, respectively) enclosed in parenthesis.
Indicates whether to snap the shape to whole false pixels.

snap

boolean

401

Polygon shape The polygon shape draws a polygon.

A list of points that define the polygon. Each point is presented as a comma delimited list of two numeric values (corresponding to x and y, respectively) enclosed in parenthesis. These parenthesis-enclosed points should then be in a comma-delimited list and enclosed within brackets. These arrays can contain other items that are arrays or nested lists of values such as points, matrices, and so on. For example, you could use [(0,1),(1,1),(1,0)] vertices array<point>

to describe a set of vertices. If a key or string value in the map contains any of these special characters []{}(),:" - the special character should be surrounded by double quotes. Existing double quotes or backslashes should be escaped with a preceding backslash.

No default defined.

snap

boolean

Indicates whether to snap the shape to whole false pixels.

Rectangle shape The rectangle shape draws a rectangle.

402

snap

boolean

Indicates whether to snap the shape to whole false pixels.

Triangle shape The triangle shape draws a triangle.

Sets the first point of the triangle in relative coordinates (0 to 1.

p1

point

Presented as a comma delimited list of two numeric (0.5, 0) values (corresponding to x and y, respectively) enclosed in parenthesis, without spaces.
Sets the second point of the triangle in relative coordinates (0 to 1.

p2

point

Presented as a comma delimited list of two numeric (1,1) values (corresponding to x and y, respectively) enclosed in parenthesis, without spaces.
Sets the third point of the triangle in relative coordinates (0 to 1.

p3

point

Presented as a comma delimited list of two numeric (0,1) values (corresponding to x and y, respectively) enclosed in parenthesis, without spaces.
403

snap

boolean

Indicates whether to snap the shape to whole false pixels.

Wedge shape The wedge shape draws a portion of a circle.

startAngle number Indicates the start angle of the wedge in degrees. Indicates the arc (end) angle of the wedge in degrees. 0

arcAngle

number

360

snap

boolean

Indicates whether to snap the shape to whole false pixels.

Shape palette properties There are three types of shape palettes: field shape palettes group shape palettes, and list shape palettes. Property name Field shape palette The field shape palette provides shapes from a specified field-->shape mapping.
A field/shape mapping. 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: {key1:value1,key2:value2,?,keyN:valueN}. fieldShapes map<shapePalette>

Value type

Definition

Defau

If a key or string value in the map contains any of these special characters - []{}(),:" the special character should be surrounded by double quotes. Existing double quotes or backslashes should be escaped with a preceding backslash.
The shape palette to use for unspecified fields.

No def specifi

defaultShapePalette

shapePalette

No def specifi

Group shape palette The group shape palette generates group shapes from other shape palettes.
shapePalettes array<shapePalette>

The list of shape palettes from which to retrieve No def shapes for the group. Should be comma-delimited and define bracket-enclosed.

404

List shape palette The list shape provides shapes from a specified list.

shapes

array<shape>

The list of shapes to choose from. Should be comma-delimited and bracket-enclosed.

No def define more inform about types, param and defaul the sh

eleme table.

Advanced configuration - Layout and data table properties

Most basic charting requirements can be dealt with using the properties and elements discussed in the preceding chart reference topics. But advanced charting configurations (such as the creation of multiple charts that share axes) it's necessary to control the layout of elements and the routing of data.

Layout
Usage: charting.layout.* The layout element controls the layout of all visual chart elements. It consists of lists for the five main visual element types: charts, legends, axis labels, axis titles, and grid lines. Each list contains one or more references to predefined elements. By default, these lists are automatically configured depending on the value of the chart property. Example For example, if the chart property is set to a cartesian (dual axis) chart such as line, the default layout list configuration is:
405

<option name="charting.layout.charts">[@chart]</option> <option name="charting.layout.legends">[@legend]</option> <option name="charting.layout.axisLabels">[@axisLabelsX,@axisLabelsY]</option> <option name="charting.layout.axisTitles">[@axisTitleX,@axisTitleY]</option> <option name="charting.layout.gridLines">[@gridLinesX,@gridLinesY]</option>

In most cases you only need to change the default layout configuration if you are designing advanced chart layouts that use multiple charts and multiple, shared axes. For example, say you want to define two charts where one overlays the other so that they share the same x-axis, but have different y-axes (one on the left side of the chart, and another on the right side of the chart). You would start by defining two custom chart types, chart1 and chart2. We can configure the charts list to render those custom charts instead of the default chart:
<option name="charting.layout.charts">[@chart1,@chart2]</option>

More information about configuring multiple charts that share axes is coming soon. Also used by The layout element is not used by any other element. Layout properties
The layout

element controls the page layout for other visual chart elements. Value type Definition
A list of one or more chart element

Property name

Default

Supported by JSChart?

charts

array<chart>

references. Must be Varies by chart comma-delimited type. without spaces and set within brackets.
A list of one or more legends element Varies by legend type.

Depends on the chart

properties involved.

legends

array<legends>

Depends on the legends

references. Must be
406

properties involved.

comma-delimited without spaces and set within brackets.

A list of one or more axisLabels

axisLabels

element references (one for single-axis charts, two for cartesian charts, Varies by axis array<axisLabels> more for chart label type. layouts with shared axes). Must be comma-delimited without spaces and set within brackets.
A list of one or more axisTitle

Depends on the axisLabels

properties involved.

axisTitles

array<axisTitle>

element references (one for single-axis charts, two for cartesian charts, Varies by axis more for chart title reference. layouts with shared axes) Must be comma-delimited without spaces and set within brackets.
A list of one or more gridLines Varies by grid line reference.

Depends on the axisTitle

properties involved.

gridLines

array<gridLines>

element references. Must be comma-delimited without spaces and set within

407

Depends on the gridLines

properties involved.

brackets.
A comma-delimited list of four numeric values corresponding to left, right, top, and bottom, respectively) enclosed in parenthesis, without spaces. It is measured in pixels. Margins are almost always positive (0,10,10,0) values, but negative values can be used as well to "trim" away at the bounding box of an object, which can be useful to get labels or other text objects to appear to be more tightly packed together. This is a special switch that splits a multi-series chart into separate charts that are stacked from top to bottom, one for each series. It is false most applicable to area, bar, column, and line charts (it may produce confusing results with other chart types). A comma-delimited (0,0,5,5) list of four numeric values corresponding to left, right, top, and bottom, respectively) enclosed in parenthesis, without spaces. This is the margin that appears around each split-series chart when splitSeries = true (see

margin

margin

No

splitSeries

boolean

Yes

splitSeriesMargin

margin

No

above). By
408

default it places a five-pixel margin at the top and bottom of each chart in order to space them apart in their stack.

Data
Usage: charting.data.* When Splunk generates a chart it requires that the data that the chart is based upon be contained in a tabular format. Data tables organize reporting data into rows and columns that provide the x-axis values for single-axis chart types (such as range marker and value marker charts) and the x- and y-axis values for dual-axis chart types (such as bar, column, line, and area charts). The data element is used by all chart types. Values The data element has three possible values: results timeline view Example Sets up a chart that counts only the first 500 results and previews them.

<option name="charting.data">results</option> <option name="charting.data.count">500</option> <option name="charting.data.preview">true</option>

Also used by charting.chart.data.* See the chart subtopic for more information.

409

Results data table properties

The results

data table collects the results data from a search job. Value type Definition
string The search job ID. The offset of the first retrieved result.

Property name
jobID

Default
Not assigned

Supported by JSChart? Yes Yes

offset

number

count

number

The number of results to 1000 retrieve. Set 0 to

Yes

get all results.

The post-processing search to apply to the results, if necessary. Whether or not results are previewed. The order in which to apply the fieldShowList

search

string

Not assigned

Yes

preview

boolean

false

Yes

and
fieldListMode string fieldHideList hide_show

Yes

filters. Valid values are show_hide and hide_show.

fieldShowList The list of fields array<string> to explicitly show Not assigned in the results. The list of fields array<string> to explicitly hide from the results Not assigned

Yes

fieldHideList

Yes

410

Timeline data table properties The timeline data table collects the timeline data from a search job. Supported Property Value Definition Default by name type JSChart?
jobID string The search job ID. Not assigned

Yes

View data table properties data table collects a "view" (a subset, in other words) of data from another data table.
A view

Property Value name type

table datatable

Supported Definition Default by JSChart?

The table Not from which to assigned create a view

Yes

rows

The list of slices All rows indicating are which rows array<slice> of the table included to include by default.

Yes

in the view.

columns

The list of slices indicating which array<slice> columns from the table to

include in the view

All columns are included by default.

Yes

Advanced configuration - textBlock, layoutSprite, and sprite properties

411

textBlock, layoutSprite,

and sprite are core elements that control property sets that are inherited and/or used by elements that are higher up in the flash charting hierarchy. In most cases you probably won't need to change their defaults, but it really depends on what you hope to achieve with your charts.

Text block
Usage: charting.textBlock.* The textBlock element controls text display in legend and axis labels as well as axis title and message text. Values textBlock Used by The textBlock element is referred to by: pie chart ratioBar chart legend axisLabels In addition, the axisTitle element inherits all of its properties from textBlock save one (placement). Text block properties
The textBlock

element controls formatting properties for text in chart labels and Supported by JSChart?

messages Property name Value type Definition Default

text

string

The raw text to display. (For HTML formatted No text by No text, see the htmlText default.

property.)
textColor number No

412

The hexadecimal color value of the text.

0x000000

(black)

defaultTextFormat

The format to apply to the text. Arranged as a comma-delimited list of property name/value See textFormat pairs, enclosed in curly braces. For details (and below. defaults) see the "Text

No

format properties" subtopic, below.

string The HTML-formatted text to display. (For raw No text by No text, see the text default.

htmlText

property.)
Determines whether white space should be condensed for false HTML-formatted text. Used in conjunction with htmlText. Determines whether to wrap long lines of text to false the next line. Determines the manner in which inline text that overflows layout bounds is handled. Valid values are default, ellipsisMiddle

condenseWhite

boolean

No

wordWrap

boolean

No

overflowMode

string

(cuts off the text at the middle of the line, halfway to the Yes, but for layout boundary, and adds an ellipsis default legend items only. to indicate continuation), and ellipsisEnd (cuts off the overflowing text at the layout boundary and adds an ellipsis to indicate continuation).
413

Indicates whether to render text as a

useBitmapRendering

boolean

bitmap. Bitmap rendering enables you to apply effects, false such as alpha transparency and rotation transforms to the text.
Determines whether a smoothing algorithm should be applied to the false text when you set useBitmapRendering to true. When you are working with text and useBitmapRendering

No

useBitmapSmoothing

boolean

No

and
bitmapSmoothingSharpness number useBitmapSmoothing are both set to true, 3 No

this enables you to set the sharpness of the smoothing algorithm. Valid values are between 1 (low) and 8 (high).
When you are working with text and useBitmapRendering

and
useBitmapSmoothing are both set to true, bitmapSmoothingQuality number

this enables you to 1 set the quality of the smoothing algorithm. Valid values are between 0 (low) and 15 (high).

No

414

Text format properties When you work with chart text blocks, there are default text formatting properties that determine basic format aspects like alignment, color, font, indentation, italicization, and so on. You use the defaultTextFormat property to change the default text format of text blocks. This table presents the properties and default values for defaultTextFormat. To specify a new set of defaults for defaultTextFormat, provide the changes in the form of a comma-delimited list of text formatting property/value pairs, without spaces and enclosed in brackets, like so:
{prop1:value1,prop2:value2,...,propN:valueN} These are the properties and defaults for defaultTextFormat.

Property name

Value type

Definition

Default

Supported by JSChart?

align

string

Controls text alignment. Valid values are center, left justify, left, and right. Controls the amount of text block indentation in terms of pixels.

No

blockindent

number

No

bold

Controls boolean whether the text false is bold or not. Controls whether the text boolean false is bulleted or not.

No

bullet

No

color

number

Determines the color of the text, 0x000000 as expressed in No (black) hexadecimal values. Determines the type of font used for the _sans No

font

string

415

text. Valid values are _sans (for

the

default sans-serif font), _serif (for the default serif font) and
_typewriter

(for the default monospaced font). Additionally you can assign popular fonts by name, such as verdanna--if the font is unavailable the browser will use the machine's default font, which is usually something like Times New Roman.
Controls the indentation from the left margin to the first 0 character in a paragraph, in pixels.

indent

number

No

italic

Controls whether the text boolean false is italicized or not.

No

416

kerning

Determines whether text boolean kerning is enabled. Determines the amount of vertical space between lines, in pixels.

false

No

leading

number

No

leftMargin

number

Controls the left margin of the 0 paragraph, in pixels. Controls the amount of space that is uniformly distributed between all characters. Controls the right margin of the paragraph, in pixels

No

letterSpacing

number

No

rightMargin

number

No

size

number

Controls the point size of the 12 text.

No

underline

Determines whether the text boolean false is underlined or not.

No

Layout sprite
Usage: charting.layoutSprite.* The layoutSprite element is the base for all visual elements in Splunk charts that require advanced layout management. It has its own properties and inherits root properties from sprite. Values layoutSprite

417

Used by All values of the following elements have layoutSprite properties, along with their own individual properties: chart axisLabels gridLines In addition, the legend element uses layoutSprite. Properties elements are the base for all charting elements that require advanced layout management. They inherit properties from sprite and have the following additional properties.
layoutSprite

Property name

Value type

Definition
Controls the sprite visibility mode. Valid values are visible (sprite element is displayed), hidden

Default

Supported by JSChart?

visibility

string

(sprite element is hidden, but layout space is reserved for it), and collapsed (sprite element is hidden, and space is not reserved for it in the layout).

visible

No

clip

Determines whether the sprite portions that fall boolean outside its layout bounds are clipped. boolean number

false

No

snap minimumWidth

Determines whether to snap false the sprite to whole pixels. The minimum allowable 0 width of the sprite, in pixels. The minimum allowable height of the sprite, in pixels. 0

No No

minimumHeight

number

No

418

maximumWidth

number

The maximum allowable Infinity width of the sprite, in pixels. The maximum allowable height of the sprite, in pixels. Infinity

No

maximumHeight

number

No

margin

margin

The margin to place around the sprite, in pixels. Should be represented as four comma-separated integers (0,0,0,0) within parentheses and without spaces, representing left, right, top, and bottom, respectively The horizontal alignment of the sprite within its layout bounds. Valid values are between 0 (left aligned) and 1 (right aligned).

No

alignmentX

number

auto

No

alignmentY

number

The vertical alignment of the sprite within its layout bounds. Valid values are auto between 0 (top aligned) and 1 (bottom aligned). Defines the transformation matrix to apply to the sprite before layout. This is represented as a comma-delimited list of six numeric values enclosed within parentheses and without spaces, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty). Defines the transformation matrix to apply to the final rendered fill. This is represented as a comma-delimited list of six numeric values enclosed within parentheses and without spaces, corresponding to a, b, c, d, tx, and ty respectively: (a,b,c,d,tx,ty).

No

layoutTransform

matrix

No default defined.

No

renderTransform

matrix

No default defined.

No

renderTransformOrigin

point

(0,0)

No

419

The origin, or anchor point, of the renderTransform.

A point is represented by two integers representing x and y coordinates respectively, comma-separated within parentheses and without spaces.
The coordinate mode of the RenderTransformOrigin.

renderTransformOriginMode

string

Valid values are relative (indicating coordinates are between 0 and 1) and absolute (indicating coordinates are in pixels).

relative

No

Sprite
sprite is the base visual element for Splunk charts. It provides properties to the layoutSprite element, and also provides properties to visual elements in each

chart type. Values sprite Used by layoutSprite every chart type Properties element provides root properties for several charting elements.
The sprite

Property name

Value type

Definition

Supported Default by JSChart?

420

number

The x position of the sprite in its parent container. The y position of the sprite in its parent container.

No

number

No

width

number

The width of the auto sprite in pixels. The height of the sprite in pixels. The x scale of the sprite. The y scale of the sprite. The rotation of the sprite in degrees. The alpha transparency of the sprite. Valid values are between 0 auto

No

height

number

No

scaleX scaleY

number number

1 1

No No

rotation

number

No

alpha

number

No

(transparent) and 1 (opaque).

visible Determines whether the boolean sprite is visible or not. string true No

blendMode

Determines the normal blend mode to apply to the sprite. The blend mode affects how an object looks in relation to the objects around or underneath it. This is achieved by varying the transparency or color of the

No

421

blended object. Valid values include:add, alpha, darken, difference, erase, hardlight, invert, layer, lighten, multiply, normal, overlay, screen, subtract. For

more information, see this discussion of Flash blend modes.

422