Professional Documents
Culture Documents
4
Developing Dashboards, Views, and Apps for Splunk Web
Generated: 9/10/2012 12:21 pm
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.
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.
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 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>
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
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)
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.
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:
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.
OR Restart Splunk
11
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>
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
" ' < > &
13
. . . </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:
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.
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.
<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
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.
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
<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.
<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.
<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:
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.
<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.
<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
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.
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>
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.
<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].
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.
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.
33
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.
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
" '
35
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
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>
<form> <label>Sample form search</label> <searchTemplate>index=sample from="$from$"</searchTemplate> <fieldset> <input type="text" token="from" />
39
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".
40
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:
41
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
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> . . .
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.
<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
<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
<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>
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
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
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.
<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>
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
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
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.
50
<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
<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>
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.
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.
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.
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.
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
<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
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 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:
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
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.
$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.
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>/
63
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.
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.
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.
<view> </view>
Add chrome
Typically, you add the top navigation modules AccountBar and AppBar.
<view>
65
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>
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
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
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:
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.
<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.
ResultsHeader module.
68
resultsOptions
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
also accept several optional parameters. The Paginator module completes the example. Here is a listing of the complete search view.
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.
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:
Name a dashboard
Use the <label> tag to provide a name to a dashboard:
70
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
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
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:
<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
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> . . .
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.
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>
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>
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
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$
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> ...
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
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.
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:
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.
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>
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>
... <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:
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.
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
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:
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:
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>
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.
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:
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
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
<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="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
<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
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.
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
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:
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.
(Optional) Displays the amount of chart remaining to load. Displays the actual Flash chart.
99
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> . . .
. . . <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> . . .
. . . <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.
<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>
. . . <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> . . .
. . .
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
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>
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> . . . . . .
<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>
<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>
<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
The _bump endpoint clears out the Splunk-related cached items in client browsers, allowing new static content to load.
113
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>
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.
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."
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>
https://localhost:8089/servicesNS/<user_name>/<app_name>/data/ui/views?refresh=1
http://splunkserver:8000/account/insecurelogin?username=admin&password=changeme&return_t
<!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>
<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>
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
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
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.
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.
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; }
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
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:
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:
120
This file contains custom JavaScript to apply to an app. Bind the JavaScript to the CSS class in the event_renderers.conf file:
The following JavaScript code creates a link to search Google in Japanese from events in Splunk.
//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:
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:
Note: The Advanced XML implementing the view should be located here:
$SPLUNK_HOME/etc/apps/<appname>/default/data/ui/views/<view_name>.xml
http://<hostname>:<port>/app/<appname>/<view_name>
Add images To add an image use the Mako template utility function make_url in the HTML:
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.
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:
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
.bar { background:pink; }
Any element with a matching class attribute of bar now has a pink background.
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:
3. (Optional) set the height. This example sets the height to 42 pixels.
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.
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.
126
For example, add the following to a dashboard's view XML file to import the mystyles.css style sheet:
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.
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
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
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
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).
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.
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.
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
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.
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.
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.
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
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
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.
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.
148
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.
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.
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:
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:
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
This makes all event types in your business analytics app viewable in every app in your Splunk installation.
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.
$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.
<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:
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:
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
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.
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
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.
This topic walks you through creating a setup screen. You can jump ahead to view the following examples:
159
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
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
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)
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:
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.
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
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 '.*'.
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)
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 '.*'.
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.
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/
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.
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!
app.conf
file. The following table summarizes the difference between apps and
add-ons: app
visible navigation file required (see not visible
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:
174
app
required
add-on
required
comme
$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
$APP_HOME/bin/
$APP_HOME/bin/*.sh, *.bat, *.py, *.pl, etc.
$APP_HOME/default/
$APP_HOME/default/app.conf
File that sets app na description; app visib add-on); and any cus configuration file sett app. See configure
the Developer ma
175
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
$APP_HOME/default/data/ui/
$APP_HOME/default/data/ui/nav/default.xml
Views specific to you add-on; an app must more views. See bu $APP_HOME/default/data/ui/views/*.xml required optional
$APP_HOME/local/
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
$APP_HOME/metadata/
$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
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
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.
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/
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> <i>Specify the configuration for a single setting in a
180
stanza.</i> </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> <i>Specify the configuration for a single setting in a stanza.</i> </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> <i><b>Iteration mode</b>: specify the cron schedule for each search in the conf file.</i></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> <i><b>Bulk mode</b>: enable the earliest dispatch time for each search in the conf file.</i> </text> <input field="dispatch.earliest_time"> <label>Set earliest dispatch time for all searches</label> <type>text</type> </input> </block> </setup>
181
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.
182
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
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.
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>
<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>
186
</block>
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
188
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.
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.
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
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:
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
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)
Here is the directory structure of the example script for this example. The
198
+ . . ./<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
200
SHOULD_LINEMERGE=false
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
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
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
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.
204
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.
Check splunkd.log first if expected events do not appear in the expected index after scheduling the scripted input.
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.
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
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 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.
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.
Default
None
Description
Indicates where to read input from.
dict None Set to None by default, which means do not record the settings.
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:
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:
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:
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
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.
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
Description
Add a title to your panel, such as
<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.
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>
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> . . .
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>
<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.
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
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.
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
settingToCreate staticFieldsToDisplay
optional params
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
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
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
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
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
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
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
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
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
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
(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
(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
- (default) this block is enabled - block disabled - block is enabled only in 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
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.
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
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
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.
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.
lineBrushPalette
brushPalette
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
Definition
Default
Supported by JSChart?
312
symbol:
@mybrushpalette.
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>
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
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
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>
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
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
No
columnStyle
style<sprite>
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
stackMode
string
default
Yes
316
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
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>
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>
table
specific defaults.
valuePlacement warningBrush
number
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.
table for
defaults.
70
warningPlacement
number
warningSize foregroundBrush
number
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
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
No
321
columnStyle
style<sprite>
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
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
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
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.
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
brush
style<sprite>
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>
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>
tabl
specific defaults.
valuePlacement warningBrush
number
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.
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>
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
Determines whether the gauge should display minor tick marks. Determines whether the gauge should display labels. Determines whether the gauge should show its value.
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:
defaults.
See the sprite
sliceStyle
style<sprite>
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
collapsed)
other
Yes
No
328
labelLineBrush
brush
No
showLabels
boolean
Yes
showPercent
boolean
Yes
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).
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
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>
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
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>
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.
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
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>
usePercentageRange
boolean
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
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
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
defaults.
symbol:
@mybrushpalette. The properties that can be applied to bar sprites in ratio bar charts. See the sprite
barStyle
style<sprite>
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
labelStyle
style<textBlock>
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
No
markerStyle
style<sprite>
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
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
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>
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
swatchStyle
Not assigned
No
itemStyle
style<layoutSprite>
Not assigned
No
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
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
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
categories
auto
No
comparator
The comparator to use none to sort the list or categories. Comparators can be alphabetic
No
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
Yes
includeZero
boolean
Yes
minimumNumber
number
auto
Yes
maximumNumber
number
auto
Yes
344
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>
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
Definition
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
minorUnit
number
No
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
content.swatchStyle
style<layoutSprite>
content.fieldStyle
style<textBlock>
content.valueStyle
style<textBlock>
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:
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.
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
358
brackets and separated by commas, no spaces). See the Define series colors subtopic in the Charting configurations overview for more information.
Note: The
masterLegend
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
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">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
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)
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
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
(black)
alpha
number
scaleMode
string
normal
caps
string
round
joints
string
round
miterLimit
number
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
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).
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
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
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
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
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
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
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).
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
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
(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
scaleMode
string
normal
caps
string
round
joints
string
round
miterLimit
number
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
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
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:
This example references the "myColorPalette" defined above and creates a brighter version of it called "myBriteColorPalette":
385
<option name="charting.myBriteColorPalette.brightness">0.5</option> And finally, this example uses the fieldColors parameter of the field color
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
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
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
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.
388
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
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
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
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>
elemen
391
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
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
(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
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
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>
393
colorPa
alphas
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
(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
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.
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
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).
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
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
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.
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
0x00000
(black) the
colorPalette
colorPalette
Determines the color palette from which to retrieve the colors of the generated solid stroke brushes.
colorPa
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
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:
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
Default
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
brushes
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
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
snap
boolean
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
arcAngle
number
360
snap
boolean
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>
No def define more inform about types, param and defaul the sh
eleme table.
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.
properties involved.
legends
array<legends>
references. Must be
406
properties involved.
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
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.
properties involved.
gridLines
array<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.
Also used by charting.chart.data.* See the chart subtopic for more information.
409
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
offset
number
count
number
Yes
search
string
Not assigned
Yes
preview
boolean
false
Yes
and
fieldListMode string fieldHideList hide_show
Yes
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
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
Yes
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?
text
string
The raw text to display. (For HTML formatted No text by No text, see the htmlText default.
property.)
textColor number No
412
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
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
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
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
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
No
underline
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
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
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
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
422