Install the Add-on Builder

The Splunk Add-on Builder is only intended for use on a single-instance development environment, such as a laptop.

Notes

• Do not install the Splunk Add-on Builder app in a production Splunk environment with real users.
• Do not install the Splunk Add-on Builder app in a search head cluster or index cluster environment.

Requirements

Requirements for the Splunk Add-on Builder:

• Splunk Enterprise

Splunk Enterprise 6.4 or later is required, running on a single-instance development environment such as a laptop.

Splunk Light is not supported.

Add-on Builder is not supported in a search head cluster or index cluster environment.

The Add-on Builder does not require a paid Enterprise license. You can use the Free license. However, consider getting a Splunk Developer License to work with more data.

For more about Splunk Enterprise system requirements, see System Requirements in the Splunk Enterprise Installation Manual.

• Mozilla Firefox, Google Chrome, or Microsoft Internet Explorer 11
• Admin privileges on Splunk Enterprise

Without admin privileges, you cannot create an add-on project, or create and run modular inputs for data collection.

• The Splunk Common Information Model (CIM) add-on

The CIM add-on version 4.6 or later is required for CIM mapping and creating adaptive response alerts.

• Download the Splunk Common Information Model add-on from Splunkbase.
• For details about installation, see Install the Splunk Common Information Model Add-on.

The CIM add-on 4.6 or later is also required for end users of your add-on to run adaptive response actions.

Performance tips

• While developing data inputs, consider disabling those inputs that you do not need. Multiple data inputs scheduled to run at frequent intervals can consume system resources.
• Running more than 10 add-ons in your development environment might negatively impact Add-on Builder's performance.

Download and install the Splunk Add-on Builder app

1. Download the Splunk Add-on Builder from Splunkbase.
2. Log into Splunk Web.
3. Click the Manage Apps icon.
4. On the Apps page, click Install app from file.
5. Click Choose File, navigate to and select the Splunk Add-on Builder package file, then click Open.
6. Click Upload.

To install the Splunk Add-on Builder app from the command line:

• At the command line, enter:

splunk install app <path>/<packagefilename>

• Alternatively, unpack the file and then copy the /splunk_app_addon-builder directory to $SPLUNK_HOME/etc/apps.

Ensure that the /splunk_app_addon-builder directory and its files have proper permissions and ownership so that Splunk Enterprise can read and write to them.

Upgrade the Splunk Add-on Builder app

When upgrading the Add-on Builder app, use Splunk Web.

Note  Do not delete the $SPLUNK_HOME/etc/apps/splunk_app_addon-builder folder directly before upgrading the app, or else your previously-created Add-on Builder projects will no longer be configurable within the Add-on Builder.

1. Download the Splunk Add-on Builder from Splunkbase.
2. Log into Splunk Web.
3. Click the Manage Apps icon.
4. On the Apps page, click Install app from file.
5. Click Choose File, navigate to and select the Splunk Add-on Builder package file, then click Open.
6. Select Upgrade app.
7. Click Upload.

Share data in Splunk Add-on Builder

The first time you run Add-on Builder, a message is displayed requesting you to opt in to send anonymized usage data to Splunk to help improve the app in future releases.

How data is collected

If you opt in, the app enables an internal library to track basic usage and crash information. The library uses browser cookies to track uniqueness and sessions of app users, then sends events to Splunk using XHR in JSON format.

Usage data that is collected

Fields common to all events

The data that the Add-on Builder sends to Splunk includes the following fields that are common to all events.

Field	Type	Description	Example value
apiKey	string	The MINT API key for the Splunk Add-on Builder.	"4t2fk73n"
appRunningSate	string	Not used.	"NA "
appVersionCode	string	Not used.	"NA"
appVersionName	string	The version of the Splunk Add-on Builder.	"2.1.0"
browser	string	The browser name.	"chrome"
browserVersion	string	The browser version.	"47.0.2526.111"
carrier	string	Not used.	"NA"
connection	string	Not used.	"NA"
device	string	The type of device used.	"MacIntel"
extraData	object	The version of Splunk Enterprise.	{"splunk_version": "6.3.2"}
locale	string	The user locale set in the browser.	"en-US".
osVersion	string	The version of the operating system.	"OS X 10.11.2"
packageName	string	The package name of the Splunk Add-on Builder.	"splunk_app_addon-builder"
platform	string	The platform.	"web"
remoteIP	string	Not used.	"NA"
screenOrientation	string	Not used.	"NA"
sdkVersion	string	The version of the internal library.	"4.3"
session_id	string	A unique session identifier.	"a5026251"
state	string	Indicates whether the browser is online.	"CONNECTED" or "DISCONNECTED"
userIdentifier	string	Not used.	"NA"
uuid	UUID	A random identifier that tracks the user uniqueness.	"b1da8edd-6eb5-4620-8fed-6f2e01e2800f"

Additional fields

In addition to fields common to all events, the Splunk Add-on Builder sends the following fields to Splunk when usage data is enabled.

Event	Source Type	Description	Data (along with common fields)
			Field	Type	Description
Session start	mint:ping	Each ping event indicates that a new session has started.	fsEncrypted	N/A	Not used, always "NA"
			rooted	N/A	Not used, always false
Session end	mint:gnip	Each gnip event indicates that a session has ended.	ses_duration	int	How long the session lasted.
Page views	mint:view	Triggered once per page view in the app.	current	string	The URL of the current web page, without the hostname.
			currentView	string	Not used. Hardcoded to "examples".
			domProcessingTime	int	Time spent to process the domain.
			domLookupTime	int	Time spent to look up the domain name.
			elapsedTime	int	Time spent to render the page.
			loadTime	int	Time spent to load the page.
			previous	string	The referrer URL.
			serverTime	int	Time spent to get a response from the server.
App performance and configuration	mint:log	Usage and performance logs for the Add-on Builder that track dashboard memory usage, dashboard loading times, the number of accounts, inputs, and regions configured in the app, and non-sensitive input configuration parameters.	level	int	Log level. For example, 60 means "error".
			log_name	any	Log content. See examples below.
API calls	mint:network	XMLHTTPRequest calls, usually HTTP API calls from client side (browser) to the Splunk server.	failed	boolean	Indicates whether the request failed.
			latency	int	Time spent before the response was received.
			protocol	string	Network protocol (http or https).
			requestLength	string	N/A. Not used.
			responseLength	int	The size of the response.
			statusCode	string	HTTP response code.
			url	string	The request URL, without the hostname.

Example app performance and configuration events

The Add-on Builder sends performance and configuration information using the log_name field in the mint:log source type. This log_name field contains two sub-fields, name, which indicates which type of logs are being transmitted, and data, the content of the tracking log.

The following examples demonstrate what data the Add-on Builder sends for each type of event.

Log name	Example JSON object
track_performance Tracks dashboard performance for memory usage and loading times.	{ "memory":{ "totalJSHeapSize":72200000, "usedJSHeapSize":39600000, "jsHeapSizeLimit":1620000000 }, "timing":{ "navigationStart":1453273923766, "unloadEventStart":1453273923929, "unloadEventEnd":1453273923930, "redirectStart":0, "redirectEnd":0, "fetchStart":1453273923766, "domainLookupStart":1453273923766, "domainLookupEnd":1453273923766, "connectStart":1453273923766, "connectEnd":1453273923766, "secureConnectionStart":0, "requestStart":1453273923773, "responseStart":1453273923927, "responseEnd":1453273923929, "domLoading":1453273923939, "domInteractive":1453273923975, "domContentLoadedEventStart":1453273923975, "domContentLoadedEventEnd":1453273923975, "domComplete":1453273926985, "loadEventStart":1453273926985, "loadEventEnd":1453273926987 } }
track_addon_builder_summary Tracks information about add-ons created by the Add-on Builder.	[{ "author": "splunk", "id": "Splunk_TA_test_panda", "is_validated": "not validated", "last_modified": "2016/10/26", "name": "test panda", "version": "1.0.0", "visible": true }]
track_addon_summary Tracks information about one add-on, such as data inputs, alert actions, event types, CIM mappings, source types, and so forth.	{ sourcetype: [{ data_format: "unstructured_data" event_count:"4584" has_cimmapping:false has_field_extraction:false input_name:"dsfsdafdsa" input_type:"rest" sourcetype:"fdsafdsafdsafdsa" }], modular_alert: [{ "description": "Send HipChat room notifications", "short_name": "hipchat", "label": "HipChat", "active_response": { "group": [ "information gathering", "information conve" ], "task": [ "block" ], "technology": [ { "product": "endpoint", "version": [ "1.0" ], "vendor": "symantec" } ], "subject": [ "router", "firewall" ] }, "alert_props": { "payload_format": "json", "is_custom": 1 }, "parameters": [ { "default_value": "message", "name": "notification_type", "required": true, "help_string": "Choose style of HipChat notification.", "possible_values": { "Application Card": "card", "Message": "message" }, "label": "Notification Style", "format_type": "dropdownlist" }, { "label": "Card Attributes", "required": false, "help_string": "", "name": "card_attributes", "format_type": "text" }, { "label": "Message Format", "required": false, "possible_values": { "Html": "html", "Plain Text": "plain" }, "name": "message_format", "format_type": "radio" }, { "default_value": "red", "name": "color", "required": false, "help_string": "", "possible_values": { "None": " ", "Purple": "purple", "random": "random", "Grey": "grey", "Yellow": "yellow", "Green": "green", "Red": "red" }, "label": "Message Color", "format_type": "dropdownlist" }, { "label": "Notify users in the room", "required": false, "name": "notify", "format_type": "checkbox" } ] }], event_type:[{ "name": "test_event_type" }], cim_mapping:[{ "event_type": "test_eventtype", "event_field": "date_year", "eval": "date_year", "cim": "Alerts", "cim_field": "dest" }] }
track_package Tracks whether the user has downloaded the add-on package.	{ app_name: 'test addon' }
track_validation Tracks validation performance and information.	{ timeStart: 1477547657730, timeEnd: 1477547658745, score: 90, categories: ['field_extraction', 'app_inspect'], num_of_warnings: 10, num_of_errors: 0, num_of_passes: 100, app_name:'ta-test' }
track_field_extraction Tracks field extraction performance and information.	{ timeStart: 1477547657730, timeEnd: 1477547658745, sourcetype: 'test:table', num_of_events: 9933, format: 'unstructured_data', app_name:'ta-test' }
track_step_view Tracks which steps the user has accessed, and possibly the amount of time spent on each step.	{ view: 'field-extraction', page: 'tab_main_flow.html', action: 'edit' }
track_step_view_wizard Tracks which steps the user has accessed in a wizard, and possibly the amount of time spent on each step.	{ view: 'data-collection', wizard_step_name: 'chooseMethod', isEditing: false }
track_creation Tracks the creation of add-on items, such as data inputs and alert actions.	{ type: 'add-on', data: { "friendlyName:"panda", "projectAuthor":"splunk", "projectDescription":"a test add-on", "projectName":"panda", "projectNamePrefix": "Splunk_TA_", "projectVersion":"1.0.0", "themeColor":"#65A637", "visible":1 } } //or { type: 'modular-input'. data: { "type": "rest", "sourcetype": "test:rest", "name": "test_rest", "title": "test rest", "description": "test rest description", "interval": "30", "data_inputs_options": [{ "name": "_rest_api_url", "rest_header": false, "description": "url", "value": "http://www.sina.com.cn" }, { "name": "_rest_api_method", "rest_header": false, "description": "method", "value": "GET" }, { "type": "customized_var", "name": "string_label", "title": "Text", "description": "", "required_on_edit": true, "required_on_create": true }], "customized_options": [{ "name": "string_label", "value": "123" }], } } //or { type: 'modular-input'. data: { "type": "command", "sourcetype": "test:command", "name": "test_command", "title": "test command", "description": "this is a test", "interval": "30", "data_inputs_options": [{ "name": "_command", "description": "command", "value": "ls -l" }, { "type": "customized_var", "name": "string_label", "title": "Text", "description": "", "required_on_edit": true, "required_on_create": true }], "customized_options": [{ "name": "string_label", "value": "" }] } } //or { type: 'modular-input'. data: { "type": "customized", "sourcetype": "test:code", "name": "test_code", "title": "test code", "description": "test code description", "interval": "30", "data_inputs_options": [{ "type": "customized_var", "name": "string_label", "title": "Text", "description": "", "required_on_edit": true, "required_on_create": true }], "customized_options": [{ "name": "string_label", "value": "" }] } } //or { "type": "sourcetype", "data": { "sourcetype": "test:st:abc", "key_values": "{\"CHARSET\":\"UTF-8\",\"SHOULD_LINEMERGE\":\"0\",\"pulldown_type\":\"1\",\"category\":\"Splunk App Add-on Builder\"}", "from_splunk": false } } //or { "type": "event-type", "data": { "eventtype":"test_event_type", "sourcetype":"test:st:abc", "searchstr":"" } } //or { "type": "cim-mapping", "data": { "event_type": "test_eventtype", "event_field": "date_year", "eval": "date_year", "cim": "Alerts", "cim_field": "dest" } } //or { "type": "modular-alert", "data": { "parameters": [{ "required": false, "default_value": "", "name": "password", "label": "Password", "help_string": "", "format_type": "password" }], "short_name": "test_alert", "label": "test alert" } }
track_deletion Tracks deletion of add-on items.	{ type: 'add-on', data: { "app_name":"Splunk_TA_panda" } } //or { type: 'modular-input'. data: { "type": "customized", "name": "test_code" } } //or { "type": "sourcetype", "data": { "sourcetype": "test:st:abc" } } //or { "type": "cim-mapping", "data": { "event_type": "test_eventtype", "event_field": "date_year", "eval": "date_year", "cim": "Alerts", "cim_field": "dest" } } //or { "type": "modular-alert", "data": { "short_name": "test_alert", "label": "test alert" } }
track_error Tracks errors that were triggered in the Add-on Builder.	{ err_code: '6099', err_args: ['123'] message: 'Cannot create a modular input with name "123". Input name must start with an alphabetic character, following by alphanumeric characters. ' }

Data that is not collected

The following kinds of data are not collected:

• Sensitive data, such as usernames or passwords.
• Identifying information, such as addresses, phone numbers, IP addresses, or hostnames.
• Indexed data in your Splunk platform instance.

How to opt in or out of data collection

The Add-on Builder displays an opt-in request the first time you run Add-on Builder. You can change your settings at any time on the Configuration > Make Add-on Builder Better tab, which is available from the Splunk Add-on Builder home page.

For more information about how Splunk collects and uses data, please refer to the Splunk Privacy Policy.