Splunk® Enterprise

Developing Views and Apps for Splunk Web

Splunk Enterprise version 7.0 is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.

Custom visualization API reference

The custom visualization API has been updated for Splunk software version 6.5 and is now fully supported. If you are building a new custom visualization app, use the latest version of the API.

Developers whose apps use the experimental API offered with software version 6.4 are encouraged to update their apps. See API updates and migration advice for more information.

Use this reference to review custom visualization requirements, components, and configuration information.


App directory structure

To add a custom visualization to an app, put the required visualization package and configuration files into the app directory. The following layout shows required custom visualization components within an app directory. It includes Webpack configuration files.

 
appname
    appserver
        static
            visualizations
                <visualization_name>
                    src
                        visualization_source.js
                    webpack.config.js
                    visualization.js
                    visualization.css
                    formatter.html
                    package.json
                    preview.png
    default
        visualizations.conf
        savedsearches.conf
    metadata
        default.meta
    README
        savedsearches.conf.spec


App packaging

Webpack

Use Webpack to package custom visualization apps to run on the Splunk platform.

Webpack is a resource packaging tool that can build multiple app dependencies into a single package. This functionality provides isolation, encapsulation, and improved performance.

To learn more about Webpack, see https://webpack.github.io.

Template Webpack configuration

You can use or extend the custom visualization app template to build any custom visualization app. This template includes a visualization_source.js file and an initial Webpack configuration that works with npm (node.js package manager).

Webpack configuration details

The template Webpack configuration is located in the stand-in visualization package. You can find it in the following folder.
$TEMPLATE_APP_ROOT/appserver/static/visualizations/standin/.

The configuration contains the following two files.

File Description
Details
package.json npm package file.
  • Declares the visualization package dependencies and useful shortcuts for running build tasks.
webpack.config.js Webpack configuration file.
  • Defines the build entry point and the output location
  • Can be extended to load various resources into a visualization package.
  • By default, webpack.config.js defines the source entry point of the package as src/visualization_source.js and the output file as visualization.js .
  • When Webpack runs in the same directory as this configuration file, it builds the JavaScript and its dependencies together and produces a built visualization.js file.

Webpack a custom visualization

Use the Webpack configuration in the custom visualization template to build custom visualizations. After Webpack builds the custom visualization visualization.js file, the template app package can be run as an app on the Splunk platform.

Prerequisites

  • Make sure that npm is installed. To install npm, see www.npmjs.com.
  • Download the custom visualization template and review the Webpack configuration files.

Steps

  1. In the custom visualization template, rename the /standin visualization directory for the custom visualization you are building.
  2. Add your custom visualization code to visualization_source.js file.
  3. Update package.json
    • Change the visualization name to match the custom visualization you are building.
    • Add any custom visualization dependencies to the dependencies list.
    • Change the description and any other details relevant to your custom visualization.
  4. From your custom visualization directory run $ npm install.
  5. From the same directory run $ npm run build.


These steps should produce the following built visualization file.

$TEMPLATE_APP_ROOT/appserver/static/visualizations/<visualization_name>/visualization.js

Logic

Use these components to build custom visualization logic.

visualization.js

By default, this file is built from the visualization_source.js source code using Webpack.

visualization_source.js

Description
This visualization source code file contains the central logic for capturing and rendering data in the visualization. It is an AMD (Asynchronous Module Definition) module that returns an object extending SplunkVisualizationBase.

Requirements

Component Requirement details For more information see
SplunkVisualizationBase

visualization_source.js must override the following functions and options in this class.

  • getInitialDataParams. Indicates how the visualization framework fetches data for the visualization.
  • updateView. Function called to render the visualization.
SplunkVisualizationBase
SplunkVisualizationUtils Security requirement
visualization_source.js must include this utility library for safely incorporating dynamic content in visualizations.

Security utilities


SplunkVisualizationBase

The SplunkVisualizationBase class offers an API for access and communication with the Splunk platform.

Requirements

visualization_source.js extends this class. It must override the following methods and options.

updateView

This function is called whenever search results are updated or the visualization format changes. It handles visualization rendering using the following two parameters.
  • data. An object containing search result data.
  • config. An object containing visualization format information.


getInitialDataParams

This function is required for data to be returned from the search. It specifies the data output format for search results. You can also use this function to specify the maximum number of results. Use any of the following data output options.

Mode Example

Row-major

List field values as they appear in each row of the raw JSON results object array.

Returns a field name array and a row array. Each row array index contains an array representing all field values for one result.

getInitialDataParams option name

SplunkVisualizationBase.ROW_MAJOR_OUTPUT_MODE
 {
     fields: [
          { name: 'store_id' },
          { name: 'qty' },
          { name: 'product' }
      ],
      rows: [
          ['west', 400, 'shirt'],
          ['east', 625, 'mug'],
          ['north', 812, 'hat']
      ]
 }

Column-major

List field values as they appear in each column of the raw JSON results object array.

Returns a field name array and a column array. Each column array index contains an array representing all results values for one field.

getInitialDataParams option name

SplunkVisualizationBase.COLUMN_MAJOR_OUTPUT_MODE
 {
      fields: [
          { name: 'store_id' },
          { name: 'qty' },
         { name: 'product' }
      ],
      columns: [
          ['west', 'east', 'north'],
          [400, 625, 812],
          ['shirt', 'mug', 'hat']
      ]
 }

Raw format

Raw JSON object.

Returns a field name array and a results array in which each index contains a result object showing all fields and field values as key value pairs.


getInitialDataParams option name

SplunkVisualizationBase.RAW_OUTPUT_MODE


  {
      fields: [
          { name: 'store_id' },
          { name: 'qty' },
          { name: 'product' }
      ],
      results: [
          { store_id: 'west', qty: 400, product: 'shirt'},
          { store_id: 'east', qty: 625, product: 'mug'},
          { store_id: 'north', qty: 812, product: 'hat'},
      ]
  }


Interface methods

The following methods are available in SplunkVisualizationBase. See the interface code to review parameters for each method.

Method Description Override required?
initialize
  • Override to define initial data parameters that the framework should use to fetch data for the visualization.
  • The code in this method can assume that the visualization root DOM (Document Object Model) element is available as this.el.
Optional
getInitialDataParams
  • Override to define the initial data parameters used to fetch data for the visualization.
Required
onConfigChange
  • Override to implement custom handling of the config attribute changes.
  • The default behavior is to mark formatData invalid.
Optional
formatData
  • Override to implement custom data processing logic. The return value passes to updateView.
  • The data return value includes a data.meta.done Boolean flag indicating that the search job is complete.
  • Do not call this method directly in visualization_source.js. Call invalidateFormatData instead to indicate that formatData needs to run again.
  • The framework batches all invalidation methods to update the visualization efficiently.
Optional
setupView
  • Override to implement the initial view setup logic.
  • This method is called immediately before the first call to updateView.
  • Do not call this method directly in visualization_source.js.
Optional
updateView
  • Override to implement visualization rendering logic.
  • Do not call this method directly in visualization_source.js. Call invalidateUpdateView instead to indicate that updateView needs to run again.
  • The framework batches all invalidation methods to update the visualization efficiently.
Required
reflow
  • Override to implement visualization resizing logic.
  • This method is called whenever the container dimensions change. Measure this.el to determine current dimensions.
  • Do not call this method directly in visualization_source.js. Call invalidateReflow instead to indicate that reflow needs to run again.
  • The framework batches all invalidation methods to update the visualization efficiently.
Optional
remove
  • Override to perform necessary disassembly logic.
Optional
updateDataParams
  • Call this method to update the data parameters to use when fetching data. The framework fetches an updated data set.
Do not override. Treat this method as final.
drilldown
  • Call this method when a drilldown interaction happens.
Do not override. Treat this method as final.
invalidateFormatData
  • Call this method to indicate that formatData needs to run again.
  • The framework batches all invalidation methods to update the visualization efficiently.
Do not override. Treat this method as final.
invalidateUpdateView
  • Call this method to indicate that updateView needs to run again.
  • The framework batches all invalidation methods to update the visualization efficiently.
Do not override. Treat this method as final.
invalidateReflow
  • Call this method to indicate that reflow needs to run again.
  • The framework batches all invalidation methods to update the visualization efficiently.
Do not override. Treat this method as final.
getCurrentData
  • Call this method to get the current data returned by formatData.
Do not override. Treat this method as final.
getCurrentConfig
  • Call this method to get current configuration attributes.
Do not override. Treat this method as final.
getPropertyNamespaceInfo
  • Call this method to get visualization namespace information.
Do not override. Treat this method as final.
setCurrentData
  • Reserved method name.
Do not call or override.
setCurrentConfig
  • Reserved method name.
Do not call or override.

SplunkVisualizationBase public interface

SplunkVisualizationBase

define([
            'underscore',
            'backbone'
        ],
        function(
            _,
            Backbone
        ) {

    var VisualizationError = function(message) {
        this.name = 'SplunkVisualizationError';
        this.message = message || '';
        Error.apply(this, arguments);
    };

    VisualizationError.prototype = new Error();

    var SplunkVisualizationBase = function(el, appName, vizName) {
        this.el = el;
        this._config = null;
        this._data = null;
        this._appName = appName;
        this._vizName = vizName;
        this.initialize();
    };

    _.extend(SplunkVisualizationBase.prototype, Backbone.Events, {

        /**
         * Override to perform constructor logic.
         *
         * Code in initialize can assume that the visualization has been assigned
         * a root DOM element, available as `this.el`.
         */
        initialize: function() {},

        /**
         * Override to define initial data parameters that the framework should use to
         * fetch data for the visualization.
         *
         * Allowed data parameters:
         *
         * outputMode (required) the data format that the visualization expects, one of
         * - SplunkVisualizationBase.COLUMN_MAJOR_OUTPUT_MODE
         *     {
         *         fields: [
         *             { name: 'x' },
         *             { name: 'y' },
         *             { name: 'z' }
         *         ],
         *         columns: [
         *             ['a', 'b', 'c'],
         *             [4, 5, 6],
         *             [70, 80, 90]
         *         ]
         *     }
         * - SplunkVisualizationBase.ROW_MAJOR_OUTPUT_MODE
         *     {
         *         fields: [
         *             { name: 'x' },
         *             { name: 'y' },
         *             { name: 'z' }
         *         ],
         *         rows: [
         *             ['a', 4, 70],
         *             ['b', 5, 80],
         *             ['c', 6, 90]
         *         ]
         *     }
         * - SplunkVisualizationBase.RAW_OUTPUT_MODE
         *     {
         *         fields: [
         *             { name: 'x' },
         *             { name: 'y' },
         *             { name: 'z' }
         *         ],
         *         results: [
         *             { x: 'a', y: 4, z: 70 },
         *             { x: 'b', y: 5, z: 80 },
         *             { x: 'c', y: 6, z: 90 }
         *         ]
         *     }
         *
         * count (optional) how many rows of results to request, default is 1000
         *
         * offset (optional) the index of the first requested result row, default is 0
         *
         * sortKey (optional) the field name to sort the results by
         *
         * sortDirection (optional) the direction of the sort, one of:
         * - SplunkVisualizationBase.SORT_ASCENDING
         * - SplunkVisualizationBase.SORT_DESCENDING (default)
         *
         * search (optional) a post-processing search to apply to generate the results
         *
         * @param {Object} config The initial config attributes
         * @returns {Object}
         *
         */
        getInitialDataParams: function(config) {
            return {};
        },

        /**
         * Override to implement custom handling of config attribute changes.
         *
         * Default behavior is to mark the formatData routine invalid.
         *
         * @param {Object} configChanges The changed config attributes, an object with
         *     changed keys mapping to their new values
         * @param {Object} previousConfig The previous config attributes
         */
        onConfigChange: function(configChanges, previousConfig) {
            this.invalidateFormatData();
        },

        /**
         * Override to implement custom data processing logic.
         *
         * The return value of this method will be passed to the updateView routine.
         * This method should not be called directly by visualization code, call
         * invalidateFormatData instead to notify the framework that the formatData
         * routine needs to be run again.
         *
         * @param {Object} rawData The data in its raw form
         * @param {Object} config The current config attributes
         * @returns {*}
         */
        formatData: function(rawData, config) {
            return rawData;
        },

        /**
         * Override to implement one-time view setup logic.
         *
         * This method will be called immediately before the first call to the
         * updateView routine.
         * This method should not be called directly by visualization code.
         */
        setupView: function() {},

        /**
         * Override to implement visualization rendering logic.
         *
         * This method should not be called directly by visualization code, call
         * invalidateUpdateView instead to notify the framework that the updateView
         * routine needs to be run again.
         *
         * @param {*} data The formatted data, as returned by the formatData routine
         * @param {Object} config The current config attributes
         * @param {Function} async A function that notifies the framework that the
         *    visualization will update asynchronously.
         *    If all updates are occurring synchronously within updateView,
         *    the `async` parameter can be ignored.
         *    If any updates are asynchronous (e.g. animations), call async() and
         *    use the return value as a callback to signal that the update has completed:
         *
         *    updateView: function(data, config, async) {
         *        var done = async();
         *        this.performAsyncUpdates({
         *            onComplete: done
         *        });
         *    }
         */
        updateView: function(data, config, async) {},

        /**
         * Override to implement visualization resizing logic.
         *
         * This method will be called whenever the container dimensions change.
         * The current container dimensions can be obtained by measuring `this.el`.
         * This method should not be called directly by visualization code, call
         * invalidateReflow instead to notify the framework that the reflow
         * routine needs to be run again.
         *
         */
        reflow: function() {},

        /**
         * Override to perform all necessary teardown logic.
         */
        remove: function() {},

        /**
         * Call this method to update the data parameters to be used when fetching data,
         * the framework will fetch an updated data set.
         *
         * This method should be treated as final.
         *
         * @param {Object} newParams New data parameters, to be merged with the existing ones.
         *     See getInitialData above for a description of allowed inputs.
         */
        updateDataParams: function(newParams) {
            this.trigger('updateDataParams', newParams);
        },

        /**
         * Call this method to notify the framework of a drilldown interaction.
         *
         * @param payload {Object} a description of the "intention" of the drilldown interaction.
         *
         * Two different type of drilldown action are supported:
         *
         * 1) Field-value pair drilldown, where the "intention" is to filter the results by
         *    setting one or more field-value pairs as constraints, e.g.
         *
         *    this.drilldown({
         *        action: SplunkVisualizationBase.FIELD_VALUE_DRILLDOWN,
         *        data: {
         *            fieldOne: valueOne,
         *            fieldTwo: valueTwo,
         *            ...
         *        }
         *    });
         *
         * 2) Geo-spatial drilldown, where the "intention" is to filter the results to a
         *    geo-spatial region, e.g.
         *
         *    this.drilldown({
         *        action: SplunkVisualizationBase.GEOSPATIAL_DRILLDOWN,
         *        data: {
         *            lat: {
         *                name: <name of latitude field>
         *                value: <value of latitude field>
         *            },
         *            lon: {
         *                name: <name of longitude field>
         *                value: <value of longitude field>
         *            },
         *            bounds: [<south>, <west>, <north>, <east>]
         *        }
         *    });
         *
         * Additionally, the "intention" can filter the results to a specific time range.
         * The time range can be combined with any of the actions above, e.g.
         *
         *    this.drilldown({
         *        earliest: '1981-08-18T00:00:00.000-07:00',
         *        latest: '1981-08-19T00:00:00.000-07:00'
         *        // optionally an `action` and `data`
         *    });
         *
         * The `earliest` and `latest` values can be ISO timestamps in the
         * format above, or as epoch times.
         *
         * @param originalEvent {Event} (optional) the original browser event that initiated the
         *     interaction, used to support keyboard modifiers.
         *
         * This method should be treated as final.
         */

        drilldown: function(payload, originalEvent) {
            this.trigger('drilldown', payload, originalEvent);
        },

        /**
         * Call this method to notify the framework that the formatData routine needs to run again.
         *
         * The framework batches calls to this and other invalidation methods so that
         * the visualization will be updated efficiently.
         *
         * This method should be treated as final.
         */
        invalidateFormatData: function() {
            this.trigger('invalidateFormatData');
        },

        /**
         * Call this method to notify the framework that the updateView routine needs to run again.
         *
         * The framework batches calls to this and other invalidation methods so that
         * the visualization will be updated efficiently.
         *
         * This method should be treated as final.
         */
        invalidateUpdateView: function() {
            this.trigger('invalidateUpdateView');
        },

        /**
         * Call this method to notify the framework that the reflow routine needs to run again.
         *
         * The framework batches calls to this and other invalidation methods so that
         * the visualization will be updated efficiently.
         *
         * This method should be treated as final.
         */
        invalidateReflow: function() {
            this.trigger('invalidateReflow');
        },

        /**
         * Call this method to get the current data, as returned by the formatData routine.
         * Cannot be called in initialize.
         *
         * This method should be treated as final.
         *
         * @returns {*}
         */
        getCurrentData: function() {
            return this._data;
        },

        /**
         * Call this method to get the current config attributes.
         * Cannot be called in initialize.
         *
         * This method should be treated as final.
         *
         * @returns {Object}
         */
        getCurrentConfig: function() {
            return this._config;
        },

        /**
         * Call this method to get info about the viz namespace.
         *
         * This method should be treated as final.
         *
         * @returns {
         *     appName: <string>,
         *     vizName: <string>,
         *     propertyNamespace: <string>
         * }
         */
        getPropertyNamespaceInfo: function() {
            return {
                appName: this._appName,
                vizName: this._vizName,
                propertyNamespace: 'display.visualizations.custom.' + this._appName + '.' + this._vizName + '.'
            };
        },        

        /**
         * Used internally for communication between the framework and the visualization.
         *
         * This method should be treated as final, and should not be called by visualization code.
         */
        setCurrentData: function(data) {
            this._data = data;
        },

        /**
         * Used internally for communication between the framework and the visualization.
         *
         * This method should be treated as final, and should not be called by visualization code.
         */
        setCurrentConfig: function(config) {
            this._config = config;
        }

    });

    _.extend(SplunkVisualizationBase, {
        extend: Backbone.View.extend,

        COLUMN_MAJOR_OUTPUT_MODE: 'json_cols',
        ROW_MAJOR_OUTPUT_MODE: 'json_rows',
        RAW_OUTPUT_MODE: 'json',

        FIELD_VALUE_DRILLDOWN: 'fieldvalue',
        GEOSPATIAL_DRILLDOWN: 'geoviz',

        SORT_ASCENDING: 'asc',
        SORT_DESCENDING: 'desc',

        // Defines a custom error type to be thrown by sub-class in order to
        // propagate an error message up to the user of the visualization, e.g.
        //
        // if (data.columns.length < 2) {
        //     throw new SplunkVisualizationBase.VisualizationError(
        //         'This visualization requires at least two columns of data.'
        //     );
        // }
        VisualizationError: VisualizationError
    });

    return SplunkVisualizationBase;
});

Drilldown options

Use the provided drilldown function in SplunkVisualizationBase to implement a time based or field-value drilldown. You can also combine these drilldown types.

Time based drilldown

A time based drilldown lets users click on the visualization to open a search over the time range that the clicked area represents. Determine the earliest and latest time. Call this.drilldown and pass the time parameters to the drilldown function.

Here is an example that incorporates a helper function.

/**
 * To be called from the visualization's click handler, after computing the
 * correct time range from the target of the click.
 *
 * @param earliestTime - the lower bound of the time range,
 *          can be an ISO-8601 timestamp or an epoch time in seconds.
 * @param latestTime - the upper bound of the time range,
 *          can be an ISO-8601 timestamp or an epoch time in seconds.
 * @param browserEvent - the original browser event that caused the drilldown
 *
 * example usage:
 *
 * this.drilldownToTimeRange('1981-08-18T00:00:00.000-07:00', '1981-08-19T00:00:00.000-07:00', e);
 */
drilldownToTimeRange: function(earliestTime, latestTime, browserEvent) {
    this.drilldown({
        earliest: earliestTime,
        latest: latestTime
    }, browserEvent);
}


Field-value drilldown
A field-value drilldown lets users click on the visualization to open a search using one or more category name and value pairs that the clicked area represents. Determine the category names and values. Call this.drilldown and pass the name and value parameters to the drilldown function.

Here is an example that incorporates a helper function. This example uses one field-value pair but the custom visualizations API supports using multiple pairs.

/**
 * To be called from the visualization's click handler, after computing the
 * correct category name and value from the target of the click.
 *
 * @param categoryName - the field name for the category
 * @param categoryFieldValue - the value for the category
 * @param browserEvent - the original browser event that caused the drilldown
 *
 * example usage:
 *
 * this.drilldownToTimeRange('State', 'Oregon', e);
 */
drilldownToCategory: function(categoryName, categoryFieldValue, browserEvent) {
    var data = {};
    data[categoryName] = categoryFieldValue;

    this.drilldown({
        action: SplunkVisualizationBase.FIELD_VALUE_DRILLDOWN,
        data: data
    }, browserEvent);
}


Time based and field-value drilldown example

You can combine the two drilldown options as shown in this example.

drilldownToTimeRangeAndCategory: function(earliestTime, latestTime, categoryName, categoryValue, browserEvent) {
    var data = {};
    data[categoryName] = categoryValue;

    this.drilldown({
        action: SplunkVisualizationBase.FIELD_VALUE_DRILLDOWN,
        data: data,
        earliest: earliestTime,
        latest: latestTime
    }, browserEvent);
}

Utility functions

The SplunkVisualizationUtils class provides utility and security functions for custom visualizations. In addition to the following utility functions, see Security utilities for information on required security functions.

Utility

The following utility functions are available in SplunkVisualizationUtils.

Function Description Arguments Returns
getColorPalette Get a predefined color palette for categorical or semantic colors. See Design guidelines for more details on color palettes. name(String)
Use of the following palette names.
  • splunkCategorical (default)
  • splunkSemantic
Array of color strings in the specified palette. If no argument is provided, the function returns the splunkCategorical color palette.
parseTimestamp Use this function whenever a date is initialized with a timestamp. The function must be used to show the correct server date and time to a user. timestamp (ISO string object) Timezone-corrected javaScript date object. If a non-ISO string is provided, the function returns a date. Timezone correction is not possible in this case.
normalizeBoolean Use this function for strict normalization of a String to a Boolean.

The following values are handled as true.

String (case-insensitive): "true", "on", "yes", "1"
Integer: 1
Boolean: true

The following values are treated as false.

String (case-insensitive): "false", "off", "no", "0"
Integer: 0
Boolean: false

value (String, Integer, or Boolean). Value to be normalized.

options (Object). Default value to return if the expression is not valid.

When a valid boolean expression is submitted, returns the normalized result. If the expression is not valid, returns the options value. If options is not specified, returns false.

Security utilities

It is a best practice to sanitize dynamic content. If you create a custom visualization app and add it to Splunkbase, dynamic content must be sanitized for your app to pass AppInspect.

Splunk platform searches can have unconstrained data outputs. This means that any data that you present in any context might be malicious. The SplunkVisualizationUtils library addresses the following common risks.

  • XSS (Cross-site scripting) injection into the DOM (Document Object Model)
  • XSS injection using unsafe URL schemes


Requirements

Make sure that visualization_source.js meets the following security requirements.

Requirement Utility function to use What to do
Prevent XSS injection. escapeHtml(inputString)

Before adding any strings to the DOM, pass them through this SplunkVisualizationUtils function.

If you are using a framework that handles HTML escaping automatically, you do not have to use this function in addition.

Strip dynamic content from unsafe URL schemes. makeSafeUrl(inputUrl)

This SplunkVisualizationUtils function is required to pass AppInspect if the custom visualization displays links with dynamic URLs.

Examples

The following examples show you how to use security utility functions in visualization_source.js.

escapeHtml usage example

define([
    'api/SplunkVisualizationBase',
    'api/SplunkVisualizationUtils'
],
function(
    SplunkVisualizationBase,
    SplunkVisualizationUtils
) {
    var SampleViz = SplunkVisualizationBase.extend({
        getInitialDataParams: function() {
            return { outputMode: SplunkVisualizationBase.COLUMN_MAJOR_OUTPUT_MODE };
        },
        updateView: function(data, config) {
            // Both the title and the data point are dynamic values that could potentially
            // contain malicious content (e.g. "<script>alert(1)</script>").
            // The escapeHTML function will encode them so that they can safely
            // be inserted into the DOM.
            var title = config['display.visualizations.custom.sampleApp.sampleViz.title'];
            this.el.innerHTML = '<h1>' + SplunkVisualizationUtils.escapeHtml(title) + '</h1>';
            var dataPoint = data.columns[0][0];
            this.el.innerHTML += '<p>' + SplunkVisualizationUtils.escapeHtml(dataPoint) + '</p>';
        }
    });

    return SampleViz;
});


makeSafeUrl usage example

define([
    'api/SplunkVisualizationBase',
    'api/SplunkVisualizationUtils'
],
function(
    SplunkVisualizationBase,
    SplunkVisualizationUtils
) {
    var SampleViz = SplunkVisualizationBase.extend({
        getInitialDataParams: function() {
            return { outputMode: SplunkVisualizationBase.COLUMN_MAJOR_OUTPUT_MODE };
        },
        updateView: function(data, config) {
            var dataPoint = data.columns[0][0];
            this.el.innerHTML = '<p>' + SplunkVisualizationUtils.escapeHtml(dataPoint) + '</p>';
            var seeMoreUrl = config['display.visualizations.custom.sampleApp.sampleViz.seeMoreUrl'];
            var seeMoreLink = document.createElement('a');
            seeMoreLink.innerHTML = 'See More';
            // The "see more" URL is a dynamic value that could potentially contain
            // a malicious URL (e.g. "javscript:alert(1)").
            // The makeSafeUrl function will strip out any un-safe URL schemes.
            seeMoreLink.setAttribute('href', SplunkVisualizationUtils.makeSafeUrl(seeMoreUrl));
            this.el.appendChild(seeMoreLink);
        }
    });

    return SampleViz;
});



User interface

Use these components to build a custom visualization user interface.

visualization.css

Description
This file contains CSS rules relevant to the visualization.

Guidelines

  • The file should contain standard CSS.
  • The Splunk platform picks up visualization.css automatically. The CSS file does not need to be pulled in by the visualization.
  • Use class attributes instead of id attributes to define CSS rules. Dashboards can contain multiple instances of the same visualization.
  • Use namespacing to avoid CSS class name conflict. See the following CSS rule namespacing requirements.


CSS class namespacing requirements
Dashboards can contain multiple visualizations. Scope CSS rules so that they are applied correctly. Use these best practices for constraining CSS rules.

Best practice What to do
If possible, scope all styles by adding a class name unique to the root DOM element. Include the app and visualization context in the class name as shown in this example.

.splunk-custom-horizon-chart .axis {

 // axis styles here

}

Another option is to create a class name unique to the app and visualization. For example, use

.splunk-horizon-chart-axis instead of .axis.

Example visualization.css
This CSS file contains text rules using prefixed classes.


.custom-radial-meter-chart .center-text {
    font-size: 45px;
    font-weight: 200;
    font-family: "Helvetica Neue", Helvetica, sans-serif;
}
.custom-radial-meter-chart .under-text {
    font-size: 20px;
    font-weight: 100;
    font-family: "Helvetica Neue", Helvetica, sans-serif;
}


formatter.html

Description
Contains HTML to render in the visualization format menu. Input elements in the HTML can specify properties to edit. These changes are passed to the visualization.

Guidelines

  • The formatter.html file can contain any of the following components.
    • Multiple forms to render multiple tabs.
    • HTML only
    • Splunk platform web components.
  • Name input elements according to the namespaced property that they affect. When inputs update the corresponding namespaced property in the page, the changes pass to the visualization.
  • Use the following case-sensitive namespace element and syntax to specify a property.
    {{VIZ_NAMESPACE}}.<property name>

    The {{VIZ_NAMESPACE}} element is replaced with the namespaced portion of a property name. When combined with the property name, it works equivalently to a fully-qualified namespace.

    The fully-qualified namespace syntax previously used for properties is also still supported.

    display.visualizations.custom.<app name>.<viz name>.<property name>


For complete details, see the Formatter API reference.


preview.png

Description
PNG image file used in the Visualization Picker user interface. Users see the image and custom visualization name when choosing a visualization.

Guidelines

  • For best results the image size should be 116px wide by 76px high.
  • Only PNG formatted images are accepted.
  • This file is not used as the app icon. To add an icon, see the following instructions.


Adding an app icon and screenshot image

  1. Save a 36px by 36px PNG icon image as appIcon.png. Follow the pixel dimensions and file name case and spelling exactly.
  2. (Optional). To add a screenshot, save a 623px by 350px PNG image as screenshot.png. Follow the pixel dimensions and file name case and spelling exactly.
  3. Place the appIcon.png and screenshot.png files in the <app_name>/appserver/static directory.



Configuration and access control

Use these components to define custom visualization configurations and access control.

visualizations.conf

Description
To make custom visualizations available across a Splunk deployment, declare them in visualizations.conf.

Requirements

  • Create a stanza for each visualization in visualizations.conf. Add the settings for loading the visualization and making it available in Splunk Web.
  • Every visualization in an app must have a stanza in the visualizations.conf file. The stanza name and the label attribute are required but there are other optional settings. See the following settings list.

Available settings

Setting Description Required?
label Public label used throughout Splunk Web to refer to the visualization. Yes
default_height Default visualization height. No. Defaults to 250 if unspecified.
description Brief description for the visualization, appearing in Splunk Web. No
search_fragment Brief search portion to indicate how to structure results for the visualization. Used in Splunk Web. No
allow_user_selection Whether the visualization should be available for users to select in Splunk Web. No. Defaults to true, meaning that the visualization is available. A true setting can be overridden if disabled is set to 1.
disabled If set to 1, the visualization is not available anywhere in the Splunk platform. In this case, the disabled setting overrides a true setting for allow_user_selection. No. Defaults to 0 if unspecified, meaning that the visualization is available.
supports_trellis Indicates whether trellis layout is available for this visualization. No. Defaults to false
supports_drilldown Indicates whether drilldown can be configured for this visualization in the drilldown editor user interface. No. Defaults to false


Example visualizations.conf

This example defines two different visualizations in two stanzas. The first stanza includes all available settings. The second stanza includes only the required settings.

[first_example_visualization]
label = First example
description = Use this visualization for making example charts.
default_height = 500
search_fragment = | stats count by a, b, c, d
 
[second_example_visualization]
label = Second example

savedsearches.conf

Description
Use savedsearches.conf to indicate visualization property default values.

  • Note: Set property defaults and handle user-configured property values in visualization_source.js.


Requirements

  • Specify properties by their complete namespace. See the example below for more details.


Example savedsearched.conf
This example sets default values for two properties.

display.visualizations.custom.viz_sample_app.sample_viz.numericProperty = 100
display.visualizations.custom.viz_sample_app.sample_viz.stringProperty = stringDefault

default.meta

Description
Use this file to export visualizations to the system. For additional details, see the default.meta configuration spec file in the Admin Manual.

savedsearches.conf.spec

Description
Use this file to declare visualization properties.

  • Note: Set property defaults and handle user-configured property values in visualization_source.js.


Requirements

  • Declare all properties in this file to ensure proper handling. Properties not declared in savedsearches.conf.spec are treated as invalid and prompt warnings at startup if they are used in reports.


Example savedsearched.conf.spec
This example declares two properties.

display.visualizations.custom.viz_sample_app.sample_viz.numericProperty = <float>
display.visualizations.custom.viz_sample_app.sample_viz.stringProperty = <string>

Documentation

Add documentation for each custom visualization in an app.

Add a README.md file to the <visualization_name> folder. Include details for an admin and end user audience. You can follow this template to cover necessary information.

Documentation template

Documentation area What to include
Visualization introduction
  • Visualization title
  • Overview of how the visualization works to represent data
  • Details about what kind of data works best for the visualization
  • Brief use case examples
Search and data formatting
  • How to write queries that generate results in the proper data structure or format for this visualization
  • Example queries
Visualization components
  • How different components add meaning or information to the visualization. For example, describe sparklines and trend indicators in a single value visualization.
Customization options
  • How to use the Format menu to customize and configure the visualization
Simple XML
  • List and define any visualization-specific Simple XML options
  • Document full option names, data type, and any rules for accepted values
  • Example configuration to demonstrate correct usage
Drilldown
  • Details of using drilldown with the visualization
Extensions
  • Details of extending or customizing the visualization using available frameworks.
Permissions or other administrative information
  • Details for admins about managing the app for end users
Support contact
  • Developer email or other contact details to use for questions and feedback
Software credits
  • Include citation details for third party software libraries or other tools used in the app. For example: https://d3js.org/



Additional API interactions

You can use custom visualizations in SimpleXML dashboards and SplunkJS.

Simple XML

You can include custom visualizations in Simple XML dashboards. For more information see Use custom visualizations in Simple XML.


SplunkJS

Custom visualization components registered with the system are accessible from SplunkJS. For more information see Use custom visualizations in SplunkJS.



Additional resources

For design and data handling best practices, see the following topics.

Last modified on 31 August, 2018
Build a custom visualization   Formatter API reference

This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10


Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters