How to create a custom Splunk view

While the Web Framework provides many built-in views to visualize your data, you can also create your own custom views as you would any JavaScript object. With a custom view, you can display Splunk events using a third-party data visualization and encapsulate the process of transforming the data into the format that the data visualization expects.

While you can go it alone and write your custom view from scratch, the Web Framework includes a base class (a Backbone view), SimpleSplunkView, from which you can inherit these built-in features:

  • Methods to create and render the view, and format data.
  • Integration with search managers, including access to the search results model and search progress notifications.
  • Automatic updates to the view whenever its associated search changes. For example, if a search property changes, the search is run again and the view is automatically updated with the new search results.
  • Errors and messages, to help you troubleshoot (for example, console messages indicating when a search fails to run).

Use these features as a starting point, then build on them as you need to.

The basic steps for creating a custom view are:

Write the JavaScript class for the custom view

To specify how to display the data from Splunk, define a custom view by creating a class that inherits from the SimpleSplunkView base class, then save your JavaScript code to the $SPLUNK_HOME/etc/apps/your_app_name/appserver/static/ directory.

The SimpleSplunkView base class contains several methods that you override as needed:

  • initialize: Constructor.
  • formatData: Formats results data from Splunk and returns a handle to the data, which is then passed to the updateView method as the second argument. When you don't override this method, data is passed in the output format that is specified by the output_mode property (such as json, json_rows, or json_cols).
  • formatResults: Same as formatData, except that it lets you format the entire results model object (rather than just the data portion).
  • displayMessage: Lets you render messages in a custom way.
  • createView: Configures the custom vizualization and returns a handle to it, which is then passed to the updateView method as the first argument. This method is called once.
  • updateView: Puts Splunk data (returned by the formatData method) into the view (returned by the createView method) and renders it. This method is called automatically whenever Splunk data changes, for example when a search is run again.
  • clearView: Resets rendering.
  • render: Creates the initial view and draws it on the screen. On subsequent calls, runs a full update cycle by calling formatResults, formatData, then updateView.

Here's a typical structure of a custom view:

// Custom view
define(function(require, exports, module) {
    var _ = require("underscore");
    var mvc = require("splunkjs/mvc");
    var SimpleSplunkView = require("splunkjs/mvc/simplesplunkview");

    var ViewName = SimpleSplunkView.extend({
        className: "view_name",

        // Set options for the visualization
        options: {
            data: "preview",  // The data results model from a search
            foo: "bar"
        },

        // Override this method to configure the view
        createView: function() {
            // TODO: Create a visualization
            return viz;
        },

        // Override this method to format the data for the view
        formatData: function(data) {
            // TODO: Format the data
            return data;
        },

        // Override this method to put the formatted Splunk data into the view
        updateView: function(viz, data) {
            // TODO: Display the data in the view
        }
    });

    return ViewName;

});

Instantiate the custom view

Instantiate the custom view in JavaScript as follows:

require([
    "splunkjs/mvc",
    "your_app_name/view_name",
    "splunkjs/mvc/simplexml/ready!"
], function(mvc, CustomView) {

    // Create a custom view
    var customView = new CustomView({
        name: "mycustomview",
        managerid: "mysearch",
        el: $("#mycustomview")
    }).render();
});

For more

For end-to-end examples of creating a custom view, see the Custom view tutorial.