splunk-sdk-ruby 0.1.0

data/lib/splunk-sdk-ruby/entity.rb

@@ -0,0 +1,260 @@
+#--
+# 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.
+#++
+
+require_relative 'ambiguous_entity_reference'
+require_relative 'atomfeed'
+require_relative 'entity_not_ready'
+require_relative 'synonyms'
+
+module Splunk
+  ##
+  # Class representing individual entities in Splunk.
+  #
+  # +Entity+ objects represent individual items such as indexes, users, roles,
+  # etc. They are usually contained within +Collection+ objects.
+  #
+  # The basic, identifying information for an +Entity+ (name, namespace, path
+  # of the collection containing entity, and the service it's on) is all
+  # accessible via getters (+name+, +namespace+, +resource+, +service+). All
+  # the fields containing the +Entity+'s state, such as the capabilities of
+  # a role or whether an app should check for updates, are accessible with 
+  # the [] operator (for instance, +role+["+capabilities+"] or 
+  # +app+["+check_for_updates+"]).
+  #
+  # +Entity+ objects cache their state, so each lookup of a field does not
+  # make a roundtrip to the server. The state may be refreshed by calling
+  # the +refresh+ method on the +Entity+.
+  #
+  class Entity
+    extend Synonyms
+
+    def initialize(service, namespace, resource, name, state=nil) # :nodoc:
+      @service = service
+      @namespace = namespace
+      if !@namespace.is_exact?
+        raise StandardError.new("Must provide an exact namespace to " +
+                                    "Entity (found: #{@namespace}")
+      end
+      @resource = resource
+      @name = name
+      @state = state
+      if !state # If the state was not provided, we need to fetch it.
+        refresh()
+      end
+    end
+
+    ##
+    # The name of this Entity.
+    #
+    # Returns: a +String+.
+    #
+    attr_reader :name
+
+    ##
+    # The namespace of this Entity.
+    #
+    # Returns: a +Namespace+.
+    #
+    attr_reader :namespace
+
+    ##
+    # The path of the collection this entity lives in.
+    #
+    # For example, on an app this will be ["+apps+", "+local+"].
+    #
+    # Returns: an +Array+ of +Strings+.
+    #
+    attr_reader :resource
+
+    ##
+    # The service this entity refers to.
+    #
+    # Returns: a +Service+ object.
+    #
+    attr_reader :service
+
+    ##
+    # Deletes this entity from the server.
+    #
+    # Returns: +nil+.
+    #
+    def delete()
+      @service.request({:method => :DELETE,
+                        :namespace => @namespace,
+                        :resource => @resource + [name]})
+    end
+
+    ##
+    # Fetches the field _key_ on this entity.
+    #
+    # You may provide a default value. All values are returned
+    # as strings.
+    #
+    # Returns: a +String+.
+    #
+    def fetch(key, default=nil)
+      @state["content"].fetch(key, default)
+    end
+
+    ##
+    # Fetch a field on this entity.
+    #
+    # Returns: a +String+.
+    #
+    synonym "[]", "fetch"
+
+    ##
+    # Returns a Hash of the links associated with this entity.
+    #
+    # The links typically include keys such as "+list+", "+edit+", or
+    # "+disable+".
+    #
+    # Returns: a +Hash+ of +Strings+ to URL objects.
+    #
+    def links()
+      return @state["links"]
+    end
+
+    ##
+    # DEPRECATED. Use +fetch+ and [] instead (since entities now cache their
+    # state).
+    #
+    # Returns all or a specified subset of key/value pairs on this +Entity+
+    #
+    # In the absence of arguments, returns a Hash of all the fields on this
+    # +Entity+. If you specify one or more +Strings+ or +Arrays+ of +Strings+,
+    # all the keys specified in the arguments will be returned in the +Hash+.
+    #
+    # Returns: a +Hash+ with +Strings+ as keys, and +Strings+ or +Hashes+ or 
+    # +Arrays+ as values.
+    #
+    def read(*field_list)
+      warn "[DEPRECATION] Entity#read is deprecated. Use [] and fetch instead."
+      if field_list.empty?
+        return @state["content"].clone()
+      else
+        field_list = field_list.flatten()
+        result = {}
+        field_list.each() do |key|
+          result[key] = fetch(key).clone()
+        end
+        return result
+      end
+    end
+
+    ##
+    # Returns the metadata for this +Entity+.
+    #
+    # This method is identical to
+    #
+    #     entity.read('eai:acl', 'eai:attributes')
+    #
+    # Returns: a +Hash+ with the keys "+eai:acl+" and "+eai:attributes+".
+    #
+    def readmeta
+      read('eai:acl', 'eai:attributes')
+    end
+
+    ##
+    # Refreshes the cached state of this +Entity+.
+    #
+    # Returns: the +Entity+.
+    #
+    def refresh()
+      response = @service.request(:resource => @resource + [name],
+                                  :namespace => @namespace)
+      if response.code == 204 or response.body.nil?
+        # This code is here primarily to handle the case of a job not yet being
+        # ready, in which case you get back empty bodies.
+        raise EntityNotReady.new((@resource + [name]).join("/"))
+      end
+      # We are guaranteed a unique entity, since entities must have
+      # exact namespaces.
+      feed = AtomFeed.new(response.body)
+      @state = feed.entries[0]
+      self
+    end
+
+    ##
+    # Updates the values on the Entity specified in the arguments.
+    #
+    # The arguments can be either a Hash or a sequence of +key+ => +value+ 
+    # pairs. This method does not refresh the +Entity+, so if you want to see 
+    # the new values, you must call +refresh+ yourself.
+    #
+    # Whatever values you pass will be coerced to +Strings+, so updating a
+    # numeric field with an Integer, for example, will work perfectly well.
+    #
+    # Returns: the +Entity+.
+    #
+    # *Example*:
+    #     service = Splunk::connect(:username => 'admin', :password => 'foo')
+    #     index =  service.indexes['main']
+    #     # You could use the string "61" as well here.
+    #     index.update('rotatePeriodInSecs' => 61)
+    #
+    def update(args)
+      @service.request({:method => :POST,
+                        :namespace => @namespace,
+                        :resource => @resource + [name],
+                        :body => args})
+      self
+    end
+
+    ##
+    # Updates the attribute _key_ with _value_.
+    #
+    # As for +update+, _value_ may be anything that may be coerced sensibly
+    # to a +String+.
+    #
+    # Returns: the new value.
+    #
+    def []=(key, value)
+      update(key => value)
+      value
+    end
+
+    ##
+    # Disables this entity.
+    #
+    # After a subsequent refresh, the "disabled" field will be set to "1".
+    # Note that on some entities, such as indexes in Splunk 5.x, most other
+    # operations do not work until it is enabled again.
+    #
+    # Returns: the +Entity+.
+    #
+    def disable
+      @service.request(:method => :POST,
+                       :namespace => @namespace,
+                       :resource => @resource + [name, "disable"])
+      self
+    end
+
+    ##
+    # Enables this entity.
+    #
+    # After a subsequent refresh, the "disabled" field will be set to "0".
+    #
+    # Returns: the +Entity+.
+    #
+    def enable
+      @service.request(:method => :POST,
+                       :namespace => @namespace,
+                       :resource => @resource + [name, "enable"])
+      self
+    end
+  end
+end

data/lib/splunk-sdk-ruby/entity/index.rb

@@ -0,0 +1,191 @@
+#--
+# 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.
+#++
+
+##
+# Provides a class +Index+ to represent indexes on the Splunk server.
+#
+
+require_relative '../entity'
+
+module Splunk
+  ##
+  # Class representing an index on the Splunk server.
+  #
+  # Beyond what its superclass +Entity+ provides, +Index+ also exposes methods
+  # to write data to an index and delete all data from an index.
+  #
+  class Index < Entity
+    # Opens a socket to write events to this index.
+    #
+    # Write events to the returned stream Socket, and Splunk will index the
+    # data. You can optionally pass a hash of _host_, _source_, and
+    # _sourcetype_ arguments to be sent with every event.
+    #
+    # Splunk may not index submitted events until the socket is closed or
+    # at least 1MB of data has been submitted.
+    #
+    # You are responsible for closing the socket.
+    #
+    # Note that +SSLSocket+ and +TCPSocket+ have incompatible APIs.
+    #
+    # Returns: an +SSLSocket+ or +TCPSocket+.
+    #
+    # *Example*:
+    #
+    #     service = Splunk::connect(:username => 'admin', :password => 'foo')
+    #     stream = service.indexes['main'].attach(:sourcetype => 'mysourcetype')
+    #     (1..5).each { stream.write("This is a cheezy event\r\n") }
+    #     stream.close()
+    #
+    def attach(args={})
+      args[:index] = @name
+
+      path = (@service.namespace.to_path_fragment() + ["receivers","stream"]).
+          map {|fragment| URI::encode(fragment)}.
+          join("/")
+      query = URI.encode_www_form(args)
+
+      cn = @service.connect
+      headers = "POST /#{path}?#{query} HTTP/1.1\r\n" +
+          "Host: #{@service.host}:#{@service.port}\r\n" +
+          "Accept-Encoding: identity\r\n" +
+          "Authorization: Splunk #{@service.token}\r\n" +
+          "X-Splunk-Input-Mode: Streaming\r\n" +
+          "\r\n"
+      cn.write(headers)
+      cn
+    end
+
+    ##
+    # DEPRECATED: Delete the index instead.
+    #
+    # Deletes all events in this index. 
+    #
+    # The +clean+ method will wait until the operation completes, or _timeout_
+    # seconds have passed. By default, _timeout_ is 100 seconds.
+    #
+    # Cleaning an index is done by setting +maxTotalDataSizeMG+ and
+    # +frozenTimePeriodInSecs+ to +"1"+.
+    #
+    # Returns: the +Index+.
+    #
+    def clean(timeout=100)
+      warn "[DEPRECATION] Index#clean is deprecated. Delete the index instead."
+      refresh()
+      original_state = read(['maxTotalDataSizeMB', 'frozenTimePeriodInSecs'])
+      was_disabled_initially = fetch("disabled") == "1"
+      needed_restart_initially = @service.server_requires_restart?
+      if (!was_disabled_initially && @service.splunk_version[0] < 5)
+        disable()
+      end
+
+      update(:maxTotalDataSizeMB => 1, :frozenTimePeriodInSecs => 1)
+      roll_hot_buckets()
+
+      Timeout::timeout(timeout) do
+        while true
+          refresh()
+          if fetch("totalEventCount") == "0"
+            break
+          else
+            sleep(1)
+          end
+        end
+      end
+
+      # Restores the original state
+      if !was_disabled_initially
+        enable()
+        if !needed_restart_initially and @service.server_requires_restart?
+          service.request(:method => :DELETE,
+                          :resource => ["messages", "restart_required"])
+        end
+      end
+      update(original_state)
+    end
+
+    ##
+    # DEPRECATED.
+    #
+    # Tells Splunk to roll the hot buckets in this index now. 
+    #
+    # A Splunk index is a collection of buckets containing events. A bucket
+    # begins life "hot", where events may be written into it. At some point,
+    # when it grows to a certain size, or when +roll_hot_buckets+ is called,
+    # it is rolled to "warm" and a new hot bucket created. Warm buckets are
+    # fully accessible, but not longer receiving new events. Eventually warm
+    # buckets are archived to become cold buckets.
+    #
+    # Returns: the +Index+.
+    #
+    def roll_hot_buckets()
+      warn "[DEPRECATION] Index#roll_hot_buckets is deprecated."
+      @service.request(:method => :POST,
+                       :resource => @resource + [@name, "roll-hot-buckets"])
+      return self
+    end
+
+    ##
+    # Writes a single event to this index.
+    #
+    # _event_ is the text of the event. You can optionally pass a hash
+    # with the optional keys +:host+, +:source+, and +:sourcetype+.
+    #
+    # Returns: the +Index+.
+    #
+    # *Example:*
+    #   service = Splunk::connect(:username => 'admin', :password => 'foo')
+    #   service.indexes['main'].submit("this is an event",
+    #                                  :host => "baz",
+    #                                  :sourcetype => "foo")
+    #
+    def submit(event, args={})
+      args[:index] = @name
+      @service.request(:method => :POST,
+                       :resource => ["receivers", "simple"],
+                       :query => args,
+                       :body => event)
+      return self
+    end
+
+    ##
+    # Uploads a file accessible by the Splunk server.
+    #
+    # _filename_ should be the full path to the file on the server where
+    # Splunk is running. Besides _filename_, +upload+ also takes a hash of
+    # optional arguments, all of which take +String+s:
+    #
+    # * +:host+ - The host for the events.
+    # * +:host_regex+ - A regex to be used to extract a 'host' field from
+    #   the path. If the path matches this regular expression, the captured
+    #   value is used to populate the 'host' field or events from this data
+    #   input.  The regular expression must have one capture group.
+    # * +:host_segment+ - Use the specified slash-seperated segment of the
+    #   path as the host field value.
+    # * +:rename-source+ - The value of the 'source' field to be applied to the
+    #   data from this file.
+    # * +:sourcetype+ - The value of the 'sourcetype' field to be applied to
+    #   data from this file.
+    #
+    def upload(filename, args={})
+      args['index'] = @name
+      args['name'] = filename
+      @service.request(:method => :POST,
+                       :resource => ["data", "inputs", "oneshot"],
+                       :body => args)
+    end
+  end
+end