Chapter 5. The Splunk Web Framework

In this chapter, we will dive directly into HTML dashboards and the Splunk web framework. This won't be just an overview, this is some serious coding. This is the nuts and bolts for all the newer apps being written and produced, as it provides the best options for customization and visualization. There is a basic structure, and some rather important points that need to be made, and some additional information on how to brand using custom CSS and JavaScript. We will explore the SplunkJS stack, and go over how the objects are used in their native form, and show how you can customize them. We will add a custom visualization using a D3 chart, and place it in the dashboard. Using D3 charts allows for so much additional extensibility and presentation. We will also cover adding external data sources (via REST APIs and other methods) using the jQuery library.

The HTML dashboard

The HTML dashboard can either be generated from an existing SimpleXML dashboard, or it can be written by hand. We recommend creating a SimpleXML dashboard and then converting it. This ensures that the most up-to-date code is generated from the version you are using. For a refresher on how to convert a SimpleXML dashboard to an HTML dashboard, please see Chapter 4, Basic Views and Dashboards. The Splunk web framework is built in to the HTML dashboard and into the core programming of Splunk. The framework is designed to allow maximum extensibility and versatility in the development of dashboards.

The basic code of the previously generated dashboard (see Chapter 4, Basic Views and Dashboards—the dashboard is called "Overview") contains various items that are consistent across dashboards. Generally, all of the HTML and CSS definitions are placed within the dashboard code first, with the JavaScript portion at the end. This is a pretty standard best practice, as this allows the...

The SplunkJS stack

The SplunkJS stack contains a few frameworks to help web developers build Splunk applications in a familiar JavaScript environment. The first is backbone.js, which provides the MVC framework as building blocks for your dashboards. The second is RequireJS, which helps to manage dependencies. The third is jQuery, which helps to manage the document objects within the dashboard. Finally, Splunk provides a large library with views and managers that help you interact with Splunk. We would be remiss if we didn't take some time and review the different views and managers. Each of these is implemented within the JavaScript code of the RequireJS function.

Note

As we start looking into each item of the Splunk library, we will present the native module path and the default variable name. These get placed in the RequireJS function call as noted earlier. This can be abstracted in the following manner:

require([ "<splunk module path>" ],
    function( <splunk variable name>...

Tokenization

Tokenization refers to the use of tokens within a dashboard. A token is a placeholder for a value within a dashboard. These placeholders can be dynamically updated within the dashboard. Searches and other objects can access these values using a special syntax. The basic syntax is to surround the token variable name with "$". So, for example, if you defined a TextInputView earlier, and assigned it the token name myText, then you would reference the value as $myText$.

There are a few different ways to generate token values within a dashboard. These generally include ways to do the following:

• Define tokens to capture input values for forms.

• Define tokens to specify conditional actions based on the value of the token.

• Define tokens within a search string that use values based on previously defined tokens.

• Splunk Enterprise defines token values that you can access. Defined tokens include tokens for visualizations, time inputs, and labels and values of form inputs.

Ok, so now what? Once...

Customizing Splunk dashboards using CSS

Now that we have covered the different types of JavaScript modules, let's start customizing our Overview dashboard. We already converted a SimpleXML dashboard to an HTML dashboard, but now we want to add some specific styling. We start by creating a dashboard CSS file in the appserver/static folder of our app. In this file, we will override specific Splunk CSS styles, as well as add a few of our own later on, specifically for a D3 visualization. Inside the dashboard.css file, add this CSS code:

.dashboard-row .dashboard-panel  {
  border: 1px dashed black;
}

This CSS will add a dashed border, 1 pixel in width, to each panel in the dashboard, overriding the native Splunk style. Now that we have a CSS file, we need to include it on the page. In order to override the Splunk CSS, you have to place the CSS include after the bootstrap CSS included with Splunk. This is as simple as placing the code line following this paragraph before the closing head tag ...

Customizing Splunk dashboards using JavaScript

Before we start using custom JavaScript, let's work with the already included JavaScript to make our dashboard include animation. In this example, we will add additional controls to each chart to allow them to slide. This is advantageous in that you can give the user control to hide charts they are not interested in, or that take up too much space to see the charts they want to examine.

First, let's add the slide controls. Right after the panel-element-row div tag for the two charts, you will see a panel-head div tag. After the panel-head div tag, you will see a dashboard-element div tag. The concept here is to use the header as the slide control, thereby leaving the header visible and allowing the end user to notice that there might be more information. In order to achieve this, you must move the header before the element. The default code shows the header contained within the element div:

<div id="element6" class="dashboard-element chart...

Custom D3 visualization

Now that we have a slide-out, let's move on to visualizations. We now want to add an information graphic that displays some statistics about the prices of the products. So let's use a box plot! D3 offers a nice example at http://bl.ocks.org/mbostock/4061502. We will take this code and adapt it for use with this dashboard. Let's start with the CSS for the boxplots. This is located in the index.html section of the tutorial. Copy all of the CSS except for the body class to the dashboard.css file in the app. In that same section, find the function irq, and copy that into the dashboard.js file. Now, find the box.js section. Copy the entire function to a file under appserver/static/js. Download and place a copy of d3.min.js in appserver/static/js. Once these files are in place, add them to the RequireJS stack using the methods described in the last section. D3 won't have a dependency but the box plot requires D3. This completes the initial dependency setup for the visualization...

External data and content

Very quickly, we will mention ways to pull in additional data from external sources. These can be external data sources, or more likely, internal API calls to internal services.

Data

Say you have an internal monitoring solution that has an API. Since you want to be efficient in both the collection of data and the storage of data, you only want to collect and store the performance data in the internal monitoring solution. However, how can you integrate the two? Simply put, you can build a script input that consumes the API data and stores the resulting performance data in a lookup that you can use to automatically enhance the data. You can also use jQuery to pull that data right into the dashboard, and use the D3 visualizations as well as the built-in JavaScript objects to visualize it. This is done quite simply by using the Ajax library of jQuery.

$.ajax({
  url: "http://myinternalserver.example.com/getNode/myNode"
})
  .done(function( data ) {
    if ( console &...

Summary

In this chapter, we covered some deeper elements of Splunk applications and visualizations. Starting with the basics of HTML dashboards and the Splunk Web Framework, we discussed how to include basic CSS overrides for some of the Splunk CSS. We also covered the static folder location within an app that serves content as needed. We mentioned the use of the bump button to bust open the caches if something isn't rendered properly. After that protip, we reviewed each of the SplunkJS modules, how to instantiate them, and gave an example of each. Moving right along, we reviewed how to set tokens within the dashboard, and how to trigger changes in the display based on updates to the tokens. We customized the dashboard with CSS, and started including custom JavaScript and D3 Visualizations. The method of placing the D3 visualization in the dashboard was neither smooth nor reusable across other dashboards. We will show that configuration in the next chapter. We will cover how to make a custom...