Splunk::Job

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.

Attributes

sid[R]

Return the Job's search id.

Returns: a String.

Public Class Methods

new(service, sid, state=nil) click to toggle source

# 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

Public Instance Methods

cancel() click to toggle source

Cancels this search job.

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

Returns nothing.

# 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

enable_preview() click to toggle source

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.

# File lib/splunk-sdk-ruby/entity/job.rb, line 127
def enable_preview
  control(:action => "enablepreview")
end

events(args={}) click to toggle source

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.

# 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() click to toggle source

Finalizes this search job.

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

Returns: the Job.

# File lib/splunk-sdk-ruby/entity/job.rb, line 139
def finalize
  control(:action => "finalize")
end

is_done?() click to toggle source

Returns whether the search job is done.

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

Returns: true or false.

# 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?() click to toggle source

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.

# File lib/splunk-sdk-ruby/entity/job.rb, line 167
def is_ready?()
  begin
    refresh()
    return true
  rescue EntityNotReady
    return false
  end
end

pause() click to toggle source

Pauses this search job.

Use unpause to resume.

Returns: the Job.

# File lib/splunk-sdk-ruby/entity/job.rb, line 183
def pause
  control(:action => "pause")
end

preview(args={}) click to toggle source

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.

# File lib/splunk-sdk-ruby/entity/job.rb, line 198
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={}) click to toggle source

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.

# File lib/splunk-sdk-ruby/entity/job.rb, line 220
def results(args={})
  response = @service.request(:resource => @resource + [sid, "results"],
                              :query => args)
  return response.body
end

searchlog(args={}) click to toggle source

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.

# File lib/splunk-sdk-ruby/entity/job.rb, line 236
def searchlog(args={})
  response = @service.request(:resource => @resource + [sid, "search.log"],
                              :body => args)
  return response.body
end

set_priority(value) click to toggle source

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.

# File lib/splunk-sdk-ruby/entity/job.rb, line 253
def set_priority(value)
  control(:action => "setpriority", :priority => value)
end

set_ttl(value) click to toggle source

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.

# File lib/splunk-sdk-ruby/entity/job.rb, line 334
def set_ttl(value)
  control(:action => "setttl", :ttl => value)
end

timeline(args={}) click to toggle source

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.

# File lib/splunk-sdk-ruby/entity/job.rb, line 281
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() click to toggle source

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.

# File lib/splunk-sdk-ruby/entity/job.rb, line 322
def touch
  control(:action => "touch")
end

unpause() click to toggle source

Resumes execution of this Job.

Returns: the Job.

# File lib/splunk-sdk-ruby/entity/job.rb, line 343
def unpause
  control(:action => "unpause")
end

Home Classes Methods

In Files

Parent

Methods

Files

Class/Module Index

Splunk::Job

Attributes

Public Class Methods

Public Instance Methods