This is the documentation for the GV-Utils app on splunkbase. This app offers various utilities to solve a number of problems in Splunk:
powerful yet easy "submit" buttons in dashboards
text areas in dashboards (version 1.3+)
encode text so it can be included in a URL
summarize heterogeneous data
figure out what changed between 2 sets of key-value pairs (version 1.4+)
render dynamically produced HTML in dashboards
render syntax-highlighted SPL in dashboards
render syntax-highlighted XML in dashboards (version 1.5+)
render colourful diff in dashboards, optionally combined with SPL or XML syntax highlighting
split SPL code in individual commands (version 1.5+)
convert search-syntax SPL into eval-syntax SPL
add expandable sliding documentation to dashboards
debug dashboard tokens
Create your own Submit Buttons
There are a number of issues with Splunk’s simple XML forms submit button:
you can't have more than one
you can't move it
you can't hide it (for instance, so that it only appears when the right input is populated)
it won't do anything if you click it a second time without changing any input
if you have inputs that are sanitised with some <change> action, this effectively forces the searchWhenChanged to true, even if you want the search to only happen when the submit button is pressed
All the solutions I’ve seen required coding and deploying some JavaScript specific to the dashboard you are developing. This implies special skills and privileges for the dashboard developer. In contrast my simple solution:
can be reused in any dashboard by any user (no admin rights required)
doesn't require installing or deploying anything (past the initial setup)
doesn't require any JavaScript knowledge
Note: Technically (as with other solutions out there) the buttons we are introducing are not "submit" buttons as their purpose isn't to "submit all the tokens". So it's not the same thing, but that’s also why it's a lot more versatile.
Hello world example
Just to get you started, this is the simplest dashboard you could have with one of my submit buttons:
Here's the code:
Basically, you need to load the JavaScript and the CSS, and have a button with id "submit_button" that will populate a token called "submit_trigger" with a random number every time the button is pressed.
That sounds so simple. The next example gives you an idea of what you can achieve with this.
More interesting example
Let's look at this convoluted example:
This is the source of that dashboard:
You can add up to 20 submit buttons. The first one should have id submit_button, the second submit_button2, the 3rd one submit_button3, etc. When a submit button is clicked, a corresponding token will be populated. The button with id submit_button will populate the submit_trigger token, submit_button2 will populate submit_trigger2, etc. Each time a button is clicked, a brand new random value is given to the corresponding token, which will trigger any search relying on this token, provided that all the other tokens it needs are populated.
Note about colours: buttons made with <input> tags inside <fieldset> will be green (thanks to the CSS) but buttons made with <button> tags inside <html> sections will remain grey. You can always create buttons in <fieldset> and then move them around to any dashboard panel. You can also change the colour of one or more buttons by adding this kind of CSS:
#submit_button2 button { background-color: #DC4E41 !important;}#submit_button2 button:hover { background-color: #C03E31 !important;}
Text areas in dashboards
(Only with GV-Utils version 1.3 and above)
For when dashboard users need to input multiline text:
This is obtained with:
Note how the textarea's ID must start with "ta_". The JavaScript will put the content inputted in the textarea in a token of the same name, minus the "ta_" prefix.
Note how the token must be used with "|s" and linebreaks must be reintroduced before the field is ready for use in your search.
Make text URL-safe with urlencode
The urlencode command simply encodes text so that it can be safely used in a URL:
One use case could be to place the output of the command in a dashboard token that can then be used in a link like so:
https://mysplunkinstance:8000/en-GB/app/search/search?q=$token$ Make your table denser with summarise
The summarise command is useful when dealing with heterogeneous data. With heterogeneous data, the fields of interests to you are different depending on the type of event, leading to a wide sparse table:
With the summarise command you can make a much more concise table with the same information:
Since version 1.3, the summarise command has 2 parameters:
multivalue=<boolean> --> summary field will be multivalue, one per field. Defaults to false.
max_length=<integer> --> if non-zero, limits the length of values to that number of characters. Defaults to zero.
Figure out what changed between 2 sets of key-value pairs
(Only with GV-Utils version 1.4 and above)
Given a couple of :-separated key-value multivalue fields, figures out what fields are different if any:
A bit of a convoluted use case but this was needed for ES Choreographer.
Render dynamic HTML with htmliser
If your dashboard produces some HTML that you can assign to a token, you can use the htmliser to render it in your dashboard.
Here's the source:
The token has to be named tokHTML and the HTML is rendered in the <div> with ID "htmlPanelWithToken". If you need a second section, you can also use "tokHTML2" and "htmlPanelWithToken2".
You might want to hide the panel with the search that populates the token and initialise the token so it still looks like something is happening if your search takes a moment to complete.
SPL syntax highlighting with splhighlight
The splhighlight command takes some SPL and creates a syntax-highlighted HTML version, like so:
You'll need GV-Utils:htmliser.js in combination with the correct CSS file for your dashboard: GV-Utils:gv_spl_highlight_light.css for a light theme and GV-Utils:gv_spl_highlight_dark.css for a dark theme:
XML syntax highlighting with xmlhighlight
(Only with GV-Utils version 1.5 and above)
Same as with splhighlight above, but for XML.
Create colourful diffs with diffy
The diffy command allows you to generate colourful HTML diffs in your dashboards:
As with splhighlight, you'll need GV-Utils:htmliser.js and the right CSS files (replace "_light" with "_dark" if your dashboard uses a dark theme).
The is_spl_field option is... optional. If provided, diffy will syntax highlight values for which the field is true.
As of version 1.5 the is_spl_field option is deprecated and instead you should use the syntax_colouring_field option instead. The field specified in this option will control what syntax highlighting is used in the diff:
"spl" for SPL highlighting
"xml" for XML highlighting
anything else (including False values) for no further highlighting
Split SPL into individual commands
(Only with GV-Utils version 1.5 and above)
Given a field with some SPL, produces a multivalue field with one SPL command per value.
Notice how multiple eval commands are split into indvidual ones.
This is for the purpose of static code analysis of SPL searches.
Convert search-syntax SPL to eval-syntax with evalify
The evalify command takes some search-style SPL and converts it into eval-style SPL, like so:
Now why would you want to do this? Say you have some configuration that categorises some of your data in search-style SPL:
category,SPL
Splunk errors,index=_internal log_level=ERROR
Splunk warnings,index=_internal log_level=WARNINGYou could have a dashboard where a user chooses a category and the SPL gets put in a token that is used in a search to pull the data. So far so good.
Now let's say you do a more generic search like "index=_internal" and you want to count the results by category. This is where you need the eval syntax, so you can do something like this:
Yes, it's awkward. And it's not perfect (for instance the search-style syntax is case insensitive, but the eval-style syntax is case sensitive). But this allows your dashboard to be driven by your configuration and be quite flexible.
Document your dashboards with docs4dash
Disclaimer: I didn't write this, Olivier Lauret from https://octamis.com did! I have permission to include it here.
This is a neat way to add documentation to your dashboards without taking space. This code allows you to add a little "?" in an HTML section of your dashboard:
You can define a tooltip that appears when the mouse hovers above the "?":
Clicking on the "?" toggles the appearance and disappearance of another piece of HTML:
This is the code behind this example:
NOTE: this will NOT work if the <html> section contains any dashboard $token$. This is because when the token changes, splunk re-renders the HTML and drops the JavaScript. To make it work, the JavaScript needs to be associated with the panel. This is possible but requires version 1.1.0 or above of GV-Utils.
For each panel using docs4dash and dashboard tokens:
give an id to the panel: The id has to be unique to the panel and be one from docs4dash_panel1 to docs4dash_panel10
change the class of the span from docs4dash-link to docs4dash-link2
Here's an example:
That produces:
Change the width of individual text inputs
(Only with GV-Utils version 1.1 and above)
To change the width of an individual text input, load dashboard_tweaker.css and simply add a unique id corresponding to the desired width:
wide_text300 for 300 pixel wide
wide_text400 for 400
same for 500, 600, 700 and 800
unfortunately IDs must be unique, so if you have more than one text box with the same width you need to differentiate them with suffixes: wide_text300 for the first one, wide_text300_2 for the 2d one, ... up to wide_text300_20.
To make a text input narrower (145 pixels) use: "narrow_text". Again if more than one add a number: "narrow_text2", "narrow_text3", ... up to "narrow_text20".
Here's a few examples:
Troubleshoot your tokens with showtokens
Disclaimer: I didn't write this! I saw it mentioned online and found it in a couple of other apps and just stole it.
This is useful for troubleshooting your dashboard tokens. It adds a table at the bottom of your dashboard with the list of all your tokens and their current values. It updates as you interact with your dashboard so you can easily see what's happening.
All you have to do is just load it:
Release notes
Version 1.5.0
New splparse command takes SPL and splits it in individual search commands for your static code analysis purposes.
New xmlhighlight command takes XML code and produces a syntax-highlighted HTML version of it, similar to splhighlight for SPL.
The diffy command can now produce diffs that can either have SPL or XML syntax highlighting on top of the diff colours (previously only SPL was available).
Fixed bug where diffy would fail in some circumstances if either the old or new value was the empty string.
Version 1.4.0
Added custom command "whatchanged" to support the next version of ES Choreographer
Version 1.3.0
HTML text areas!
Summarise command has 2 new options
Version 1.2.1
Reduced diff size in some cases, especially where linebreaks are added/removed
Fix CSS bug where the table was wider than the page
Version 1.1.0
New way to use docs4dash that is compatible with having tokens used in the same HTML section
New dashboard_tweaker.css CSS