Ruby library for dealing with Splunk searches and results using the Splunk REST API.

• Session based authentication to Splunk REST interface
• Create and check on the status of Splunk Jobs
• Retrieve Splunk alerts
• Natural Ruby methods for interacting with search results (no need to parse XML or JSON or use Ruby Hashes)

gem install splunk-client

Creating and using a client is easy:

require 'rubygems' 
require 'splunk-client'

# Create the client
splunk = SplunkClient.new("username", "password", "hostname")

# Create the Search
search = splunk.search("test_search")

# Wait for the Splunk search to complete
search.wait # Blocks until the search returns

#Print the raw XML results 
puts search.results

# Use ruby methods for dealing with results:
search.parsedResults.each do |result|
	puts result.host + " : " + result.time
end

Working with Splunk alerts:

# Create the client
splunk = SplunkClient.new("username", "password", "hostname")

# Fetch all the open alerts
alertEntries = splunk.get_alert_list.entries

# What's the name of this alert?
alertEntries[1].alert.title

# What time did a particular alert trigger?
alertEntries[1].alert.trigger_time_rendered

# How many times has a particular alert fired?
alertEntries[1].alert.triggered_alerts

# Fetch the raw XML results of the alert
alertEntries[1].alert.results

# Work with the results as a Ruby object
alertEntries[1].alert.parsedResults

• Want to spawn multiple jobs without blocking on each? Use search.complete? to poll for job status.

• Looking for more or less results? Use search.results(maxResults) to control how much is returned. (A value of 0 returns all results (this is the default.))

• Access Splunk fields in results via simple method calls

  `result = search.parsedResults`
  `puts result[0].fieldName`
  

I'm making an assumption that if you are looking for a Ruby client to interact with Splunk's REST API, you have some idea of what Splunk does. If not, you should totally check it out. It makes working with logs awesome.

http://www.splunk.com

The Splunk REST API reference can be found here: http://docs.splunk.com/Documentation/Splunk/5.0.1/RESTAPI/RESTsearch

This gem currently only provides access to the /search/ and /alerts/ APIs. The gem attempts to make use of method_missing to implement ruby methods where fields are returned from a given Splunk search.

Very little excetption handling occurs with-in the gem. It is up to consumers to ensure they have appropriate network connectivity to their splunk endpoint, and that the credentials are correct.

Insufficient network connectivity will raise a TimeOut exception.

Incorrect credentials will raise a Nokogiri error referencing Undefined namespace prefix: //s:key[@name='isDone']

• Refactored the growing list of items to pass into SplunkClient.new into an options hash.

• Added support for turning off SSL use_ssl

• Added support for HTTP proxy servers and read timeouts.

• Added preliminary GET support for alarms within the Splunk REST API

TODO: Write test-cases for alerts methods.

• Added alias support for raw field
• Added test cases for all Splunk meta fields

• Added two new objects: SplunkResults and SplunkResult for to support:

• Accessing Splunk fields via method calls

  search.parsedResults.each {|result| puts result.$$FIELD_NAME$$}
  

WARNING: Compatibility with prior versions will break as SplunkClient no longer returns a sid. It now returns a SplunkJob object.

• Separated SplunkClient and SplunkJob into two separate objects.

• Initial Release

As of 0.5, this software uses Semantic Versioning. Basically, this means that any given minor release number is backwards compatible. Patch releases are just that, and major releases may break compatibility.

If you contribute to this software, and I hope you do, please leave the VERSION file alone. Alternatively, update the VERSION file in a commit on it's own, so that we can cherry-pick around it when merging code.

This software is released under the MIT License (ref: LICENSE)