Overview of the Splunk SDK for JavaScript

Welcome to the Splunk® Software Development Kit (SDK) for JavaScript!

This SDK is open source and uses the Apache v2.0 license. If you want to make a code contribution, go to the Open Source page for more information.

This overview tells you more about:

 

What you can do with the Splunk SDK for JavaScript

This SDK contains library code and examples designed to enable developers to build applications using Splunk.

With the Splunk SDK for JavaScript you can write JavaScript applications to programmatically interact with the Splunk engine. The SDK is built on top of the REST API, providing a wrapper over the REST API endpoints. So that means with fewer lines of code, you can write applications that:

  • Search your data, run saved searches, and work with search jobs.
  • Manage Splunk configurations and objects.
  • Integrate search results into your applications.
  • Log directly to Splunk.
  • Present a custom UI.

You can create client-side script, server-side script, or both to interact with Splunk. We tested the Splunk SDK for JavaScript on the following web browsers:

  • Internet Explorer 8 (and version 7 in compatibility mode)
  • Chrome
  • Safari
  • Firefox

If you find any issues with a particular browser, please let us know at Splunk Dev Info.

Add visualizations to your web pages

Use client-side JavaScript to add visualization components to your web pages. Go here to learn about how to use the pre-built files and tools included with the SDK. To see the Splunk SDK for JavaScript in action, run the client-side examples to see pages that implement different components, like the Timeline control shown here:

Timeline control

 

And, other examples show how to integrate third-party visualization tools, like the Google Charts component shown here:

Charting control

Create complete applications

You can create complete applications using server-side JavaScript. Check out the server-side examples. They'll show you ropes, from listing jobs and running searches to handling the results in JSON.

 

The Splunk SDK for JavaScript architecture and components

The Splunk SDK for JavaScript is divided into two areas:

  • The Data SDK allows you to interact with Splunk. For example, you can manage Splunk (such as creating and removing indexes, and user creation), input data (through the HTTP input), and search data.
  • The UI SDK includes popular Splunk UI components so that you can provide rich and engaging material to your clients. Currently these components include:
    • The Charting control, which is included with Splunk, that allows you to display different types of charts based on Splunk data.
    • The Timeline control, which shows you how many events are available for every timeslice in your query. Note that this control only works in browsers that support the <canvas> tag (it doesn't work in Internet Explorer 8 or earlier).

The Splunk SDK for JavaScript support server-side and client-side JavaScript, and you can decide which components to install. The SDK includes a Splunk app as a translation layer between Splunk's XML output and the JSON that is used by JavaScript. The SDK also includes several third-party libraries, which are included for functionality such as cross-domain communication and other features used by the examples.

The Splunk SDK for JavaScript library files include:

  • utils.js: A collection of utility functions.
  • async.js: A collection of asynchronous utility functions to handle operations such as async looping and async control flow.
  • paths.js: A dictionary of named REST endpoint paths.
  • http.js: A base HTTP implementation, shared by other HTTP clients.
  • context.js: An abstraction over the Splunk REST-wire protocol. Handles operations such as authentication and parameter encoding.
  • service.js: Native JavaScript operations for the REST API. Contains objects for creating and managing jobs, indexes, saved searches, and so on.
  • searcher.js: A higher-level abstraction over searching and iterating over results.

Read more about:

 

Entities and collections

Most REST endpoints in the Splunk REST API can be thought of as operations on entities and collections of entities. For example, there are operations to create, modify, and remove apps. Similarly, there are operations to create, manage, remove, and get results from search jobs. For each logical grouping, the base abstractions are as follows:

  • Resource: An abstraction over a resource that can be accessed over HTTP, with shortcuts for making HTTP GET, POST, and DELETE calls.
  • Entity: An abstraction over a Splunk entity (such as a single app, saved search, job, or index), providing operations such as update, remove, read properties, and refresh.
  • Collection: An abstraction over a Splunk collection (such as all apps, all saved searches, all jobs, or all indexes), providing operations such as creating new entities and fetching specific entities.

Entity and Collection are a type of Resource:

Entity = Resource.extend({...});
Collection = Resource.extend({...});
 

Native JavaScript objects

The service layer provides higher-level access to Splunk REST API through native JavaScript objects. Architecturally, each object implements either Entity or Collection. For example:

Indexes = Collection.extend({...});
Index = Entity.extend({
Jobs = Collection.extend({...});
Job = Entity.extend({...});

Each object has the default operations available to its superclass: Job has update and remove methods, while Jobs has create and list methods.

 

Namespaces

To account for permissions to view apps, system files, and other entity resources by users throughout a Splunk installation, Splunk provides access to entity resources based on a namespace. This is similar to the app/user context that is used by the Splunk REST API when accessing resources using endpoints.

The namespace is defined by:

  • An owner, which is the Splunk username, such as "admin". A value of "nobody" means no specific user. The "-" wildcard means all users.
  • An app, which is the app context for this resource (such as "search"). The "-" wildcard means all apps.
  • A sharing mode, which indicates how the resource is shared. The sharing mode can be:
    • "user": The resource is private to a specific user, as specified by owner.

      "app": The resource is shared through an app, as specified by app. The owner is "nobody", meaning no specific user.

      "global": The resource is globally shared to all apps. The owner is "nobody", meaning no specific user.

      "system": The resource is a system resource (owner is "nobody", app is "system").

In general, when you specify a namespace you can specify any combination of owner, app, and sharing the SDK library will reconcile the values, overriding them as appropriate. If a namespace is not explicitly specified, the current user is used for owner and the default app is used for app.

Here are some example combinations of owner, app, sharing:

  • List all of the saved searches for a specific user named Kramer: kramer, -, user
  • Create an index to be used within the Search app: nobody, search, app
 

State management

When you create an object for an entity, the entity's properties are read and copied from the server, creating a local snapshot of those values. Any changes to the object are only made to the object in your local cache. Your changes are not made on the server until you explicitly call the object's update method and include the specific properties and values to update. And, changes made on the server don't affect your local copy unless you call the object's fetch method, which replaces any changes you have made to your local object with an updated snapshot from the server.

The SDK does not perform validation on values when you set them, but rather passes these values to the server for validation. Any error messages from the server are then sent back to you through the SDK.

 

The Service class

The Service class is the entry point for using the Splunk SDK for JavaScript. Communication with Splunk starts by creating a Service instance and logging in, for example:

var service = new splunkjs.Service({username: "admin", password: "changeme"});

If you provide a username and password, you will be auto-logged in as long as autologin is not disabled. (Otherwise, you'd need to explicitly call the Service.login method next.) If a subsequent request returns a 401 error, the SDK attempts to log in once.

You can pass more arguments to the Service constructor, such as scheme, host, and sessionKey. For example, if you already got a Splunk session key from another source, you can use it as follows:

var service = new splunkjs.Service({sessionKey: mySessionKey});

The Service class is also where you access the different resources in Splunk. For example, this example gets the Jobs collection:

var service = new splunkjs.Service(...); 
var jobs = service.jobs();

You can specify a namespace when you create a new Service instance, but you can also specify a namespace as you fetch a resource:

var jobs = service.jobs({owner: "user", app: "awesome_app"});

When you retrieve a collection, you can limit the number of items you retrieve at a time by specifying count and offset parameters. Set count to the number of items to retrieve, and use offset to indicate where in the collection to retrieve them. For example, to page through 10 jobs at a time in the Jobs collection, you'd set count to 10, and offset to increments of 10. This retrieves 10 jobs starting at the 21st job in the collection:

var searches = service.jobs();
jobs.fetch({count: 10, offset: 20}, function(err, searches) {
    console.log(jobs.list().length); // is 10
});
 

Asynchronous model

JavaScript is asynchronous, so rather than return values, functions expect a callback as their last argument. In return, every callback takes an error parameter as its first argument.

The following pseudo-code shows how to create a job:

var service = new splunkjs.Service({username: "admin", password: "changeme"});
var jobs = service.jobs();
service.login(function(err, success) {
    assert.ok(success);
    service.jobs.create("search index=_internal | head 1", {exec_mode: "blocking"}, function(err, job) {
        assert.ok(!err); // err will be null if we were successful.
        console.log(job.sid); 
    });
});

However, writing in this nesting, diagonal style can become tiresome and hard to maintain, so Splunk provides the Async module to ease development. Code could then be written as follows:

var service = new splunkjs.Service(...);
Async.chain([
        function(done) {
            service.login(done);
        },
        function(success, svc, done) {
            var jobs = svc.jobs();
            jobs.create("search index=_internal | head 1", {exec_mode: "blocking"}, done);
        },
        function(job, done) {
            console.log(job.sid);
            job.cancel(done);
        }
    ],
    function(err) {
        assert.ok(err);
        console.log("DONE");
    }
);

Async.chain executes each function in turn, and passes the results to the next function. If any function encounters an error (by calling the callback with the first parameter not equal to null), it immediately calls the final callback with the error.