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.



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

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.



147
148
149
150
151
152
 
# File 'lib/scout_agent/api.rb', line 147

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



231
232
233
 
# File 'lib/scout_agent/api.rb', line 231

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



241
242
243
 
# File 'lib/scout_agent/api.rb', line 241

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

.queue_for_mission(mission_id, message, options = { }) ⇒ Object

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 objects 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.



200
201
202
 
# File 'lib/scout_agent/api.rb', line 200

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



221
222
223
 
# File 'lib/scout_agent/api.rb', line 221

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. The returned object and background processing rules are the same as those described in queue_for_mission().



211
212
213
 
# File 'lib/scout_agent/api.rb', line 211

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.



136
137
138
139
140
 
# File 'lib/scout_agent/api.rb', line 136

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

.take_snapshot(options = { }) ⇒ Object

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



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

def take_snapshot(options = { })
  Command.new(:snapshot, nil, nil, options)
end