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.

[Source]

# 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

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.

[Source]

# 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

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 )

[Source]

# File lib/scout_agent/api.rb, line 278
    def queue_alert(fields, options = { })
      QueueCommand.new(:alert, fields, options)
    end

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 )

[Source]

# File lib/scout_agent/api.rb, line 294
    def queue_error(fields, options = { })
      QueueCommand.new(:error, fields, options)
    end

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.

[Source]

# File lib/scout_agent/api.rb, line 228
    def queue_for_mission(mission_id, message, options = { })
      QueueCommand.new(mission_id, message, options)
    end

Alias for queue_for_mission

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

[Source]

# File lib/scout_agent/api.rb, line 262
    def queue_hint(fields, options = { })
      QueueCommand.new(:hint, fields, options)
    end

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

[Source]

# File lib/scout_agent/api.rb, line 252
    def queue_report(fields, options = { })
      QueueCommand.new(:report, fields, options)
    end

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.

[Source]

# 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

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.

[Source]

# 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