cbrito / splunk-client

Splunk REST API Library for Ruby
MIT License
21 stars 15 forks source link

SplunkClient

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

Features

Installation

gem install splunk-client

Usage

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

Tips

FAQ

What is Splunk?

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

Where can I find information on Splunk's REST API and the methods available in this gem?

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.

Why do I get an exception when using wait on a 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']

Revision History

1.0.0

0.10

0.9

0.8

TODO: Write test-cases for alerts methods.

0.7

0.6

0.5

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

0.1

Versioning

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.

License

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