Install the Add-on Builder - Splunk Documentation (original) (raw)

Splunk® Add-on Builder

Splunk Add-on Builder User Guide

To build your add-ons:

Install the Add-on Builder onto a single-instance development environment, such as your laptop.
Use your Add-on Builder instance to build your new add-ons.
Deploy your new add-ons to your larger deployment.

Use your Add-on Builder instance in a single instance environment, then deploy the resulting add-on to a larger environment:

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.
Splunk Light is not supported.

Requirements

Requirements for the Splunk Add-on Builder:

Splunk Enterprise For Add-on Builder version 4.0.0 and later, Splunk Enterprise 8.2.0 or later is required for Python 3 compatibility. Develop your add-ons with the Add-on Builder in a single-instance development environment such as a laptop.
- Add-on Builder is not supported in a search head cluster or index cluster environment.
- You can use the Add-on Builder Free with the Free license. Adding a Splunk Developer License lets you work with more data.
- For more about Splunk Enterprise system requirements, see System Requirements in the Splunk Enterprise Installation Manual.
Mozilla Firefox or Google Chrome
Admin privileges on Splunk Enterprise. You must have Admin privileges to create an add-on project and to 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 alerts.

Performance tips

While developing data inputs, disable unnecessary inputs. Multiple data inputs scheduled to run at frequent intervals 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

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

Install the Splunk Add-on Builder app from the command line:

At the command line, enter:

splunk install app /

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

Use Splunk Web to upgrade the Add-on Builder.

Because the Splunk Add-on Builder version 4.0.0 and later is compatible with only Python 3, version 3.0.0 and later of the Add-on Builder is also only compatible with Splunk version 8.0.0, which also runs on Python 3. See the Python 3 Migration manual.

Do not delete the $SPLUNK_HOME/etc/apps/splunk_app_addon-builder folder before upgrading the app. You need this folder to configure previous projects in the upgraded version of the Add-on Builder.

Download the Splunk Add-on Builder from Splunkbase.
Log into Splunk Web.
Click Manage Apps.
On the Apps page, click Install app from file.
Click Choose File and navigate to the Splunk Add-on Builder package file, then click Open.
Select Upgrade app.
Click Upload.
After upgrade, clear the browser cache and reload the page (CMD+shift+R on Mac OSX or CTRL+shift+R on Windows) to apply the new UI changes.

Migrate your existing add-ons

When you migrate your previously created add-ons they become Python 3 compatible. This upgrade cannot be reverted.

The following migration task must be performed using version 8.2.0 of Splunk Enterprise.

in your Add-on Builder user interface, click the Import Project button and select the package with the addon that you want to upgrade.
Wait for it to be imported
Depending on your addon settings it will be visible either in Splunk Apps or in Add-on Builder user interface

Migrate modular inputs and alerts

By default, all modular inputs and alerts built by version 4.0.0 and later are Python 3 compatible on Splunk 8.0.

The first time you run Add-on Builder, an opt-in message lets you decide whether to send anonymized usage data to Splunk to help improve the app in future releases.

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.

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.

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_performanceTracks 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_summaryTracks 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_summaryTracks information about one add-on, including data inputs, alert actions, event types, CIM mappings, and source types.	{ 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_packageTracks whether the user has downloaded the add-on package.	{ app_name: 'test addon' }
track_validationTracks 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_extractionTracks 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_viewTracks 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_wizardTracks 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_creationTracks 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_deletionTracks 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_errorTracks 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. ' }

How to edit your data collection opt-in or opt-out selections

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.

| | Learn more and get help | | Design your add-on | | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------- |

This documentation applies to the following versions of Splunk® Add-on Builder: 4.4.1, 4.5.0