• Gabriel

GV-Utils

Updated: Apr 26

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 "submit" buttons in dashboards

  • encode text so it can be included in a URL

  • summarize heterogeneous data

  • render dynamically produced HTML in dashboards

  • render syntax-highlighted SPL in dashboards

  • render colourful diff in dashboards

  • convert search-syntax SPL into eval-syntax SPL

  • add expandable 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 but 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:

submit_button
.txt
Download TXT • 2KB

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.


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:


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:

htmliser
.txt
Download TXT • 760B

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:

splhighlight
.txt
Download TXT • 852B

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

diffy
.txt
Download TXT • 2KB

The is_spl_field option is... optional. If provided, diffy will syntax highlight values for which the field is true.

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=WARNING

You 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:




117 views0 comments

Recent Posts

See All

This for the most part isn't splunk-specific, but if you do any amount of administration on the linux command line, you might find it helpful. .bashrc A better prompt In your .bashrc: PS1='\t \[\033[0