Welcome to the Splunk® Software Development Kit (SDK) for Ruby!
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:
This SDK contains library code and examples designed to enable developers to build applications using Splunk. With the Splunk SDK for Ruby you can write Ruby 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 with fewer lines of code, you can write applications that:
The Splunk library included in this SDK consists of two layers of API that can be used to interact with splunkd - the binding layer and the client layer. First, however, a word about XML...
Ruby ships with the REXML library by default, but for most real world work,
you may want to use Nokogiri, which can be orders of magnitude faster. The Splunk
SDK for Ruby supports both. By default it will try to use Nokogiri, but will fall
back to REXML if Nokogiri is not available. The value of the library in use is
kept in the global variable
$splunk_xml_library (which will be either
You can force your program to use a particular library by calling
require_xml_library(library) (where, again, library is either
:rexml). This method is in
but will be included when you include the whole SDK.
If you force your program to use a particular library, the SDK will no longer try to fall back to REXML, but will issue a LoadError.
This is the lowest layer of the Splunk SDK for Ruby. It is a thin wrapper around low-level HTTP capabilities, including:
Here is a simple example of using the binding layer. This example makes a REST call to Splunk returning an Atom feed of all users defined in the system:
require 'splunk-sdk-ruby' c = Splunk::Context.new(:username => "admin", :password => 'password') c.login() # Will print an Atom feed in XML: puts c.request(:resource => ["authentication", "users"]).body
You can read the Atom feed into a convenient Ruby object with the AtomFeed class. It has two getter methods: metadata, which returns a hash of all the Atom headers; and entries, which returns an array of hashes describing each Atom entry.
require 'splunk-sdk-ruby' c = Splunk::Context.new(:username => "admin", :password => 'password') c.login() response = c.request(:resource => ["authentication", "users"]) users = Splunk::AtomFeed.new(response.body) puts users.metadata["updated"] puts users.entries
The client layer builds on the binding layer to provide a friendlier interface to Splunk that abstracts away many of the lower level details of the binding layer. It currently abstracts the following (with more to come):
Here is example code to print the names of all the users in the system:
service = Splunk::connect(:username => 'admin', :password => 'password') service.users.each do |user| puts user.name end
For more examples, see the examples/ directory in the Splunk SDK for Ruby.
The Splunk developer platform consists of three primary components: Splunkd, the engine; Splunk Web, the app framework that sits on top of the engine; and the Splunk SDKs that interface with the REST API and extension points.
The Splunk SDK for Ruby lets you target Splunkd by making calls against the engine's REST API and accessing the various Splunkd extension points such as custom search commands, lookup functions, scripted inputs, and custom REST handlers.
Read more about:
The Service class is the primary entry point for the client library. Construct an instance of the Service class and provide the login credentials that are required to connect to an available Splunk server. There are different ways to construct the instance and authenticate.
First, add the following to the top of your source file to include the Splunk SDK for Ruby:
All the code in the SDK is in the Splunk module. Once you have included the SDK, create a connection to your Splunk instance with the following (changing host, port, username, and password to your values):
service = Splunk::Service.new(:host => "localhost", :port => 8089, :username => "admin", :password => "changeme").login()
Once the Service instance is created and authenticated, you can use it to navigate, enumerate, and operate on a wide variety of Splunk resources.
The Splunk REST API has over 160 endpoints (resources) that provide access to almost every feature of Splunk. The Splunk SDK for Ruby exposes many of these endpoints as entities and collections of entities. The base abstractions are as follows:
Each collection type can be accessed on the Service object. For example, the following example shows how to retrieve a collection of all the apps installed on Splunk:
require 'splunk-sdk-ruby' service = Splunk::connect(...) # Fill in your host and authentication details service.apps.each do |app| puts app.name end
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:
|"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:
Splunk's namespaces give access paths to objects. Each application, user, search job, saved search, or other entity in Splunk has a namespace, and when you access an entity via the REST API, you include a namespace in your query. What entities are visible to your query depends on the namespace you use for the query.
Some namespaces can contain wildcards or default values filled in by Splunk. We call such namespaces wildcard, since they cannot be the namespace of an entity—only a query. Namespaces that can be the namespace of an entity are called exact.
We distinguish six kinds of namespace, each of which is represented by a separate class:
In the user and application namespaces, you can use "-" as a wildcard in place of an actual user or application name.
These are all represented in the Ruby SDK by correspondingly named classes: DefaultNamespace, GlobalNamespace, SystemNamespace, AppNamespace, and UserNamespace. Each of these have an empty mixing Namespace, so an instance of any of them will respond to is_a?(Namespace) with true.
Some of these classes are singletons, some aren't, and to avoid confusion or having to remember which is which, you should create namespaces with the namespace function.
What namespace the eai:acl fields in an entity map to is determined by what the path to that entity should be. In the end, a namespace is a way to calculate the initial path to access an entity. For example, applications all have sharing="app" and app="" in their eai:acl fields, but their path uses the services/ prefix, so that particular combination, despite what it appears to be, is actually an AppReferenceNamespace.
One of the primary features of Splunk is running searches and retrieving search results. There are multiple types of search:
The Splunk::Jobs#create method creates a normal search job.
The Splunk::Jobs#create_oneshot method creates a oneshot search.
The Splunk::SavedSearch class represents a saved search.