Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Reports, Dashboards and Alerts

Splunk Dashboard Inputs, Tokens and Drilldowns

Make Splunk dashboards interactive: time, dropdown and text inputs, how tokens fill searches, default values, click drilldowns with $click.value$, and conditional panels.

A static dashboard answers one question. An interactive dashboard lets the viewer pick a host, narrow the time range or click a bar to see the events behind it. Two ideas make that possible: inputs, which collect a value, and tokens, which carry that value into searches. A drilldown is the reverse direction: a click creates a token or opens another search.

Inputs

You add inputs from Edit > Add Input in a classic dashboard (or the Inputs tab in Dashboard Studio). Common types:

Input Typical use
Time Choose the earliest and latest time for panels
Dropdown One value from a list (static choices or from a search)
Radio A few mutually exclusive choices
Multiselect Several values at once
Checkbox On/off switches
Text Free-form entry such as a user name or IP

Each input has a token name. If a dropdown has the token name host_tok, the selected value is available as $host_tok$ (in Simple XML form inputs the token is also $form.host_tok$). Dropdowns can be populated by a search, for example index=web | stats count by host, with host as the field for both label and value. Always set an initial value or a default, and add * (All) as a static choice, otherwise panels stay empty until someone chooses something.

Tokens in searches

A token is replaced by its value before the search runs:

XML
<fieldset submitButton="false">
  <input type="time" token="time_tok">
    <label>Time range</label>
    <default><earliest>-24h@h</earliest><latest>now</latest></default>
  </input>
  <input type="dropdown" token="host_tok">
    <label>Host</label>
    <choice value="*">All</choice>
    <fieldForLabel>host</fieldForLabel>
    <fieldForValue>host</fieldForValue>
    <search><query>index=web | stats count by host</query></search>
    <default>*</default>
    <initialValue>*</initialValue>
  </input>
</fieldset>

<chart>
  <search>
    <query>index=web host=$host_tok$ | timechart count</query>
    <earliest>$time_tok.earliest$</earliest>
    <latest>$time_tok.latest$</latest>
  </search>
</chart>

Details that trip people up:

  • A search with an unset token does not run at all. The panel shows "Waiting for input" until the token has a value; defaults prevent this.
  • Text inputs often need a prefix and suffix (for example " around the value) so that user=$user_tok$ becomes user="alice smith". In a multiselect, valuePrefix, valueSuffix and delimiter build the OR expression, for example host=a OR host=b.
  • Token values are inserted as text. A user who types * | delete into a text input could alter a search, so restrict text inputs with a validation or use dropdowns when you can (and never give dashboard users the delete capability).
  • Use |s to quote a token safely: user=$user_tok|s$ wraps the value in double quotes and escapes inner quotes.

Try it: token substitution (stand-in)

Splunk does this replacement inside the dashboard framework. The stand-in reproduces the rules for defaults, prefixes and the "unset token" behavior.

Python Stand-in: filling tokens in a search

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Multiselect: building an OR list

A multiselect input with delimiter=" OR ", valuePrefix="host=" and no suffix yields host=web01 OR host=web02. Wrap the token in parentheses in the search: index=web ($host_tok$), otherwise the OR mixes with the surrounding terms.

Python Stand-in: multiselect to an OR expression

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Drilldowns

A drilldown reacts to a click on a chart, table or single value. In the UI choose Edit Drilldown on the panel and pick:

  • Link to search: open the search page for the clicked value (the default for many charts).
  • Link to dashboard / report / custom URL: navigate, passing values through the URL.
  • Manage tokens on this dashboard: set tokens from the click and let other panels react.

Click values are available as tokens:

Token Meaning
$click.name$ First column's name (the x-axis field for a chart)
$click.value$ First column's value (the clicked x-axis value)
$click.name2$ Name of the second column (the series, for a chart)
$click.value2$ Value of the second column (the clicked series or cell value)
$row.<field>$ The value of any field in the clicked table row

A table drilldown that stores the clicked user in a token:

XML
<table>
  <search><query>index=auth action=failure | stats count by user</query></search>
  <drilldown>
    <set token="user_tok">$row.user$</set>
  </drilldown>
</table>
<table depends="$user_tok$">
  <title>Events for $user_tok$</title>
  <search><query>index=auth user=$user_tok|s$ | table _time host src action</query></search>
</table>

The second panel uses depends="$user_tok$", so it is hidden until the token exists. rejects="$token$" does the opposite. <unset token="user_tok"/> clears the token, for example from a "Close" link. Input changes can also run <change> handlers (<set>, <unset>, <condition value="...">) to fill dependent tokens: choosing an index can set a default sourcetype.

Try it: mapping a click to tokens (stand-in)

Python Stand-in: what a table click sets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Design advice

  • Provide defaults for every input so the dashboard loads in a meaningful state.
  • Put inputs together at the top, with the time input first.
  • Use dropdowns populated by searches for hosts, indexes and sourcetypes, with earliest/latest small, because the input runs its own search.
  • Avoid chains of more than two dependent inputs; they confuse people and multiply searches.
  • Test with the "All" choice (*); it is the case most people open first and the heaviest.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to a panel whose search uses $host_tok$ when the token has no value?

    Splunk waits until every token in the search is set. Give inputs defaults to avoid empty panels.
  2. 2. Which token holds the value of a field called src in the clicked table row?

    $row.<field>$ exposes each field of the clicked row, whichever column you click.
  3. 3. What does depends="$user_tok$" on a panel do?

    A panel with depends is only displayed (and its searches only run) while the token exists.
  4. 4. Why wrap a multiselect token in parentheses in the search?

    index=ops host=a OR host=b would apply OR to the wrong terms, so group the list: index=ops (host=a OR host=b).

Summary

  • Inputs collect values into tokens; searches use $token$ and run only when all tokens are set.
  • Always set defaults; use |s or prefixes and suffixes to quote values, and grouping parentheses for OR lists.
  • Drilldowns set tokens from clicks ($click.value$, $row.field$); depends and rejects show or hide panels.
  • Dropdowns beat free text for safety and usability.

Next: Alerts and triggered actions