Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Splunk Software Development Kit for JavaScript (Preview Release)

README.md

The Splunk JavaScript Software Development Kit (Preview Release)

The Splunk JavaScript Software Development Kit (SDK) contains library code and examples designed to enable developers to build applications using Splunk and JavaScript. This SDK supports both server- and client-side JavaScript.

License

The Splunk JavaScript SDK is licensed under the Apache License 2.0. Details can be found in the LICENSE file.

The Splunk JavaScript SDK is a Preview release

  1. This Preview is a pre-Beta release that is incomplete and may have bugs. There will be a Beta release prior to a general release.

  2. The Apache License only applies to the Splunk JavaScript SDK and no other Software provided by Splunk.

  3. Splunk, in using the Apache License, does not provide any warranties or indemnification, and does not accept any liabilities with the Preview release of the SDK.

  4. We are now accepting contributions from individuals and companies to our Splunk open source projects. See the Open Source page for more information.

Installation

You can install the Splunk JavaScript SDK in a few simple steps. For more detailed instructions, go to the Splunk Developer Portal.

Get the Splunk JavaScript SDK

You can get the SDK by downloading it from GitHub, or by cloning it:

git clone https://github.com/splunk/splunk-sdk-javascript.git

Install the XML to JSON Splunk app

To install the XML to JSON Splunk app, xml2json, copy it to $SPLUNK_HOME/etc/apps/.

Use the Splunk JavaScript SDK components on your web page

To use the components from the Splunk JavaScript SDK on your web page, copy the splunk-sdk-javascript/client directory to your web server and include the splunk.js or splunk.min.js file from this directory in your code.

So, include one of the following tags in your code:

<script type="text/javascript" src="/yourpath/splunk.js"></script>

Or:

<script type="text/javascript" src="/yourpath/splunk.min.js"></script>

You can also include the UI components, such as the Timeline and Charting controls. The UI component files (such as splunk.ui.timeline and splunk.ui.charting) are also in the splunk-sdk-javascript/client directory.

Install the Splunk JavaScript SDK for Node.js

If you want to use the SDK with your Node.js programs, install the SDK by using npm in your project's directory:

npm install splunk-sdk

To include the SDK, use the require function in your code:

var splunkjs = require('splunk-sdk');

Usage

Client-side code example

This HTML example uses the Splunk JavaScript SDK to list all jobs:

<script type="text/javascript" src="splunk.js"></script>

<script type="text/javascript" charset="utf-8">
    var service = new splunkjs.Service({username: "admin", password: "changeme"});
    service.login(function(err, success) {
        if (err) {
            throw err;
        }

        console.log("Login was successful: " + success);
        service.jobs().fetch(function(err, jobs) {
            var jobList = jobs.list();
            for(var i = 0; i < jobList.length; i++) {
                console.log("Job " + i + ": " + jobList[i].sid);
            }
        });
    });
</script>

Node.js code example

This example shows how to use the Splunk JavaScript SDK and Node.js to list all jobs:

var splunkjs = require('splunk-sdk');

var service = new splunkjs.Service({username: "admin", password: "changeme"});
service.login(function(err, success) {
    if (err) {
        throw err;
    }

    console.log("Login was successful: " + success);
    service.jobs().fetch(function(err, jobs) {
        var jobList = jobs.list();
        for(var i = 0; i < jobList.length; i++) {
            console.log("Job " + i + ": " + jobList[i].sid);
        }
    });
});

SDK examples

The Splunk JavaScript SDK contains several server- and client-based examples. For detailed instructions about getting them running, see the Splunk Developer Portal.

Set up the .splunkrc file

To connect to Splunk, many of the SDK examples and unit tests take command-line arguments that specify values for the host, port, and login credentials for Splunk. For convenience during development, you can store these arguments as key-value pairs in a text file named .splunkrc. Then, when you don't specify these arguments at the command line, the SDK examples and unit tests use the values from the .splunkrc file. To use a .splunkrc file, create a text file with the following format:

# Host at which Splunk is reachable (OPTIONAL)
host=localhost
# Port at which Splunk is reachable (OPTIONAL)
# Use the admin port, which is 8089 by default.
port=8089
# Splunk username
username=admin
# Splunk password
password=changeme
# Access scheme (OPTIONAL)
scheme=https

Save the file as .splunkrc in the current user's home directory or in the root directory of the Splunk JavaScript SDK.

Client-side examples

The Splunk JavaScript SDK includes several browser-based examples, which you can run from the Examples web page. To start a simple web server and open this page in a web browser, enter:

node sdkdo examples

Node.js examples

The Splunk JavaScript SDK includes several command-line examples, which are located in the /splunk-sdk-javascript/examples/node directory. These examples run with Node.js and use the command-line arguments from the .splunkrc file, if you set this up with your login credentials.

For example, to run the jobs.js sample, go to the splunk-sdk-javascript/examples/node directory and enter:

node jobs.js list

If you aren't storing your login credentials in .splunkrc, enter the following command:

node jobs.js --username yourusername --password yourpassword list

Your output should look something like this:

~\splunk-sdk-javascript\examples\node> node .\jobs.js list
  Job 1 sid: scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1323917700_79740ae7e22350d6
  Job 2 sid: scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1323917400_0dceb302931a2b3f
  Job 3 sid: scheduler__nobody__search_SW5kZXhpbmcgd29ya2xvYWQ_at_1323917100_48fb4cc65a25c5b1
  Job 4 sid: scheduler__nobody__search_SW5kZXhpbmcgd29ya2xvYWQ_at_1323916200_b2f239fef7834523
  Job 5 sid: scheduler__nobody__unix_QWxlcnQgLSBzeXNsb2cgZXJyb3JzIGxhc3QgaG91cg_at_1323914400_96cb9084680b25d7
  Job 6 sid: admin__admin__search_TXkgQXdlc29tZSBTYXZlZCBTZWFyY2g_1323901055.6
==============

Development

The Splunk JavaScript SDK infrastructure relies on Node.js, so if you want to build files, run examples, run tests, or generate documentation, you must install Node.js. You can read more about how to set up your environment on the Splunk Developer Portal.

All development activities are managed by a helper script called sdkdo. For a list of possible commands and options, open a command prompt in the splunk-sdk-javascript directory, then enter the following command:

node sdkdo --help

Compile (combine and minify) the browser files

To rebuild and minify the browser files, enter:

node compile

Run unit tests

The SDK includes several unit tests for each component. You can run individual test modules or run all tests. Open a command prompt and go to the splunk-sdk- javascript directory. To run all tests, enter the following command:

node sdkdo tests

To run the HTTP and the Async tests, enter:

node sdkdo tests http,async

To run the browser tests, enter:

node sdkdo tests-browser

Documentation

Changelog

The CHANGELOG.md file contains a description of changes for each version of the SDK. You can find this file in the root of the SDK repository, and online at:

Branches

The master branch always represents a stable and released version of the SDK. You can read more about our branching model on our Wiki:

Repository

bin Executable files (such as `sdkdo`)
client Pre-built files for the browser
contrib Packaged third-party dependencies (such as test runners)
docs Generated documentation for the SDK
examples Examples
internal Internal files used by the SDK for testing and examples
lib The SDK code files
licenses License information for packaged third-party dependencies
xml2json Source for the `xml2json` XML -> JSON app
tests Unit tests
ui UI components of the SDK

Resources

Find anything having to do with developing on Splunk at the Splunk Developer Portal:

Find reference documentation for the Splunk REST API:

For information about Splunk and its capabilities:

For more information about the SDK and this repository, see our GitHub Wiki:

Community

Stay connected with other developers building on Splunk.

Email devinfo@splunk.com
Issues https://github.com/splunk/splunk-sdk-javascript/issues/
Answers http://splunk-base.splunk.com/tags/javascript/
Blog http://blogs.splunk.com/dev/
Twitter @splunkdev

Contributions

If you want to make a code contribution, go to the Open Source page for more information.

Support

Contact us

You can reach the Dev Platform team at devinfo@splunk.com.

License

The Splunk JavaScript Software Development Kit is licensed under the Apache License 2.0. Details can be found in the LICENSE file.

Third-party libraries

The embedded third-party libraries may have different licenses. Here is a list of embedded libraries and their licenses:

  1. dox: MIT
  2. davis.js Documentation Generator: MIT
  3. easyXDM: MIT
  4. jquery.class.js: MIT
  5. nodeunit: MIT
  6. showdown.js: BSD
  7. staticresource: MIT
  8. webapp2: Apache
  9. commander: MIT 10.script.js: Apache 11.base64.js: MIT 12.eventemitter.js: MIT
Something went wrong with that request. Please try again.