Reusable UI Components in Splunk: A Search Help Menu [Part 1]

This tutorial goes over the build-out process of creating a custom, reusable search help menu in Splunk. This helps the user as it provides additional context.



Part 1: Getting Started

There are times when a client will request a custom user interface (UI) modification in Splunk -- sometimes it will be a feature that is common for websites, but not necessarily found in Splunk’s UI. Building out these types of features can provide quite a bit of value to end-users, and can be enjoyable as well.

A benefit to this particular search help menu build-out process, is that we can reuse it across multiple panels on any Splunk dashboard we want. Fortunately, in order to make the component reusable, all we need to do is modify some HTML on a dashboard and include a JavaScript file. This is what we call a "modular" approach.

Note: Some of the commands I use in this are Unix only, but they shouldn’t prevent you from following along and completing the process.

For those of you who are more audio-visual learners, feel free to follow along with the screencast if you would like.

Also, if you're only interested in the end result, or would like to reference some files as we build out the app, you can download the completed version of the app on the HurricaneLabs GitHub.

What We Will Build

In this tutorial we will be building a help menu that will provide a description about a particular search. There may be times when a user needs to view information on a specific dashboard that they've never seen before and they need to quickly gather as much information as possible.

Basic Structure

We’re going to put all of our code into our own custom app. This will help keep our code in one central place that's not Splunk’s Search and Reporting app.

The Final Result

A user will click on a question mark icon, which will then show a popdown menu with text describing the purpose of a search. This is beneficial as it provides extra context to the user and will also not detract from the original dashboard UI.

Create an App

First thing we are going to do is build out an app to store our code in.

From the Splunk homepage, you can click the gear icon in the left-hand navigation bar or click Apps < Manage Apps if you are in any other section of the Splunk UI.

From there, choose ‘Create app’ as shown below:

Then fill out all the necessary information. I’m calling my app "Help Menu", but you can name it whatever you like.

As you can see above we are setting its visible state to 'No’. This app will have no dashboards in it, as it will only be used as a place to store our code.

Next, go into your app’s main directory as shown below:

Inside of your app’s main directory create a new folder called "appserver", and then inside of appserver create a new folder called "static". We will also need to create an index.js file that will act as our main file. If you’ve done any kind of Splunk development, or followed any of my other blog posts, this process should look pretty familiar to you.

You can quickly do this on the command line (Unix - sorry Windows people) in the app’s main directory:

mkdir -p appserver/static
cd appserver/static/
touch index.js

Next, open up index.js in your preferred text editor and add the following:

require([
    'underscore',
    'backbone',
    'jquery',
    'splunkjs/mvc',
    'splunkjs/mvc/simplexml/ready!'
], function(_, Backbone, $, mvc) {

    console.log('I need help!');

});

Save index.js.

For the sake of speeding up the development process, I am also going to turn off caching on JavaScript files.

To do this, you can create a local version of web.conf in $SPLUNK_HOME/etc/system/local/ and put:

[settings]
js_no_cache = True

Restart Splunk (through the UI or command line: $SPLUNK_HOME/bin/splunk restart)

Basic Dashboard

In order for this to work we will, of course, need a dashboard to hook up to. So, let's go ahead and build out some simple searches to populate a dashboard.

The first search I will use will simply pull all of my saved searches using the rest command:

| rest /services/saved/searches | table title

Once you run the search click ‘Save As’ < ‘Dashboard Panel’ as shown below:

Then fill out all the necessary information:

Click ‘Save’ and then ‘View dashboard’.

The second search we will add directly to the dashboard. This search will be to pull a list of apps installed on our local Search Head:

| rest /services/apps/local | table title

Add your second search to the dashboard by clicking on ‘Edit’ < ‘Edit Panels’ then ‘Add Panel’ and then the ‘New’ link that appears in the slideout menu. Then choose Statistics Table. Finally click ‘Add to dashboard’.

Your dashboard should look something like this:

The next thing we need to do is include a reference to our index.js file located in our Help Menu app. Click on ‘Edit’ < ‘Edit Source’.

In the SimpleXML we will add a reference to the index.js file in our Help Menu app, like so:

Click save and then in your browser open up your console window and you should see the message we logged out earlier: "I need help!". We are successfully loading in the file. Now we need to make this more useful.

That's it for the first part of the tutorial. In Part 2 we will go over setting up the template and view for our help menu.




Close off Canvas Menu