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 |
|
---|---|---|
package.json
|
npm package file.
|
|
webpack.config.js
|
Webpack configuration 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 installnpm
, see www.npmjs.com. - Download the custom visualization template and review the Webpack configuration files.
Steps
- In the custom visualization template, rename the
/standin
visualization directory for the custom visualization you are building. - Add your custom visualization code to
visualization_source.js
file. - 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.
- From your custom visualization directory run
$ npm install
. - 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 |
|
SplunkVisualizationBase |
SplunkVisualizationUtils | Security requirementvisualization_source.js must include this utility library for safely incorporating dynamic content in visualizations.
|
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.
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.
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.
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
|
|
Optional |
getInitialDataParams
|
|
Required |
onConfigChange
|
|
Optional |
formatData
|
|
Optional |
setupView
|
|
Optional |
updateView
|
|
Required |
reflow
|
|
Optional |
remove
|
|
Optional |
updateDataParams
|
|
Do not override. Treat this method as final. |
drilldown
|
|
Do not override. Treat this method as final. |
invalidateFormatData
|
|
Do not override. Treat this method as final. |
invalidateUpdateView
|
|
Do not override. Treat this method as final. |
invalidateReflow
|
|
Do not override. Treat this method as final. |
getCurrentData
|
|
Do not override. Treat this method as final. |
getCurrentConfig
|
|
Do not override. Treat this method as final. |
getPropertyNamespaceInfo
|
|
Do not override. Treat this method as final. |
setCurrentData
|
|
Do not call or override. |
setCurrentConfig
|
|
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), required.Use of the following palette names:
|
Array of color strings in the specified palette. If no argument is provided, the function returns the splunkCategorical color palette. Adding a theme option, for example, dark , will return the semantic and categorical color palettes available for dark theme.
|
getCurrentTheme
|
Use this function to return the current active theme. | Returns dark or light .
| |
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): |
|
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
Developers are required to sanitize dynamic content for custom visualization app certification.
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 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 |
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
|
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
- Save a 36px by 36px PNG icon image as appIcon.png. Follow the pixel dimensions and file name case and spelling exactly.
- (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.
- 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 thelabel
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 |
|
Search and data formatting |
|
Visualization components |
|
Customization options |
|
Simple XML |
|
Drilldown |
|
Extensions |
|
Permissions or other administrative information |
|
Support contact |
|
Software credits |
|
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.
Build a custom visualization | Formatter API reference |
This documentation applies to the following versions of Splunk Cloud Platform™: 9.2.2406 (latest FedRAMP release), 8.2.2202, 8.2.2203, 8.2.2112, 8.2.2201, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403
Feedback submitted, thanks!