Splunk® Enterprise

Dashboards and Visualizations

Download manual as PDF

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

Form examples

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.

Basic form example

Forms specify a <searchTemplate> to define the search for the form. The search uses fields or other identifiable parts of your data. Typically, you build a search that fits your data and use case. Then, identify the parts of the search that can be specified by the user.

The form search uses "tokens" for search fields that accept user data. In the search command, surround a field with $...$ characters to specify a token. For the example below, $series$ defines the token.

When a user types in a search term of a form, the token is replaced with the user input. For example, the basic form example below provides a textbox to specify the value for series in a search.

Here is the underlying search for this form:

index=_internal source=*metrics.log group="per_sourcetype_thruput" series=$series$ | table sourcetype eps, kb, kbps

Highlights of this example:

  • Token The token $series$ represents the text entered by the user in the text box.
  • Search template The <searchTemplate> is global to the form. (You can also place a <searchTemplate> within individual panels. See example below.)
  • Time range picker The search specifies a time range picker. If you specify a time range picker, do not specify time constraints within the search.
  • autoRun The <fieldset> tag is set to autoRun, which means the search runs as soon as it is loaded.


BasicForm.png


Here is the simple XML implementing the form.

<form>
  <label>Sample Form</label>
  <description/>

  <!-- define master search template                              -->
  <!-- leave time unbounded so that the time input can be used    -->
  <!-- $series$ is the token replaced by the input in the textbox -->
  <searchTemplate>
    index=_internal source=*metrics.log
    group="per_sourcetype_thruput" series=$series$ 
    | table sourcetype eps, kb, kbps
  </searchTemplate>
  
  <!-- use the autoRun attribute so the form runs when loaded -->
  <fieldset autoRun="True">
    
    <!-- Create a text box; token is "series"                         -->
    <!-- label: Label for the text box                                -->
    <!-- default: Default value for the form                          -->
    <!-- suffix: All tokens are followed by a *                       -->
    <!--         If user does not specify text, then search uses '*'  -->
    <input type="text" token="series">
      <label>sourcetype</label>
      <default>splunkd</default>
      <suffix>*</suffix>
    </input>
    
    <!-- Add time range picker -->
    <input type="time" searchWhenChanged="true">
      <default>
        <earliestTime>-24h@h</earliestTime>
        <latestTime>now</latestTime>
      </default>
    </input>
    
  </fieldset>

  <row>
    <panel>
      <!-- Show results as a table -->
      <table>
        <option name="showPager">true</option>
        <option name="count">20</option>
      </table>
    </panel>
  </row>
</form>


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

Static and dynamic inputs to forms

You can specify dropdown lists and radio buttons as inputs to forms. You can define the choices for these inputs within the simple XML code or use a populating search to define the choices.

Highlights of this example:

  • Static inputs Simple XML code defines the radio button choices.
  • Dynamic inputs A populating search defines inputs for the dropdown list.
  • Search when changed The inputs specify to initiate the search after making a selection. A submit button is not needed.
  • Search Template The <searchTemplate> in this form is placed within the panel.
  • Tokens Uses search tokens to customize the title of the panel


FormWithInputs.png


Here is the simple XML implementing the form:


<form>
  <label>Form with static and dynamic inputs</label>
  <description>Events Filtered by User and Sourcetype</description>
  
  <!-- Do not need a Search Button. Inputs search when changed -->
  <fieldset autoRun="true" submitButton="false">
    
    <!-- Specify search when changed for the inputs -->
    <input type="radio" token="username" searchWhenChanged="true">
      <label>Select a User:</label>
      <default>Splunk System User</default>
      
      <!-- Define the choices in code -->
      <choice value="*">All</choice>
      <choice value="-">-</choice>
      <choice value="admin">Admin</choice>
      <choice value="nobody">Nobody</choice>
      <choice value="splunk-system-user">Splunk System User</choice>
    </input>
    
    <input type="dropdown" token="source" searchWhenChanged="true">
      <label>Select a Sourcetype:</label>
      <prefix>sourcetype="</prefix>
      <suffix>"</suffix>
      <default>splunkd</default>
      
     <!-- Define the default value -->      
      <choice value="*">All</choice>
      
     <!-- Define the choices with a populating search -->
      <populatingSearch fieldForValue="sourcetype" fieldForLabel="sourcetype" earliest="-24h" latest="now">
        <![CDATA[index=_internal | stats count by sourcetype]]>
      </populatingSearch>
    </input>    
    
  </fieldset>
  
  <row>
    <panel>
      <chart>
        <!-- Use tokens from the search template to modify the title of the panel -->
        <title>Chart of Events for user="$username$" and $source$</title>
      
        <!-- searchTemplate is placed inside the panel -->
        <searchTemplate>index=_internal user=$username$ $source$ | timechart count</searchTemplate>
      
        <earliestTime>-24h@h</earliestTime>
        <latestTime>now</latestTime>
        <option name="charting.chart">column</option>
      </chart>
    </panel>
  </row>
</form>

Create a form with a global search

This example shows how to create a form that uses the <searchTemplate> tag as a global search for the form. The Dashboard Editor does not support creating forms with a global search.

About the Dashboard Editor shows how to create dashboards using the Dashboard Editor. This topic walks you through creating a basic dashboard that you later convert to a form with a global search.

1. From the Dashboards page of an app, click Create New Dashboard and specify the following, then click Create Dashboard:

  • Title: Convert a dashboard to a form

2. Add a panel and specify the following:

  • Content Title: My form search
  • Inline search: Inline search string listed below
  • Time Range: Last 7 days

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

3. Click Add Panel and Done to view the new dashboard. The dashboard lists the results of the search.

This dashboard has an inline search and a hard-coded time range for results.

In the following steps, you convert the inline search to a search for the form. The user adds an additional search term to the search query in the form. The user can also use a time range picker to specify the time range for the search.

4. Click Edit > Edit Source. This is the generated simple XML for the dashboard:

<dashboard>
  <label>Dashboard to convert to Form Search</label>
  <row>
    <panel>
      <chart>
        <searchString>
          index=_internal source=*metrics.log group="per_sourcetype_thruput"  
          |  fields eps, kb, kbps | top 100 eps
        </searchString>
        <title>My form search</title>
        <earliestTime>-7d@h</earliestTime>
        <latestTime>now</latestTime>
        <!-- There are also visualization options -->
        <!-- which are not needed for this example -->
        <!-- You can delete these options -->
      </chart>
    </panel>
  </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>
    <panel>
      <chart>
        <title>My Form Search</title>
        <earliestTime>-7d</earliestTime>
        <latestTime>now</latestTime>
      </chart>
    </panel>
  </row>
</form>

6. Modify the search to include a series field token ($series$). Add a text box for the user to specify the series field. Set the autoRun attribute for the <fieldset> element.

The field set in this example specifies a label for the text box, a seed value for the text box, and a default value to append to each user-supplied value. It runs as soon as the view is loaded.

<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 autoRun="True">
    <input type="text" token="series">
      <label>sourcetype</label>
      <default>splunkd</default>
      <suffix>*</suffix>
    </input>
  </fieldset>

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

7. Remove the hardcoded time fields from the <chart> element, and add a time range picker to the field set.

<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>
    
    <input type="time">
      <default>Last 7 days</default>
    </input>
  </fieldset>

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


8. Click Save to view the form. You can add different source types to the check box, and specify different time ranges.


Dashboard2form.png

PREVIOUS
Dashboard examples
  NEXT
Dynamic drilldown in dashboards and forms

This documentation applies to the following versions of Splunk® Enterprise: 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters