Class: Splunk::Index

Inherits:
Entity show all
Defined in:
lib/splunk-sdk-ruby/entity/index.rb

Overview

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.

Instance Attribute Summary

Attributes inherited from ReadOnlyEntity

#name, #namespace, #resource, #service

Instance Method Summary collapse

Methods inherited from Entity

#[]=, #delete, #disable, #enable, #update

Methods inherited from ReadOnlyEntity

#[], #fetch, #initialize, #links, #read, #readmeta, #refresh

Constructor Details

This class inherits a constructor from Splunk::ReadOnlyEntity

Instance Method Details

#attach(args = {}) ⇒ Object

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()



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/splunk-sdk-ruby/entity/index.rb', line 53

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

#clean(timeout = 100) ⇒ Object

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.



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/splunk-sdk-ruby/entity/index.rb', line 85

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

#roll_hot_buckets ⇒ Object

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.



134
135
136
137
138
139
 
# File 'lib/splunk-sdk-ruby/entity/index.rb', line 134

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

#submit(event, args = {}) ⇒ Object

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")



155
156
157
158
159
160
161
162
 
# File 'lib/splunk-sdk-ruby/entity/index.rb', line 155

def submit(event, args={})
  args[:index] = @name
  @service.request(:method => :POST,
                   :resource => ["receivers", "simple"],
                   :query => args,
                   :body => event)
  return self
end

#upload(filename, args = {}) ⇒ Object

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 Strings:

  • :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.



183
184
185
186
187
188
189
 
# File 'lib/splunk-sdk-ruby/entity/index.rb', line 183

def upload(filename, args={})
  args['index'] = @name
  args['name'] = filename
  @service.request(:method => :POST,
                   :resource => ["data", "inputs", "oneshot"],
                   :body => args)
end