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

By |Published On: May 19th, 2015|

If you’ve ever had a dashboard in Splunk that includes searches with errors, you’ll notice a little icon popup that alerts you of an error message. From a user standpoint, this little popup may not make it completely obvious that an error is being outputted. This can be less than ideal for the user, especially when running searches against an API, as the user should have immediate clarity as to why the search failed. A better way to handle these error alerts, to benefit the user interface perspective, would be to clearly display the error message directly within the Splunk dashboard panel.

This blog-screencast tutorial will teach you how to leverage aspects of the Splunk JavaScript Framework to display error messages directly within your dashboard panels. You can either watch the screencast below, or continue reading. The second part on adding style to our error is here.

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:

Copy to Clipboard

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

Copy to Clipboard

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:

Copy to Clipboard

Make the following changes highlighted below:

Copy to Clipboard

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:

Copy to Clipboard

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

Copy to Clipboard

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.


Copy to Clipboard

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:

Copy to Clipboard

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:

Copy to Clipboard

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:

Copy to Clipboard

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

Copy to Clipboard

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:

Copy to Clipboard

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

Copy to Clipboard

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

Copy to Clipboard

In the end, your code should look like this:

Copy to Clipboard

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:

Copy to Clipboard

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:

Copy to Clipboard

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:

Copy to Clipboard

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.

Share with your network!
Get monthly updates from Hurricane Labs
* indicates required

About Hurricane Labs

Hurricane Labs is a dynamic Managed Services Provider that unlocks the potential of Splunk and security for diverse enterprises across the United States. With a dedicated, Splunk-focused team and an emphasis on humanity and collaboration, we provide the skills, resources, and results to help make our customers’ lives easier.

For more information, visit and follow us on Twitter @hurricanelabs.