scout_agent 3.0.6 → 3.0.7

data/lib/scout_agent/dispatcher.rb

@@ -2,9 +2,19 @@
 # encoding: UTF-8
 
 module ScoutAgent
+  #
+  # This is the namespace for the methods that turn a command-line invocation
+  # into a command executed by the agent.
+  # 
   module Dispatcher
+    ###############
     module_function
+    ###############
 
+    #
+    # This method handles the command invocation process.  The passed +args+ are
+    # parsed for switches and command, then the selected code is loaded and run.
+    # 
     def dispatch(args = ARGV)
       switches   = parse_switches(args)
       assignment = parse_assignment(args)
@@ -12,6 +22,11 @@ module ScoutAgent
       execute_assignment(assignment, code, switches, args)
     end
     
+    #
+    # Removes all supported command-line switches from +args+.  Each switch sets
+    # the corresponding value in the Plan and a Hash of all switches are
+    # returned from this method.
+    # 
     def parse_switches(args)
       switches = { }
 
@@ -61,7 +76,7 @@ module ScoutAgent
                  "Take regular system snapshots." ) do |boolean|
           switches[:periodic_snapshots] = boolean
         end
-        opts.on( "--trusted NAME1,NAME2,...", Array,
+        opts.on( "--trusted USER1,USER2,...", Array,
                  "A list of trusted XMPP users." ) do |users|
           switches[:xmpp_trusted] = users
         end
@@ -113,6 +128,14 @@ module ScoutAgent
       switches
     end
     
+    #
+    # Locates the command in +args+.  This process aborts with an error message
+    # if the given command is malformed.  Otherwise the provided name is
+    # returned.
+    # 
+    # If a command is not given, the agent will default <tt>"identify"</tt> if
+    # not configured, <tt>"start"</tt> if not running, or <tt>"status"</tt>.
+    # 
     def parse_assignment(args)
       assignment = args.shift.to_s.downcase
       if assignment.empty?
@@ -132,6 +155,10 @@ module ScoutAgent
       assignment
     end
     
+    #
+    # Loads the code matching the +assignment+ command or dies with an error
+    # message if the name cannot be matched.  Returns the loaded code file.
+    # 
     def load_assignment(assignment)
       dir     = LIB_DIR + "assignment"
       matches = dir.entries.map { |path| path.to_s }.
@@ -145,6 +172,11 @@ module ScoutAgent
       end
     end
     
+    # 
+    # Requires +code+, loads the Class indicated by +assignment+, build an
+    # instance passing +switches+ and +other_args+, then executes the command.
+    # This method exits with an error if the code cannot be loaded.
+    # 
     def execute_assignment(assignment, code, switches, other_args)
       require code
       class_name = code.basename(".rb").to_s.CamelCase
@@ -156,6 +188,10 @@ module ScoutAgent
       loaded.new(switches, other_args).prepare_and_execute
     end
     
+    # 
+    # Abort with an error message to the user that says we matched +assignment+
+    # to multiple +matches+ and we need clarification.
+    # 
     def abort_with_ambiguous_assignment(assignment, matches)
       choices         = matches.map { |m| "'#{File.basename(m, '.rb')}'" }
       choices[-2..-1] = choices[-2..-1].join(", or ")
@@ -164,10 +200,18 @@ module ScoutAgent
       END_AMBIGUOUS
     end
     
+    # 
+    # Abort with an error message to the user that says we were unable to match
+    # +assignment+ to a known command.
+    # 
     def abort_with_unknown_assignment(assignment)
       abort "Unknown command '#{assignment}'."
     end
     
+    # 
+    # Abort with an error message to the user that warns of a broken command in
+    # our system.
+    # 
     def abort_with_missing_code(class_name)
       abort "Failed to load '#{class_name}'."
     end

data/lib/scout_agent/lifeline.rb

@@ -3,8 +3,8 @@
 
 module ScoutAgent
   class Lifeline
-    NO_CONTACT_TIMEOUT   = 3
-    CHECK_IN_FREQUENCY   = 0.99  # gives us three check ins before a cutoff
+    NO_CONTACT_TIMEOUT   = 5
+    CHECK_IN_FREQUENCY   = 0.99  # gives us five check-ins before a cutoff
     TERM_TO_KILL_PAUSE   = 1
     RELAUNCH_FREQUENCIES = [0, 1, 1, 2, 3, 5, 8, 13]
     
@@ -145,6 +145,11 @@ module ScoutAgent
       status(@agent, :restarting)
       close_reader
       Process.term_or_kill(@child_pid, TERM_TO_KILL_PAUSE)
+      # make sure we kill a mission process as well if running
+      if @agent == "master" and (mission_pid = IDCard.new(:mission).pid)
+        log.info("Stopping 'mission'.")
+        Process.term_or_kill(mission_pid, TERM_TO_KILL_PAUSE)
+      end
     end
     
     def status(process, restarting = false)

data/lib/scout_agent/mission.rb

@@ -32,17 +32,24 @@ module ScoutAgent
     end
 
     # Creates a new Scout Plugin to run.
-    def initialize(id, name, last_run, memory, options)
+    def initialize(id, name, last_run, memory, options, log = WireTap.new(nil))
       @id             = id
       @name           = name
       @last_run       = last_run
       @memory         = memory
       @options        = options
-      @mission_log_db = Database.load(:mission_log)
-      @queue_db       = Database.load(:queue)
+      @log            = log
+      @mission_log_db = !testing? && Database.load(:mission_log, @log)
+      @queue_db       = !testing? && Database.load(:queue,       @log)
     end
     
     attr_reader :last_run
+    attr_reader :log
+    alias_method :logger, :log
+    
+    def testing?
+      @id == :testing
+    end
     
     def option(name)
       @options[name] ||
@@ -132,13 +139,23 @@ module ScoutAgent
     end
     
     def each_queued_message(&block)
-      while message = @queue_db.peek(@id)
-        if block.arity == 1
-          block[message[:fields]]
-        else
-          block[message[:fields], message[:created_at]]
+      if testing?
+        Array(option(:__queue__)).each do |message|
+          if block.arity == 1
+            block[message]
+          else
+            block[message, Time.now]
+          end
+        end
+      else
+        while message = @queue_db.peek(@id)
+          if block.arity == 1
+            block[message[:fields]]
+          else
+            block[message[:fields], message[:created_at]]
+          end
+          @queue_db.dequeue(message[:id]) or return # prevent infinite loop
         end
-        @queue_db.dequeue(message[:id]) or return # prevent infinite loop
       end
     end
     
@@ -201,10 +218,13 @@ module ScoutAgent
     def write_reports_and_update_memory
       %w[report hint alert error].each do |type|
         Array(send("#{type}s")).each do |fields|
-          @mission_log_db.write_report(@id, type, fields)
+          @mission_log_db.write_report(@id, type, fields) unless testing?
+          log.debug("#{type}(#{fields.inspect.sub(/\A\{(.*)\}\z/, '\1')})")
         end
       end
-      @mission_log_db.update_mission_memory(@id, data_for_server[:memory])
+      unless testing?
+        @mission_log_db.update_mission_memory(@id, data_for_server[:memory])
+      end
     end
   end
   

data/lib/scout_agent/order/check_in_order.rb

@@ -3,18 +3,44 @@
 
 module ScoutAgent
   class Order
+    #
+    # This type of Order can be used to request a check-in over the XMPP
+    # interface.  Times can also be cleared for the desired missions to ensure
+    # they're included in the check-in.
+    # 
     class CheckInOrder < Order
+      # 
+      # The pattern of supported commands:
+      # 
+      #   checkin
+      #   checkin 1
+      #   checkin 1 2 3
+      #   check-in
+      #   check-in 1
+      #   check-in 1 2 3
+      #   check_in
+      #   check_in 1
+      #   check_in 1 2 3
+      # 
       MATCH_RE = /\A\s*check[-_]?in(?:\s+(.+?))?\s*\z/
       
+      # 
+      # Returns the mission log database or exit()'s with an error if it cannot
+      # be loaded.
+      # 
       def self.mission_log
         return @mission_log if defined? @mission_log
         unless db = Database.load(:mission_log, log)
           log.fatal("Could not load mission log database.")
-          exit
+          exit(1)
         end
         @mission_log = db
       end
       
+      #
+      # Requests a check-in by waking up the master agent.  All provided mission
+      # ID's will have their run times reset before the check-in requested.
+      # 
       def execute
         if id_str = match_details.captures.first
           ids = id_str.scan(/\d+/).map { |n| n.to_i }

data/lib/scout_agent/order/snapshot_order.rb

@@ -3,9 +3,25 @@
 
 module ScoutAgent
   class Order
+    #
+    # This type of Order can be used to request a snapshot over the XMPP
+    # interface.  All snapshots requested this way are forced and, as such, not
+    # subject to command waits.
+    # 
     class SnapshotOrder < Order
+      # 
+      # The pattern of supported commands:
+      # 
+      #   snapshot
+      #   snap-shot
+      #   snap_shot
+      # 
       MATCH_RE = /\A\s*snap[-_]?shot\s*\z/
       
+      #
+      # Requests a snapshot via the API and then notifies the master agent to
+      # check-in pushing the snapshot to the server.
+      # 
       def execute
         log.info("Requesting that a snapshot be taken.")
         API.take_snapshot(:force)

data/lib/scout_agent/order.rb

@@ -2,66 +2,112 @@
 # encoding: UTF-8
 
 module ScoutAgent
+  #
+  # This object represents an order that can be understood over XMPP.
+  # 
+  # Each subclass can can set a +MATCH_RE+ constant with a regular expression
+  # for orders it can handle or override the match?() class method, analyze the
+  # orders with code, and return +true+ or +false+ if it can handle it.
+  # 
+  # The first subclass that matches will have it's execute() method called to
+  # process the order.
+  # 
   class Order
+    # The directory Order subclasses are loaded from.
     ORDERS_DIR = LIB_DIR + "order"
     
+    # Set the log() used by all Order objects.
     def self.log=(log)
       @log = log
     end
     
+    # Returns whatever log has been set by or log=() or a bit bucket log.
     def self.log
       @log ||= WireTap.new(nil)
     end
     
+    # Returns an Array of all loaded subclasses.
     def self.subclasses
       @subclasses ||= Array.new
     end
     
+    # 
+    # Hooks into Ruby's class load process so we can notice subclasses as they
+    # are loaded.
+    # 
     def self.inherited(order)
       subclasses << order
     end
 
+    # Load all subclasses found in +ORDERS_DIR+ and return them.
     def self.load_all
       ORDERS_DIR.each_entry do |order|
         require ORDERS_DIR + order unless order.basename.to_s[0] == ?.
       end
       subclasses
     end
-    
+
+    # 
+    # Finds the first subclass that can handle +message+, optionally with the
+    # +modified_body+.  This method will return +nil+ if a match cannot be made.
+    # 
     def self.can_handle?(message, modified_body = nil)
-      subclasses.each do |order|
+      subclasses.each { |order|
         if match_details = order.match?(message, modified_body)
           return order.new(message, match_details)
         end
-      end
+      }
       nil
     end
     
+    # 
+    # Returns +true+ if this type of object matches +message+, optionally with
+    # the +modified_body+.
+    # 
+    # The default implementation looks for a +MATCH_RE+ constant and checks it
+    # against +modified_body+ or <tt>message.body</tt>.  Subclasses are free to
+    # override this for more complex behavior though.
+    # 
     def self.match?(message, modified_body = nil)
       const_defined?(:MATCH_RE) and
       const_get(:MATCH_RE).match(modified_body || message.body)
     end
-      
+    
+    # 
+    # Returns an IDCard for the master agent that Order objects can use to
+    # signal it.
+    # 
     def self.master_agent
       @master_agent ||= IDCard.new(:master)
     end
     
+    # 
+    # Creates an instance of this Order type for execution.  The Order is passed
+    # the matched +message+ and the +match_details+.
+    # 
     def initialize(message, match_details)
       @message       = message
       @match_details = match_details
     end
     
-    attr_reader :message, :match_details
+    # The message matched from XMPP.
+    attr_reader :message
+    # 
+    # Any details returned from the match.  This will be an Array of Regexp
+    # captures by default.
+    # 
+    attr_reader :match_details
     
+    # A shortcut for the class method of the same name.
     def log
-      Order.log
-    end
-    
-    def execute
-      raise NotImplementedError,
-            "Subclasses must override ScoutAgent::Order#execute()."
+      self.class.log
     end
     
+    # 
+    # This helper can be used to send an +ALRM+ signal to the master agent which
+    # triggers it to wake up and go to work.  This is handy for making it notice
+    # changes faster.
+    # 
     def notify_master
       self.class.master_agent.signal("ALRM")
     rescue Exception  # unable to signal process

data/lib/scout_agent/plan.rb

@@ -17,7 +17,7 @@ module ScoutAgent
     
     # The default configuration for this agent.
     def defaults
-      [ [:server_url,         "http://beta.scoutapp.com:3000"],
+      [ [:server_url,         "https://beta.scoutapp.com"],
         [:proxy_url,          nil],
         [:run_as_daemon,      true],
         [:logging_level,      "INFO"],

data/lib/scout_agent.rb

@@ -66,7 +66,7 @@ module ScoutAgent
   end
 
   # The version of this agent.
-  VERSION = "3.0.6".freeze
+  VERSION = "3.0.7".freeze
   # A Pathname reference to the agent code directory, used in dynamic loading.
   LIB_DIR = Pathname.new(File.dirname(__FILE__)) + agent_name
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: scout_agent
 version: !ruby/object:Gem::Version 
-  version: 3.0.6
+  version: 3.0.7
 platform: ruby
 authors: 
 - James Edward Gray II
@@ -12,7 +12,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-17 00:00:00 -05:00
+date: 2009-04-27 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -75,7 +75,12 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 0.1.0
     version: 
-description: Scout is a full server monitoring solution.  You can install standard plugins to get started with basic monitoring right away, or build your own plugins to address your specific needs.  Scout can be tied into any monitoring strategy, providing you data collection, trend analysis, email notifications and more.
+description: |
+  Scout is a full server monitoring solution.  You can install standard plugins
+  to get started with basic monitoring right away, or build your own plugins to
+  address your specific needs.  Scout can be tied into any monitoring strategy,
+  providing you data collection, trend analysis, email notifications and more.
+
 email: support@highgroove.com
 executables: 
 - scout_agent
@@ -102,6 +107,7 @@ files:
 - lib/scout_agent/assignment/start.rb
 - lib/scout_agent/assignment/status.rb
 - lib/scout_agent/assignment/stop.rb
+- lib/scout_agent/assignment/test.rb
 - lib/scout_agent/assignment/update.rb
 - lib/scout_agent/assignment/upload_log.rb
 - lib/scout_agent/assignment.rb
@@ -139,6 +145,8 @@ files:
 - LICENSE
 has_rdoc: true
 homepage: http://scoutapp.com
+licenses: []
+
 post_install_message: |+
   Installing Scout's agent...
   
@@ -174,9 +182,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: scout
-rubygems_version: 1.3.1
+rubygems_version: 1.3.2
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: Scout makes monitoring and reporting on your servers as flexible and simple as possible.
 test_files: 
 - test/ts_all.rb