Custom Error View in Splunk Part 1: Listening for Search Events

I will be showing you an example of what the end result will be when an error message is fully displayed – allowing the user to gain immediate, fully visible feedback, not just an alert for the message. I will begin by showing you how to write a search that will generate an error – allowing us to then modify the dashboard panel to use the search’s on(“progress:done”) event to check and see if an error was returned and, if so, display it.

Building a Simple Dashboard 

Let’s start by creating an invalid Splunk search that guarantees an error will be thrown:

When running the search, we will get back an error:

Now that we have an error coming back, click on ‘Save As’ < Dashboard Panel in the top right:

Name the Dashboard whatever you like. I named mine ‘Error Reporting:’

Then click on ‘View Dashboard’ and click on ‘Edit’ < Edit Source

You should see the following:

Make the following changes highlighted below:

Click ‘Save.’

Creating the app.js file 

If you have access to your Splunk install directories, depending on where you created your dashboard (for example in the Search and Reporting app), you would go to:

Then inside of that directory, go to appserver/static. Your full directory path would be:

If you added this to some other app, or a newly created app, the directory ‘appserver’ may not exist and you’ll have to create it.

Splunk loads it’s dependencies using the require.js library. If you’ve never used it before it is a more efficient way to load file dependencies.

app.js:

Splunk’s JS Framework is based on the backbone.js library. It has one dependency, the underscore.js library, which is why we load that first. We are also going to load in Splunk’s MVC components. We then pass in our dependencies as function parameters.

Creating Instances of Our Search and Table 

Inside of your require function, we will need to first create variables that will reference our search and the visualization of that search, in this case a table:

We’re using the Splunk mvc components to pull reference to these items based off the id attributes we defined in our Simple XML earlier.

Listening for Events 

Searches in Splunk have events tied to them such as progress, end, and failed. If you want more detailed information on these events, check out the Splunk documentation on progress events.

In our case, we are going to listen for the ‘search:done’ event, so we can check whether or not there was an error in the response. The ‘on’ event has a properties parameter from which we can extract information about the search. So, let’s start by logging that out:

If you inspect the console in your browser you’ll see it comes back as an object with a lot of different properties:

We’re specifically interested in what is in ‘content.’ Expand that out and you should get a long list of items. Look for ‘messages,’ expand that, and you should see the following:

That error message currently gets injected into the bottom right of the dashboard panel:

First, we are going to define our responseMsg variable inside of our on event, like so:

Then we want to ensure the response we get back is not undefined, so we don’t get an error:

Inside of our if statement we are going to create a variable for the type, which in this case is ERROR and the text, which is the actual error message:

Then we want to check and see if the response type is of ERROR:

Inside of our if statement we are checking to make sure it’s of type ERROR. If it is of type ERROR, then we want to append in the error to the table element. So, we are essentially saying “in the table element find the dom element with a class of panel-body and append a div with a class of error-response to it.”

In the end, your code should look like this:

One last thing we will want to take care of is removing the error. As is, if we run the search and it errors out and then rerun the search successfully, the error will still be present because we haven’t removed it from the UI – this could be very confusing for the user.

We do this by adding:

This will be added right under where we defined our responseMsg variable and right before our first if statement. Now, if it’s successful and no error is thrown, the error will be removed if it exists. Also, feel free to remove your console.log() that currently exists in the on event.

In the end your entire app.js will look like the following:

Before we restart, let’s go ahead and create our CSS file as well.

Part 2: Styling our error

Right now if we were to restart Splunk to view our custom error it would look something like this:

Right now if we were to restart Splunk to view our custom error it would look something like what you see above.

This doesn’t look very good. So, let’s go ahead and add some style to our app.css file:

Go ahead and save your app.css file and then restart Splunk.

Once you restart Splunk your custom error should look like this:

Congrats! You now have a customized error component in Splunk.