splunk-sdk-ruby 0.1.0

data/Rakefile

@@ -0,0 +1,40 @@
+require 'rubygems' unless ENV['NO_RUBYGEMS']
+require 'rubygems/package_task'
+require 'rubygems/specification'
+require 'rake/testtask'
+require 'date'
+
+spec = Gem::Specification.new do |s|
+  s.name = "splunk-sdk"
+  s.version = "0.1.0"
+  s.author = "Splunk"
+  s.email = "devinfo@splunk.com"
+  s.homepage = "http://dev.splunk.com"
+  s.summary = "SDK for easily working with Splunk from Ruby."
+  s.description = s.summary
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "LICENSE", "TODO"]
+  s.require_path = "lib"
+  s.files = %w(LICENSE README Rakefile TODO) + Dir.glob('{lib,test}/**/*')
+end
+
+task :default => :help
+
+desc "Print help on using the Rakefile for the Ruby SDK for Splunk."
+task :help do
+  puts "Rake commands for the Ruby SDK for Splunk:"
+  puts "  rake install: Install the SDK in your current Ruby environment."
+  puts "  rake test: Run the unit test suite."
+  puts "  rake test COVERAGE=true: Run the unit test suite with code coverage."
+end
+
+desc "install the gem locally"
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION}}
+end
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/test_*.rb"
+  t.verbose = true
+end

data/examples/1_connect.rb

@@ -0,0 +1,51 @@
+#--
+# Copyright 2011-2012 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'splunk-sdk-ruby'
+
+# How to get to the Splunk server. Edit this to match your
+# own Splunk install.
+config = {
+    :scheme => :https,
+    :host => "localhost",
+    :port => 8089,
+    :username => "admin",
+    :password => "changeme"
+}
+
+# Create a Service logged into Splunk, and print the authentication token
+# that Splunk sent us.
+service0 = Splunk::connect(config)
+puts "Logged in service 0. Token: #{service0.token}"
+
+# connect is a synonym for creating a Service by hand and calling login.
+service1 = Splunk::Service.new(config)
+service1.login()
+puts "Logged in. Token: #{service1.token}"
+
+# However, we don't always want to call login. If we have already obtained a
+# valid token, we can use it instead of a username or password. In this case
+# we must create the Service manually.
+token_config = {
+    :scheme => config[:scheme],
+    :host => config[:host],
+    :port => config[:port],
+    :token => service1.token
+}
+
+service2 = Splunk::Service.new(token_config)
+puts "Theoretically logged in. Token: #{service2.token}"
+

data/examples/2_manage.rb

@@ -0,0 +1,103 @@
+#--
+# Copyright 2011-2012 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'splunk-sdk-ruby'
+
+# How to get to the Splunk server. Edit this to match your
+# own Splunk install.
+config = {
+    :scheme => :https,
+    :host => "localhost",
+    :port => 8089,
+    :username => "admin",
+    :password => "changeme"
+}
+
+# First we connect to Splunk. We'll use this service for all the work in this
+# example.
+service = Splunk::connect(config)
+
+# Service provides convenience methods to get to the various collections in
+# Splunk. For example, we'll list all the apps, all the users, and all the
+# search jobs.
+puts "Apps:"
+service.apps.each do |app|
+  puts "  #{app.name}"
+end
+
+puts
+puts "User:"
+service.users.each do |user|
+  puts "  #{user.name}"
+end
+
+puts "Jobs:"
+service.jobs.each do |job|
+  puts "  #{job.sid}: #{job["eventSearch"]}"
+end
+
+# Collections have most of the methods you would expect from Hash.
+puts
+puts "Apps starting with s:"
+service.apps.select do |app|
+  app.name.start_with?("s")
+end.each do |app|
+  puts "  #{app.name}"
+end
+
+# Collections have create and delete methods which do what you would expect.
+# create methods all take the name of the entity to create as the sole
+# positional argument, and a hash of other arguments, and returns an object
+# representing the new entity.
+new_user = service.users.create("a-new-user",
+                                :password => "some password",
+                                :email => "harry@nowhere.com",
+                                :roles => ["power"])
+
+puts
+puts "User in collection: #{service.users.member?("a-new-user")}"
+matches = service.users["a-new-user"].name == new_user.name
+puts "User returned by create matches user fetched: #{matches}"
+
+service.users.delete("a-new-user")
+puts "User still in collection after delete: #{service.users.member?("a-new-user")}"
+
+# You can access the fields on entites returned from collections as if
+# they were keys in a dictionary.
+new_user = service.users.create("a-new-user",
+                                :password => "some password",
+                                :email => "harry@nowhere.com",
+                                :roles => ["power", "admin"])
+
+puts
+puts "Roles on a-new-user: #{new_user["roles"]}"
+puts "Email of a-new-user: #{new_user["email"]}"
+
+# To update fields, call the update method (or you can use []= if you only want
+# to update a single field, but each call to it makes a round trip to the
+# Splunk server, while update makes one call).
+new_user["email"] = "petunia@nowhere.com"
+new_user.update("email" => "edward@nowhere.com", "roles" => ["power"])
+
+# If you immediately fetch the fields, you'll still see the old values, though.
+# Entities cache their state, and you must call refresh to get the new state.
+new_user.refresh()
+puts
+puts "New email: #{new_user["email"]}"
+puts "New roles: #{new_user["roles"]}"
+
+# And finally, we'll delete this user again.
+service.users.delete("a-new-user")

data/examples/3_blocking_searches.rb

@@ -0,0 +1,82 @@
+#--
+# Copyright 2011-2012 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'splunk-sdk-ruby'
+
+# How to get to the Splunk server. Edit this to match your
+# own Splunk install.
+config = {
+    :scheme => :https,
+    :host => "localhost",
+    :port => 8089,
+    :username => "admin",
+    :password => "changeme"
+}
+
+# First open a connection to Splunk.
+service = Splunk::connect(config)
+
+# The simplest way to get data out of Splunk is with a oneshot search. A oneshot
+# search creates a synchronous search. The call blocks until the search finishes
+# and then returns a stream containing the events.
+stream = service.create_oneshot("search index=_internal | head 1")
+
+# By default the stream contains XML, which you can parse into proper events
+# with the Ruby SDK's ResultsReader class. You can call fields on the
+# ResultsReader to get an Array of Strings giving the names of all the fields
+# that may appear in any of the events, or call each on it to iterate over
+# the results.
+results = Splunk::ResultsReader.new(stream)
+
+puts "Fields: #{results.fields}"
+results.each do |result|
+  puts "#{result["_raw"]}"
+end
+puts
+
+# You can also tell create_oneshot to return JSON or CSV by specifying the
+# :output_mode argument to be "json" or "csv", respectively, but the Ruby SDK
+# provides no support beyond what is already available in Ruby to parse either
+# of these formats.
+stream = service.create_oneshot("search index=_internal | head 1",
+                                :output_mode => "json")
+puts stream
+puts
+
+# Hash arguments like :output_mode are how you set various parameters to the
+# search, as :earliest_time and :latest_time.
+stream = service.create_oneshot("search index=_internal | head 1",
+                                :earliest_time => "-1h",
+                                :latest_time => "now")
+results = Splunk::ResultsReader.new(stream)
+results.each do |result|
+  puts "#{result["_raw"]}"
+end
+
+# If you only need the events Splunk has returned, without any of the
+# transforming search commands, you can call create_stream instead. It is
+# identical to create_oneshot, but returns the events produced before any
+# transforming search commands, and will thus run somewhat faster.
+stream = service.create_export("search index=_internal | head 1",
+                               :earliest_time => "-1h",
+                               :latest_time => "now")
+results = Splunk::ResultsReader.new(stream)
+results.each do |result|
+  puts "#{result["_raw"]}"
+end
+
+
+

data/examples/4_asynchronous_searches.rb

@@ -0,0 +1,79 @@
+#--
+# Copyright 2011-2012 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'splunk-sdk-ruby'
+
+# How to get to the Splunk server. Edit this to match your
+# own Splunk install.
+config = {
+    :scheme => :https,
+    :host => "localhost",
+    :port => 8089,
+    :username => "admin",
+    :password => "changeme"
+}
+
+# First open a connection to Splunk.
+service = Splunk::connect(config)
+
+# For longer running jobs, you don't want to wait until the job finishes, as
+# create_oneshot in 3_blocking_searches.rb does. In this case, use the
+# create_search method of Service. Instead of returning a stream, it creates
+# an asynchronous job on the server and returns a Job object referencing it.
+job = service.create_search("search index=_internal | head 1",
+                            :earliest_time => "-1d",
+                            :latest_time => "now")
+
+# Before you can do anything with a Job, you must wait for it to be ready.
+# Before it is, you cannot do anything with it, even read its state.
+while !job.is_ready?()
+  sleep(0.1)
+end
+
+# More typically you will want to wait until the job is done and its events
+# ready to retrieve. For that, use the is_done? method instead. Note that a
+# job is always ready before it's done.
+while !job.is_done?()
+  sleep(0.1)
+end
+
+# If you want the transformed results (equivalent to what create_oneshot would
+# return), call the results method on the Job. If you want the untransformed
+# results, call events. You can optionally pass an offset and total count,
+# which are useful to get hunks of large sets of results.
+stream = job.results(:count => 1, :offset => 0)
+# Or: stream = job.events(:count => 3, :offset => 0)
+results = Splunk::ResultsReader.new(stream)
+results.each do |result|
+  puts result["_raw"]
+end
+
+# If you want to run a real time search, it must be asynchronous, and it is
+# never done, so neither results or events will work. Instead, you must call
+# preview (which takes the same arguments as the other two).
+rt_job = service.create_search("search index=_internal | head 1",
+                               :earliest_time => "rt-1h",
+                               :latest_time => "rt")
+
+while !rt_job.is_ready?()
+  sleep(0.1)
+end
+
+stream = rt_job.preview()
+results = Splunk::ResultsReader.new(stream)
+results.each do |result|
+  puts result["_raw"]
+end

data/examples/5_stream_data_to_splunk.rb

@@ -0,0 +1,79 @@
+#--
+# Copyright 2011-2012 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'splunk-sdk-ruby'
+
+# How to get to the Splunk server. Edit this to match your
+# own Splunk install.
+config = {
+    :scheme => :https,
+    :host => "localhost",
+    :port => 8089,
+    :username => "admin",
+    :password => "changeme"
+}
+
+# First open a connection to Splunk.
+service = Splunk::connect(config)
+
+# Data written to Splunk with the Ruby SDK must be written to a particular
+# index, so we first create an index to write to if it doesn't already
+# exist.
+INDEX_NAME = "my_index"
+
+if !service.indexes.has_key?(INDEX_NAME)
+  example_index = service.indexes.create(INDEX_NAME)
+else
+  example_index = service.indexes[INDEX_NAME]
+end
+
+# We can write single events to the index with the Index#submit method.
+example_index.submit("This is a test event.")
+
+# And we'll wait until it has probably been indexed.
+sleep(1) # Indexing isn't instantaneous.
+stream = service.create_oneshot("search index=#{INDEX_NAME}")
+results = Splunk::ResultsReader.new(stream)
+results.each do |result|
+  puts result["_raw"]
+end
+
+# If you need to send more than one event, use the attach method to get an
+# open socket to the index again. Sending multiple events via attach is
+# significantly faster than calling submit. However, Splunk only indexes data
+# from attach when either the socket is closed or it has accumulated 1MB
+# of input.
+socket = example_index.attach()
+begin
+  socket.write("The first event.\r\n")
+  socket.write("The second event.\r\n")
+ensure
+  socket.close() # You must make sure the socket gets closed.
+end
+
+# Again we'll wait until it's probably been indexed.
+sleep(3) # Indexing isn't instantaneous.
+stream = service.create_oneshot("search index=#{INDEX_NAME}")
+results = Splunk::ResultsReader.new(stream)
+results.each do |result|
+  puts result["_raw"]
+end
+
+# Finally, if we're running a version of Splunk where we can delete indexes
+# (anything since 5.0), we'll delete the index we created.
+if service.splunk_version[0] >= 5
+  service.indexes.delete(INDEX_NAME)
+end

data/lib/splunk-sdk-ruby.rb

@@ -0,0 +1,47 @@
+# :title:Splunk SDK for Ruby
+#--
+# Copyright 2011-2013 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#++
+#
+# The Splunk SDK for Ruby provides an idiomatic interface to Splunk from 
+# Ruby. To use it, add
+#
+#     require 'splunk-sdk-ruby'
+#
+# to the top of your source file. 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()
+#
+
+require_relative 'splunk-sdk-ruby/atomfeed'
+require_relative 'splunk-sdk-ruby/version'
+require_relative 'splunk-sdk-ruby/namespace'
+require_relative 'splunk-sdk-ruby/xml_shim'
+require_relative 'splunk-sdk-ruby/resultsreader'
+require_relative 'splunk-sdk-ruby/context'
+require_relative 'splunk-sdk-ruby/service'
+require_relative 'splunk-sdk-ruby/ambiguous_entity_reference'
+require_relative 'splunk-sdk-ruby/entity_not_ready'
+require_relative 'splunk-sdk-ruby/illegal_operation'
+require_relative 'splunk-sdk-ruby/splunk_http_error'
+
+module Splunk
+end