Splunk® Add-on Builder

Splunk Add-on Builder User Guide

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Splunk® Add-on Builder. For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

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.

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.

Last modified on 22 June, 2018
PREVIOUS
Learn more and get help
  NEXT
What to know before you build add-ons

This documentation applies to the following versions of Splunk® Add-on Builder: 2.1.0, 2.1.1, 2.1.2


Was this documentation topic helpful?


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