Splunker

A Ruby client for the RESTful Splunk API

Consider this largely functional but alpha. See the TODO list below.

Installation

Add this line to your application's Gemfile:

gem 'splunker'

And then execute:

$ bundle

Or install it yourself as:

$ gem install splunker

Usage

Models are on the way, but you can access resources by directly invoking the HTTP helper methods.

Console

To make playing around with the API client a smooth(er) experience, you can fire up our IRB wrapper by:

$ bundle exec script/console 
Enabling console mode for local gem
Loading splunker gem...
Splunker:001:0> c = Splunker.client(:auth_mode => :http_auth)
#<Splunker::Client:0x007f9782b0d238 @endpoint="https://localhost:8089", @app="search", @ssl_verify=true, @request_handler=#<Splunker::Auth::HttpAuth:0x007f9782b0cf68 @client=#<Splunker::Client:0x007f9782b0d238 ...>>, @password=nil, @username=nil>

Basic Auth

c = Splunker.client(:auth_mode => :http_auth, :username => "MYUSERNAME", 
  :password => "MYPASSWORD", :endpoint => "https://splunk.mysite.com")
# Returns Nokogiri::XML::Document 
# Note that /servicesNS/YOUR_USERNAME/YOUR_APPNAME is prepended automatically
# to your resource.
r = c.get("/saved/searches/MySearch/history")
# Process away
r.xpath("...")

Exceptions

The API client raises an exception when a non-2XX response codes is received.

HTTP Code Splunk API Error Code
401 Splunker::Errors::AuthenticationFailureError
402 Splunker::Errors::FeatureDisabledError
403 Splunker::Errors::PermissionDeniedError
404 Splunker::Errors::ObjectDoesNotExistError
405 Splunker::Errors::MethodNotAllowedError
409 Splunker::Errors::InvalidOperationError
500 Splunker::Errors::InternalServerError
Any other non-2xx response Splunker::Errors::ClientError

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

TODO

  • Token Auth
  • Resource creation handling, blocking & polling options, with a timeout.
  • Build console into gem (bin/)
  • Search all models in addition to getting by ID
  • Support search paramters (or, validate support)
  • Strat for acknowledge, dispatch, history, etc.
  • XML parsing -- detect nodes with children, detect types?