Module: ScoutAgent::API

Defined in:
lib/scout_agent/api.rb

Overview

This module contains methods used to communicate with the agent programmatically. These methods can be used to send data to the agent or to make requests that the agent perform certain actions for you.

Defined Under Namespace

Classes: Command, QueueCommand

Class Method Summary collapse

Class Method Details

.path_to_agent ⇒ Object

This method returns the path to the agent executable as a Pathname object. This is convience for those who wish to manually communicate with the agent and not needed if you stick to the higher level interface.



183
184
185
186
 
# File 'lib/scout_agent/api.rb', line 183

def path_to_agent
  @path_to_agent ||= Pathname.new( File.join( File.dirname(__FILE__),
                                              *%w[.. .. bin scout_agent] ) )
end

.path_to_ruby ⇒ Object

This method returns the path to the Ruby executable used to load this code as a Pathname object. The API uses this path to make sure another version of Ruby isn’t invoked when shelling out.



171
172
173
174
175
176
 
# File 'lib/scout_agent/api.rb', line 171

def path_to_ruby
  @path_to_ruby ||= Pathname.new(
    File.join(Config::CONFIG.values_at(*%w[bindir ruby_install_name])) +
    Config::CONFIG["EXEEXT"]
  )
end

.queue_alert(fields, options = { }) ⇒ Object

This method queues an alert that will be sent straight to the Scout server during the next checkin. The passed fields should follow the rules outlined in queue_report(). The returned object and background processing rules are the same as those described in queue_for_mission().

Thus a typical alert message looks like:

ScoutAgent::API.queue_alert( :subject   => "You should know",
                             :body      => "Details here...",
                             :plugin_id => 42 )



278
279
280
 
# File 'lib/scout_agent/api.rb', line 278

def queue_alert(fields, options = { })
  QueueCommand.new(:alert, fields, options)
end

.queue_error(fields, options = { }) ⇒ Object

This method queues an error that will be sent straight to the Scout server during the next checkin. The passed fields should follow the rules outlined in queue_report(). The returned object and background processing rules are the same as those described in queue_for_mission().

Thus a typical error message looks like:

ScoutAgent::API.queue_error( :subject   => "Something went wrong",
                             :body      => "Details here...",
                             :plugin_id => 42 )



294
295
296
 
# File 'lib/scout_agent/api.rb', line 294

def queue_error(fields, options = { })
  QueueCommand.new(:error, fields, options)
end

.queue_for_mission(mission_id, message, options = { }) ⇒ Object Also known as: queue_for_plugin

Use this method to queue a message for a mission to receive on it’s next run.

By default, this method will not return until the request to the agent is complete. It then returns a Command object, which can be used to examine how the request went. For example:

response = ScoutAgent::API.queue_for_mission(42, {"message" => "here"})
if response.success?
  puts "Message queued."
else
  warn "Error:  #{response.error_message} (#{response.error_code})"
end

If you don’t wish to wait, you can request that the send take place in the background. You can still use the Command object to check the status of these requests, but you must first wait for them to be finished?(). Do not trust any other methods, like success?(), until finished?() returns true.

in_progress = ScoutAgent::API.queue_for_mission( ...,
                                                 :background => true )
# the above returns immediately, so we need to wait for it to finish
until in_progress.finished?
  # do important work that can't wait here
end
if in_progress.success?
  # ...
else
  # ...
end

Of course, you are free to ignore the returned Command, say if performance is more critical than getting a message through.



228
229
230
 
# File 'lib/scout_agent/api.rb', line 228

def queue_for_mission(mission_id, message, options = { })
  QueueCommand.new(mission_id, message, options)
end

.queue_hint(fields, options = { }) ⇒ Object

This method queues a hint that will be sent straight to the Scout server during the next checkin. The passed fields should follow the rules outlined in queue_report(). The returned object and background processing rules are the same as those described in queue_for_mission().



262
263
264
 
# File 'lib/scout_agent/api.rb', line 262

def queue_hint(fields, options = { })
  QueueCommand.new(:hint, fields, options)
end

.queue_report(fields, options = { }) ⇒ Object

This method queues a report that will be sent straight to the Scout server during the next checkin.

The passed fields must be a Hash and must contain a :plugin_id key/value pair that tells the server which plugin this report belongs to. All other pairs in the fields Hash will be considered the data for your report. For example, you could send the current Time in a report as follows:

now = Time.now
ScoutAgent::API.queue_report( :hour      => now.hour,
                              :minute    => now.min,
                              :second    => now.sec,
                              :plugin_id => 42 )

The returned object and background processing rules are the same as those described in queue_for_mission().



252
253
254
 
# File 'lib/scout_agent/api.rb', line 252

def queue_report(fields, options = { })
  QueueCommand.new(:report, fields, options)
end

.shell_escape(str) ⇒ Object

This convience method will escape a single word for use in a shell command. This is handy for anyone wanting to construct their own commands manually. You will not need this method if you stick to the higher level interface methods provided by this API.



160
161
162
163
164
 
# File 'lib/scout_agent/api.rb', line 160

def shell_escape(str)
  String(str).gsub(/(?=[^a-zA-Z0-9_.\/\-\x7F-\xFF\n])/n, '\\').
              gsub(/\n/,                                 "'\n'").
              sub(/^$/,                                  "''")
end

.take_snapshot(*args) ⇒ Object

:call-seq:

take_snapshot(options = { })
take_snapshot(force = false, options = { })

This method requests that the agent take a snapshot of the current environment, by running any commands the server has sent down. A timestamped result of these executions will be pushed up to the server during the next checkin. The returned object and background processing rules are the same as those described in queue_for_mission().

Passing a true value in force clears the command times before running, forcing a full snapshot to be taken.



316
317
318
319
320
 
# File 'lib/scout_agent/api.rb', line 316

def take_snapshot(*args)
  force   = args.shift ? %w[force] : nil unless args.first.is_a? Hash
  options = args.shift || Hash.new
  Command.new(:snapshot, force, nil, options)
end