Class: Splunk::Service

Inherits:
Context show all
Defined in:
lib/splunk-sdk-ruby/service.rb

Overview

A user friendly interface to the Splunk REST API.

Service subclasses Context (which provides the methods to login to Splunk and make requests to the REST API), and adds convenience methods for accessing the major collections of entities, such as indexes, search jobs, and configurations.

Instance Attribute Summary

Attributes inherited from Context

#host, #namespace, #password, #path_prefix, #port, #proxy, #scheme, #ssl_client_cert, #ssl_client_key, #token, #username

Instance Method Summary collapse

Methods inherited from Context

#connect, #initialize, #login, #logout, #request, #request_by_url, #restart, #server_accepting_connections?, #server_requires_restart?

Constructor Details

This class inherits a constructor from Splunk::Context

Instance Method Details

#apps ⇒ Object

Returns a collection of all the apps installed on Splunk.

Returns a Collection containing Entity objects.

Examples::

require 'splunk-sdk-ruby'
service = Splunk::connect(:username => 'admin', 
                          :password => 'changeme')
service.apps.each do |app|
  puts app.name
end



108
109
110
 
# File 'lib/splunk-sdk-ruby/service.rb', line 108

def apps
  Apps.new(self, PATH_APPS_LOCAL)
end

#capabilities ⇒ Object

Returns an Array of all the capabilities roles may have in Splunk.

Capabilities are a fixed list on the server, so this method returns an Array rather than an Entity.

Returns: an Array of Strings.

Example:

service = Splunk::connect(:username => 'admin', 
                          :password => 'changeme')
puts service.capabilities
# Prints: ["admin_all_objects", "change_authentication",
#          "change_own_password", "delete_by_keyword", ...]



127
128
129
130
131
 
# File 'lib/splunk-sdk-ruby/service.rb', line 127

def capabilities
  response = request(:resource => PATH_CAPABILITIES)
  feed = AtomFeed.new(response.body)
  feed.entries[0]["content"]["capabilities"]
end

#confs ⇒ Object

Returns a Collection of all the configuration files visible on Splunk.

The configurations you see are dependent on the namespace your Service is connected with. So if you are connected in the system namespace, you may see different values than if you’re connected in the app namespace associated with a particular app, since the app may override some values within its scope.

The configuration files which are the contents of this Collection are not Entity objects, but Collection objects in their own right. They contain Entity objects representing the stanzas in that configuration file.

Returns: Configurations (a subclass of Collection containing ConfigurationFile objects).



150
151
152
 
# File 'lib/splunk-sdk-ruby/service.rb', line 150

def confs
  Configurations.new(self)
end

#create_export(query, args = {}) ⇒ Object

Creates a blocking search without transforming search commands.

The create_export method starts a search query, and any optional arguments specified in a hash (which are identical to those taken by the create methods). It then blocks until the job is finished, and returns the events found by the job before any transforming search commands (equivalent to calling events on a Job).

Returns: a stream readable by MultiResultsReader.



190
191
192
 
# File 'lib/splunk-sdk-ruby/service.rb', line 190

def create_export(query, args={}) # :nodoc:
  jobs.create_export(query, args)
end

#create_oneshot(query, args = {}) ⇒ Object

Creates a blocking search.

The create_oneshot method starts a search query, and any optional arguments specified in a hash (which are identical to those taken by create). It then blocks until the job finished, and returns the results, as transformed by any transforming search commands in query (equivalent to calling the results method on a Job).

Returns: a stream readable by ResultsReader.



165
166
167
 
# File 'lib/splunk-sdk-ruby/service.rb', line 165

def create_oneshot(query, args={})
  jobs.create_oneshot(query, args)
end

#create_search(query, args = {}) ⇒ Object

Creates an asynchronous search job.

The search job requires a query, and takes a hash of other, optional arguments, which are documented in the Splunk REST documentation.



175
176
177
 
# File 'lib/splunk-sdk-ruby/service.rb', line 175

def create_search(query, args={})
  jobs.create(query, args)
end

#create_stream(query, args = {}) ⇒ Object

DEPRECATED. Use create_export instead.



195
196
197
198
 
# File 'lib/splunk-sdk-ruby/service.rb', line 195

def create_stream(query, args={})
  warn "[DEPRECATION] Service#create_stream is deprecated. Use Service#create_export instead."
  jobs.create_export(query, args)
end

#indexes ⇒ Object

Returns a Collection of all Index objects.

Index is a subclass of Entity, with additional methods for manipulating indexes in particular.



206
207
208
 
# File 'lib/splunk-sdk-ruby/service.rb', line 206

def indexes
  Collection.new(self, PATH_INDEXES, entity_class=Index)
end

#info ⇒ Object

Returns a Hash containing Splunk’s runtime information.

The Hash has keys such as “build” (the number of the build of this Splunk instance) and “cpu_arch” (what CPU Splunk is running on), and “os_name” (the name of the operating system Splunk is running on).

Returns: A Hash that has Strings as both keys and values.



219
220
221
222
223
224
 
# File 'lib/splunk-sdk-ruby/service.rb', line 219

def info
  response = request(:namespace => Splunk::namespace(:sharing => "default"),
                     :resource => PATH_INFO)
  feed = AtomFeed.new(response.body)
  feed.entries[0]["content"]
end

#inputs ⇒ Object

Return a collection of the input kinds.



229
230
231
 
# File 'lib/splunk-sdk-ruby/service.rb', line 229

def inputs
  InputKinds.new(self, PATH_INPUTS)
end

#jobs ⇒ Object

Returns a collection of all the search jobs running on Splunk.

The Jobs object returned is a subclass of Collection, but also has convenience methods for starting oneshot and streaming jobs as well as creating normal, asynchronous jobs.

Returns: A Jobs object.



241
242
243
 
# File 'lib/splunk-sdk-ruby/service.rb', line 241

def jobs
  Jobs.new(self)
end

#loggers ⇒ Object

Returns a collection of the loggers in Splunk.

Each logger logs errors, warnings, debug info, or informational information about a specific part of the Splunk system (e.g., WARN on DeploymentClient).

Returns: a Collection of Entity objects representing loggers.

Example:

service = Splunk::connect(:username => 'admin', :password => 'foo')
service.loggers.each do |logger|
  puts logger.name + ":" + logger['level']
end
# Prints:
#   ...
#   DedupProcessor:WARN
#   DeployedApplication:INFO
#   DeployedServerClass:WARN
#   DeploymentClient:WARN
#   DeploymentClientAdminHandler:WARN
#   DeploymentMetrics:INFO
#   ...



269
270
271
 
# File 'lib/splunk-sdk-ruby/service.rb', line 269

def loggers
  Collection.new(self, PATH_LOGGER)
end

#messages ⇒ Object

Returns a collection of the global messages on Splunk.

Messages include such things as warnings and notices that Splunk needs to restart.

Returns: A Collection of Message objects (which are subclasses of Entity).



282
283
284
 
# File 'lib/splunk-sdk-ruby/service.rb', line 282

def messages
  Messages.new(self, PATH_MESSAGES, entity_class=Message)
end

#modular_input_kinds ⇒ Object

Returns a read only collection of modular input kinds.

The modular input kinds are custom input kinds on this Splunk instance. To access the actual inputs of these kinds, use the Service#inputs method. This method gives access to the metadata describing the input kinds.

Returns: A ReadOnlyCollection of ModularInputKind objects representing all the custom input types added to this Splunk instance.



297
298
299
300
301
302
303
304
305
 
# File 'lib/splunk-sdk-ruby/service.rb', line 297

def modular_input_kinds
  if self.splunk_version[0] < 5
    raise IllegalOperation.new("Modular input kinds are " +
                                   "not supported before Splunk 5.0")
  else
    ReadOnlyCollection.new(self, PATH_MODULAR_INPUT_KINDS,
                           entity_class=ModularInputKind)
  end
end

#roles ⇒ Object

Returns a collection of the roles on the system.

Returns: A Collection of Entity objects representing the roles on this Splunk instance.



313
314
315
 
# File 'lib/splunk-sdk-ruby/service.rb', line 313

def roles
  CaseInsensitiveCollection.new(self, PATH_ROLES)
end

#saved_searches ⇒ Object 



321
322
323
 
# File 'lib/splunk-sdk-ruby/service.rb', line 321

def saved_searches
  Collection.new(self, PATH_SAVED_SEARCHES, entity_class=SavedSearch)
end

#settings ⇒ Object

Returns an Entity of Splunk’s mutable runtime information.

The settings method includes values such as “SPLUNK_DB” and “SPLUNK_HOME”. Unlike the values returned by the info method, these settings can be updated.

Returns: an Entity with all server settings.

Example:

service = Splunk::connect(:username => 'admin', :password => 'foo')
puts svc.settings.read
# Prints:
#    {"SPLUNK_DB" => "/path/to/splunk_home/var/lib/splunk",
#     "SPLUNK_HOME" => "/path/to/splunk_home",
#     ...}



342
343
344
345
346
347
348
 
# File 'lib/splunk-sdk-ruby/service.rb', line 342

def settings
  # Though settings looks like a collection on the server, it always has
  # a single entity, of the same name, giving the actual settings. We access
  # that entity directly rather than putting a collection inbetween.
  Entity.new(self, Splunk::namespace(:sharing => "default"),
             PATH_SETTINGS, "settings").refresh()
end

#splunk_version ⇒ Object

Returns the version of Splunk this Service is connected to.

The version is represented as an Array of length 3, with each of its components an integer. For example, on Splunk 4.3.5, splunk_version would return [4, 3, 5], while on Splunk 5.0.2, splunk_version would return [5, 0, 2].

Returns: An Array of Integers of length 3.



360
361
362
 
# File 'lib/splunk-sdk-ruby/service.rb', line 360

def splunk_version
  info["version"].split(".").map() {|v| Integer(v)}
end

#users ⇒ Object

Return a Collection of the users defined on Splunk.



367
368
369
 
# File 'lib/splunk-sdk-ruby/service.rb', line 367

def users
  CaseInsensitiveCollection.new(self, PATH_USERS)
end