Class: Splunk::Job

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

Overview

A class to represent a Splunk asynchronous search job.

When you create a job, you need to wait for it to be ready before you can interrogate it in an useful way. Typically, you will write something like

job = @service.jobs.create("search *")
while !job.is_ready?
  sleep(0.2)
end
# Now the job is ready to use.

The most important methods on Job beyond those provided by Entity are those that fetch results (results, preview), and those that control the job’s execution (cancel, pause, unpause, finalize).

Note that jobs are created with preview disabled by default. You need to call enable_preview and wait for the field “isPreviewEnabled” to be “1” before you will get anything useful from preview.

Instance Attribute Summary collapse

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, #links, #read, #readmeta, #refresh

Constructor Details

#initialize(service, sid, state = nil) ⇒ Job

Returns a new instance of Job.



46
47
48
49
50
51
52
53
54
55
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 46

def initialize(service, sid, state=nil)
  @sid = sid
  begin
    super(service, Splunk::namespace(:sharing => "global"), PATH_JOBS, sid, state)
  rescue EntityNotReady
    # Jobs may not be ready (and so cannot be refreshed) when they are
    # first created, so Entity#initialize may throw an EntityNotReady
    # exception. It's nothing to be concerned about for jobs.
  end
end

Instance Attribute Details

#sid ⇒ Object (readonly)

Return the Job‘s search id.

Returns: a String.



266
267
268
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 266

def sid
  @sid
end

Instance Method Details

#cancel ⇒ Object

Cancels this search job.

Cancelling the job stops the search and deletes the results cache.

Returns nothing.



64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 64

def cancel
  begin
    control(:action => "cancel")
  rescue SplunkHTTPError => err
    if err.code == 404
      return self # Job already cancelled; cancelling twice is a nop.
    else
      raise err
    end
  end
end

#control(args) ⇒ Object

Issues a control request to this job.

args should be a hash with at least the key :action (with a value such as “cancel” or “setpriority”).

Returns: the Job.



84
85
86
87
88
89
90
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 84

def control(args) # :nodoc:
  @service.request(:method => :POST,
                   :namespace => @namespace,
                   :resource => @resource + [sid, "control"],
                   :body => args)
  self
end

#enable_preview ⇒ Object

Enables preview generation for this job.

Enabling previews may slow the search down considerably, but will make the preview method return events before the job is finished.

Returns: the Job.



127
128
129
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 127

def enable_preview
  control(:action => "enablepreview")
end

#events(args = {}) ⇒ Object

Returns the raw events found by this search job.

These events are the data from the search pipeline before the first “transforming” search command. This is the primary method for a client to fetch a set of untransformed events from a search job. This call is only valid if the search has no transforming commands.

If the job is not yet finished, this will return an empty set of events.

See the REST docs for this call for more info on valid parameters and results.

Returns: a stream that can be read with ResultsReader.



107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 107

def events(args={})
  # Suppress segmentation (<sg> tags in the XML response) by default:
  if !args.has_key?(:segmentation)
    args[:segmentation] = "none"
  end
  response = @service.request(
      :method => :GET,
      :resource => @resource + [sid, "events"],
      :query => args)
  return response.body
end

#finalize ⇒ Object

Finalizes this search job.

Stops the search and provides whatever results have been obtained so far. (retrievable via results).

Returns: the Job.



139
140
141
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 139

def finalize
  control(:action => "finalize")
end

#is_done? ⇒ Boolean

Returns whether the search job is done.

is_done refreshes the Job, so its answer is always current.

Returns: true or false.

Returns:

  • (Boolean) 


150
151
152
153
154
155
156
157
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 150

def is_done?()
  begin
    refresh()
    return fetch("isDone") == "1"
  rescue EntityNotReady
    return false
  end
end

#is_ready? ⇒ Boolean

Returns whether the search job is ready.

is_ready refreshes the Job, so once the job is ready, you need not call refresh an additional time.

Returns: true or false.

Returns:

  • (Boolean) 


167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 167

def is_ready?()
  begin
    refresh()
    if @state["content"]["dispatchState"] == "QUEUED" || @state["content"]["dispatchState"] == "PARSING"
      return false
    else
      return true
    end
  rescue EntityNotReady
    return false
  end
end

#pause ⇒ Object

Pauses this search job.

Use unpause to resume.

Returns: the Job.



187
188
189
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 187

def pause
  control(:action => "pause")
end

#preview(args = {}) ⇒ Object

Returns a set of preview events from this Job.

If the search job is finished, this method is identical to results. Otherwise, it will return an empty results set unless preview is enabled (for instance, by calling enable_preview).

See the REST docs for this call for more info on valid parameters and results.

Returns: a stream readable by ResultsReader.



202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 202

def preview(args={})
  # Suppress segmentation (<sg> tags in the XML response) by default:
  if !args.has_key?(:segmentation)
    args[:segmentation] = "none"
  end
  response = @service.request(:method => :GET,
                              :resource => @resource +
                                  [sid, "results_preview"],
                              :query => args)
  return response.body
end

#results(args = {}) ⇒ Object

Returns search results for this job.

These are the results after all processing from the search pipeline is finished, including transforming search commands.

The results set will be empty unless the job is done.

Returns: a stream readable by ResultsReader.



224
225
226
227
228
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 224

def results(args={})
  response = @service.request(:resource => @resource + [sid, "results"],
                              :query => args)
  return response.body
end

#searchlog(args = {}) ⇒ Object

Returns the search log for this search job.

The search log is a syslog style file documenting the job.

See the REST docs for this call for more info on valid parameters and results.

Returns: a stream containing the log.



240
241
242
243
244
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 240

def searchlog(args={})
  response = @service.request(:resource => @resource + [sid, "search.log"],
                              :body => args)
  return response.body
end

#set_priority(value) ⇒ Object

Sets the priority of this search Job.

value can be 0-10, but unless the Splunk instance is running as root or administrator, you can only reduce the priority.

Arguments:

  • value: an Integer from 0 to 10.

Returns: the Job.



257
258
259
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 257

def set_priority(value)
  control(:action => "setpriority", :priority => value)
end

#set_ttl(value) ⇒ Object

Sets the time to live (TTL) of this Job.

The time to live is a number in seconds saying how long the search job should be on the Splunk system before being deleted.

Returns: the Job.



338
339
340
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 338

def set_ttl(value)
  control(:action => "setttl", :ttl => value)
end

#timeline(args = {}) ⇒ Object

Returns the distribution over time of the events available so far.

See the REST docs for this call for more info on valid parameters and results.

Each bucket is represented as a Hash with the following fields: :available_buckets, :event_count, :time_in_seconds (number of seconds since the epoch), :bucket_duration (how much time this bucket covers), :finished_scanning (is scanning for events in this bucket complete), :earliest_timezone and :latest_timezone (which can be different, for example when daylight savings time starts during a bucket’s duration), and :time (a string representing the bucket’s time in human readable form).

Returns: an Array of Hashes describing each time bucket.



285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 285

def timeline(args={})
  response = @service.request(:resource => @resource + [sid, "timeline"],
                              :body => args)
  if $splunk_xml_library == :nokogiri
    doc = Nokogiri::XML(response.body)
    matches = doc.xpath("/timeline/bucket").map() do |bucket|
      {:available_buckets => Integer(bucket.attributes["a"].to_s),
       :event_count => Integer(bucket.attributes["c"].to_s),
       :time_in_seconds => Float(bucket.attributes["t"].to_s),
       :bucket_duration => Integer(bucket.attributes["d"].to_s),
       :finished_scanning => Integer(bucket.attributes["f"].to_s),
       :earliest_timezone => Integer(bucket.attributes["etz"].to_s),
       :latest_timezone => Integer(bucket.attributes["ltz"].to_s),
       :time => bucket.children.to_s}
    end
    return matches
  else
    doc = REXML::Document.new(response.body)
    matches = []
    matches = doc.elements.each("/timeline/bucket") do |bucket|
      {:available_buckets => Integer(bucket.attributes["a"]),
       :event_count => Integer(bucket.attributes["c"]),
       :time_in_seconds => Float(bucket.attributes["t"]),
       :bucket_duration => Integer(bucket.attributes["d"]),
       :finished_scanning => Integer(bucket.attributes["f"]),
       :earliest_timezone => Integer(bucket.attributes["etz"]),
       :latest_timezone => Integer(bucket.attributes["ltz"]),
       :time => bucket.children.join("")}
    end
    return matches
  end
end

#touch ⇒ Object

Resets the time to live for this Job.

Calling touch resets the remaining time to live for the Job to its original value.

Returns: the Job.



326
327
328
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 326

def touch
  control(:action => "touch")
end

#unpause ⇒ Object

Resumes execution of this Job.

Returns: the Job.



347
348
349
 
# File 'lib/splunk-sdk-ruby/entity/job.rb', line 347

def unpause
  control(:action => "unpause")
end