Skip to content
This repository

Splunk Software Development Kit for JavaScript

Release 1.3

latest commit 2872818694
Itay Neeman itay authored
Octocat-spinner-32 bin Make browser examples run with Splunk 6.0 November 21, 2013
Octocat-spinner-32 client Compiled browser files March 19, 2014
Octocat-spinner-32 contrib Update SDK to work with AMD loaders February 26, 2013
Octocat-spinner-32 docs Change SDK name per legal December 19, 2012
Octocat-spinner-32 examples Updated copyright date March 17, 2014
Octocat-spinner-32 lib Updated copyright date March 17, 2014
Octocat-spinner-32 licenses Change JobManager to use real eventing April 12, 2012
Octocat-spinner-32 node_modules Changed Request modulde dependency to "2.21.x" August 29, 2013
Octocat-spinner-32 tests Remove results.js example test March 17, 2014
Octocat-spinner-32 xml2json Remove easyXDM library. Context.init() now requires user to explicitl… October 16, 2012
Octocat-spinner-32 .coverignore Exclude 'contrib' directory from code coverage, since the coverage to… September 21, 2012
Octocat-spinner-32 .gitignore Checkin node dependencies November 30, 2012
Octocat-spinner-32 .jshintignore Fix some jshint issues April 27, 2012
Octocat-spinner-32 .jshintrc Remove easyXDM library. Context.init() now requires user to explicitl… October 16, 2012
Octocat-spinner-32 CHANGELOG.md Update changelog March 11, 2014
Octocat-spinner-32 LICENSE Add license info to the README about every 3rd party lib we include November 29, 2011
Octocat-spinner-32 README.md Update version # in readme March 13, 2014
Octocat-spinner-32 index.js Remove Storm functionality as per DVPL-1223. November 06, 2012
Octocat-spinner-32 package.json Bump version number in package.json February 17, 2014
Octocat-spinner-32 sdkdo Add a more descriptive error if we have a 'require' problem December 09, 2011
Octocat-spinner-32 sdkdo.bat Add sdkdo.bat file for easier Windows execution December 11, 2011
Octocat-spinner-32 splunkrc.spec Restore 'scheme' key to .splunkrc documentation. (DVPL-1335) November 30, 2012
README.md

The Splunk Software Development Kit for JavaScript

Version 1.3.0

The Splunk Software Development Kit (SDK) for JavaScript 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.

Installation

This section describes the basic steps for installing the Splunk SDK for JavaScript. For more detailed instructions and requirements, see the Splunk Developer Portal.

Get the Splunk SDK for JavaScript

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

The XML to JSON Splunk app (xml2json) converts XML output to JSON, and is required if:

  • You are using Splunk 4.2.x or 4.3.x.
  • You want to run the unit tests (with any Splunk version).

To install the XML to JSON app, copy the xml2json app directory (/splunk-sdk-javascript/xml2json) to the Splunk apps directory ($SPLUNK_HOME/etc/apps), then restart Splunk.

Use the Splunk SDK for JavaScript components on your web page

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

For example, 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. These UI component files (splunk.ui.timeline and splunk.ui.charting) are also in the /splunk-sdk-javascript/client directory.

Install the Splunk SDK for JavaScript for Node.js

Note: The Splunk SDK for JavaScript v1.3.0 requires Node.js version 0.8.x or 0.10.x.

If you want to use the Splunk SDK for JavaScript with your Node.js programs, install the SDK by running npm in your project's directory as follows:

npm install splunk-sdk

Then, to include the Splunk SDK for JavaScript, use the require function in your code:

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

Usage

The following examples show you how to list search jobs using client-side and server-side code.

Client-side code example

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

<script type="text/javascript" src="splunk.js"></script>
<script type="text/javascript" src="jquery.min.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 SDK for JavaScript 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 SDK for JavaScript 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, the SDK examples and unit tests use the values from the .splunkrc file when you don't specify them.

To use this convenience file, create a text file with the following format and save it as .splunkrc in the current user's home directory:

# Splunk host (default: localhost)
host=localhost
# Splunk admin port (default: 8089)
port=8089
# Splunk username
username=admin
# Splunk password
password=changeme
# Access scheme (default: https)
scheme=https
# Your version of Splunk (default: 5.0)
version=5.0

Note: The version key is required if using Splunk 4.3.

Client-side examples

The Splunk SDK for JavaScript includes several browser-based examples, which you can run from the Examples web page.

To start a simple web server and open the Examples page in a web browser, enter:

node sdkdo examples

Node.js examples

The Splunk SDK for JavaScript 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 example, open a command prompt in the splunk-sdk-javascript directory and enter:

node jobs.js list

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

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 SDK for JavaScript 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 and enter:

node sdkdo --help

Compile (combine and minify) the browser files

To rebuild and minify the browser files, open a command prompt in the splunk-sdk-javascript directory and enter:

node sdkdo compile

Run unit tests

The Splunk SDK for JavaScript includes several unit tests for each component. You can run individual test modules or run all tests. Before you run them, some searches need to be running in your splunkd instance. You can start some searches by logging into Splunk Web and opening the Search app, which will run a few searches to populate its dashboard.

Note: The xml2json app is required for running unit tests.

To run the unit tests, open a command prompt in the splunk-sdk-javascript directory. To run all tests, enter:

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

Repository

/bin Executable files (such as sdkdo)
/client Pre-built files for the browser
/contrib Packaged third-party dependencies (such as test runners)
/docs API reference documentation
/examples Examples
/lib The SDK code files
/licenses License information for packaged third-party dependencies
/node_modules JavaScript modules used by Node.js
/tests Unit tests
/xml2json Source for the XML to JSON app

Changelog

The CHANGELOG.md file in the root of the repository contains a description of changes for each version of the SDK. You can also find the Splunk SDK for JavaScript Changelog online.

Branches

The master branch always represents a stable and released version of the SDK. You can read more about the JavaScript SDK Branching Model on our wiki.

Documentation and resources

If you need to know more:

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

How to contribute

If you would like to contribute to the SDK, go here for more information:

Support

  1. You will be granted support if you or your company are already covered under an existing maintenance/support agreement. Send an email to support@splunk.com and include "Splunk SDK for JavaScript" in the subject line.

  2. If you are not covered under an existing maintenance/support agreement, you can find help through the broader community at:

  3. Splunk will NOT provide support for SDKs if the core library (the code in the /lib directory) has been modified. If you modify an SDK and want support, you can find help through the broader community and Splunk answers (see above). We would also like to know why you modified the core library—please send feedback to devinfo@splunk.com.
  4. File any issues on GitHub.

Contact us

You can reach the Developer 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:

Something went wrong with that request. Please try again.