scout 4.0.2 → 5.0.2

data/README

@@ -6,32 +6,32 @@ Scout by Highgroove Studios
 
 The easier way to monitor servers and web applications.
 
-Scout makes monitoring and reporting on your web applications as flexible 
-and simple as possible.
+Scout makes monitoring and reporting on your web applications
+as flexible and simple as possible.
 
-Scout is a product of Highgroove Studios.  Please visit http://scoutapp.com 
-for more information.
+Scout is a product of Highgroove Studios.
+Please visit http://scoutapp.com for more information.
 
 == Installing
 
-After installing the scout gem:
+Install the Scout gem:
 
   $ sudo gem install scout
 
-Simply run:
+Then simply run:
 
   $ scout
 
-to run the installation wizard.  You'll need your Client Key to continue.
+to run the installation wizard.  You'll need your server key to continue. Get the server key from your account at http://scoutapp.com
 
 == Running the Scout Client
 
 The Scout client has several modes of operation and commands.  The normal, intended usage is through a scheduled interval with no output.
 
 Normal checkin with server:
-  $ scout [OPTIONS] CLIENT_KEY
+  $ scout [OPTIONS] SERVER_KEY
   ... OR ...
-  $ scout [OPTIONS] run CLIENT_KEY
+  $ scout [OPTIONS] run SERVER_KEY
 
 Install:
   $ scout
@@ -41,36 +41,26 @@ Install:
 Local plugin testing:
   $ scout [OPTIONS] test PATH_TO_PLUGIN [PLUGIN_OPTIONS]
 
-Clone a client setup:
-  $ scout [OPTIONS] clone CLIENT_KEY NEW_CLIENT_NAME
 
-CLIENT_KEY is the indentification key assigned to
-this client by the server.
+SERVER_KEY is the identification key assigned by your account at http://scoutapp.com
 
 PATH_TO_PLUGIN is the file system path to a Ruby file
 that contains a Scout plugin.
 
-PLUGIN_OPTIONS can be the code for a Ruby Hash or the
-path to a YAML options file containing defaults.  These
-options will be used for the plugin run.
+PLUGIN_OPTIONS are one or more options in the form:
+key1=val1 key2=val2
+These options will be used for the plugin run.
 
-NEW_CLIENT_NAME is name you wish to use for the new
-client the server creates.
 
+== Setting up in cron
 
-== Cloning a Client
+Configure Scout to run every minute. Typically, this will look like:
 
-The Scout gem can clone an existing client to automate the process of setting up additional clients.
-
-An example usage, running:
-
- server1 $ scout clone CLIENT_KEY 'My New Client'
-
-Will create a new client called 'My New Client' on the Scout server with the same plugins as an already existing client (with the CLIENT_KEY specified).  It will also return the new system crontab line:
-
-  */30 * * * *  deploy /usr/bin/scout NEW_CLIENT_KEY
+  * * * * *  deploy /usr/bin/scout SERVER_KEY
 
+It's often helpful to log the output to a file. To do so:
 
+  * * * * *  deploy /usr/bin/scout SERVER_KEY > /path/to/anywhere/scout.out 2>&1
 
 
 For additional help, please visit http://scoutapp.com

data/Rakefile

@@ -7,8 +7,8 @@ require "net/ssh"
 require "rubygems"
 require "rubyforge"
 
-dir     = File.dirname(__FILE__)
-lib     = File.join(dir, "lib", "scout.rb")
+dir = File.dirname(__FILE__)
+lib = File.join(dir, "lib", "scout.rb")
 version = File.read(lib)[/^\s*VERSION\s*=\s*(['"])(\d\.\d\.\d)\1/, 2]
 history = File.read("CHANGELOG").split(/^(===.*)/)
 changes ||= history[0..2].join.strip
@@ -19,50 +19,50 @@ need_zip = true
 task :default => [:test]
 
 Rake::TestTask.new do |test|
-  test.libs       << "test"
+  test.libs << "test"
   test.test_files = [ "test/scout_test.rb" ]
-  test.verbose    = true
+  test.verbose = true
 end
 
 Rake::RDocTask.new do |rdoc|
-	rdoc.main     = "README"
-	rdoc.rdoc_dir = "doc/html"
-	rdoc.title    = "Scout Client Documentation"
-	rdoc.rdoc_files.include( "README",  "INSTALL",
-	                         "TODO",    "CHANGELOG",
-	                         "AUTHORS", "COPYING",
-	                         "LICENSE", "lib/" )
+  rdoc.main = "README"
+  rdoc.rdoc_dir = "doc/html"
+  rdoc.title = "Scout Client Documentation"
+  rdoc.rdoc_files.include( "README",  "INSTALL",
+                           "TODO",    "CHANGELOG",
+                           "AUTHORS", "COPYING",
+                           "LICENSE", "lib/" )
 end
 
 spec = Gem::Specification.new do |spec|
-	spec.name    = "scout"
-	spec.version = version
+  spec.name = "scout"
+  spec.version = version
 
-	spec.platform = Gem::Platform::RUBY
-	spec.summary  = "Scout makes monitoring and reporting on your web applications as flexible and simple as possible."
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = "Scout makes monitoring and reporting on your web applications as flexible and simple as possible."
 
   # TODO: test suite
-	# spec.test_suite_file = "test/ts_all.rb"
-	spec.files           = Dir.glob("{bin,lib}/**/*.rb")  +
-	                       Dir.glob("{data,vendor}/**/*") +
-	                       %w[Rakefile]
-  spec.executables     = ["scout"]
-
-	spec.has_rdoc         = true
-	spec.extra_rdoc_files = %w[ AUTHORS COPYING README INSTALL TODO CHANGELOG
+  # spec.test_suite_file = "test/ts_all.rb"
+  spec.files = Dir.glob("{bin,lib}/**/*.rb") +
+          Dir.glob("{data,vendor}/**/*") +
+          %w[Rakefile]
+  spec.executables = ["scout"]
+
+  spec.has_rdoc = true
+  spec.extra_rdoc_files = %w[ AUTHORS COPYING README INSTALL TODO CHANGELOG
 	                            LICENSE ]
-	spec.rdoc_options     << "--title" << "Scout Client Documentation" <<
-	                         "--main"  << "README"
+  spec.rdoc_options << "--title" << "Scout Client Documentation" <<
+          "--main" << "README"
+
+  spec.require_path = "lib"
 
-	spec.require_path = "lib"
-	
   spec.add_dependency "elif"
 
-	spec.author            = "Highgroove Studios"
-	spec.email             = "scout@highgroove.com"
-	spec.rubyforge_project = "scout"
-	spec.homepage          = "http://scoutapp.com"
-	spec.description       = <<END_DESC
+  spec.author = "Highgroove Studios"
+  spec.email = "scout@highgroove.com"
+  spec.rubyforge_project = "scout"
+  spec.homepage = "http://scoutapp.com"
+  spec.description = <<END_DESC
 Scout makes monitoring and reporting on your web applications as flexible and simple as possible.
 
 Scout is a product of Highgroove Studios.
@@ -70,8 +70,8 @@ END_DESC
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|
-	pkg.need_zip = need_tar
-	pkg.need_tar = need_zip
+  pkg.need_zip = need_tar
+  pkg.need_tar = need_zip
 end
 
 desc "Publishes to Scout Gem Server and Rubyforge"
@@ -85,12 +85,12 @@ task :publish_rubyforge => [:package] do
   puts "Logging in"
   forge.login
 
-  release                    = forge.userconfig
+  release = forge.userconfig
   release["release_changes"] = File.read(File.join(dir, "CHANGELOG"))
-  release["preformatted"]    = true
+  release["preformatted"] = true
 
   package = "pkg/#{spec.name}-#{version}"
-  files   = %W[#{package}.tgz #{package}.zip #{package}.gem].compact
+  files = %W[#{package}.tgz #{package}.zip #{package}.gem].compact
 
   puts "Releasing #{spec.name}-#{version}"
   forge.add_release(spec.rubyforge_project, spec.name, version, *files)
@@ -98,9 +98,9 @@ end
 
 desc "Upload current documentation to Scout Gem Server and RubyForge"
 task :upload_docs => [:rdoc] do
-	sh "scp -r doc/html/* " +
-	   "deploy@gems.scoutapp.com:/var/www/gems/docs"
-	   
+  sh "scp -r doc/html/* " +
+          "deploy@gems.scoutapp.com:/var/www/gems/docs"
+
   config = YAML.load(File.read(File.expand_path("~/.rubyforge/user-config.yml")))
   host = "#{config["username"]}@rubyforge.org"
 
@@ -112,5 +112,5 @@ end
 
 desc "Add new files to Subersion"
 task :svn_add do
-   system "svn status | grep '^\?' | sed -e 's/? *//' | sed -e 's/ /\ /g' | xargs svn add"
+  system "svn status | grep '^\?' | sed -e 's/? *//' | sed -e 's/ /\ /g' | xargs svn add"
 end

data/bin/scout

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# encoding: utf-8
 
 $VERBOSE = true # -w
-$KCODE   = "u"  # -Ku
+#$KCODE   = "u"  # -Ku
 
 $LOAD_PATH << File.join(File.dirname(__FILE__), *%w[.. lib])
 require "scout"

data/lib/scout.rb

@@ -1,9 +1,10 @@
 #!/usr/bin/env ruby -wKU
 
 module Scout
-  VERSION = "4.0.2".freeze
+  VERSION = "5.0.2".freeze
 end
 
 require "scout/command"
 require "scout/plugin"
+require "scout/plugin_options"
 require "scout/server"

data/lib/scout/command.rb

@@ -9,7 +9,7 @@ module Scout
     def self.user
       @user ||= ENV["USER"] || ENV["USERNAME"] || "root"
     end
-    
+
     def self.program_name
       @program_name ||= File.basename($PROGRAM_NAME)
     end
@@ -17,7 +17,7 @@ module Scout
     def self.program_path
       @program_path ||= File.expand_path($PROGRAM_NAME)
     end
-    
+
     def self.usage
       @usage
     end
@@ -25,9 +25,10 @@ module Scout
     def self.parse_options(argv)
       options = { }
 
-      ARGV.options do |opts|
+      op = OptionParser.new do |opts|
         opts.banner = "Usage:"
 
+        opts.separator "--------------------------------------------------------------------------"
         opts.separator "  Normal checkin with server:"
         opts.separator "    #{program_name} [OPTIONS] CLIENT_KEY"
         opts.separator "    ... OR ..."
@@ -39,47 +40,32 @@ module Scout
         opts.separator "  Local plugin testing:"
         opts.separator "    #{program_name} [OPTIONS] test " +
                        "PATH_TO_PLUGIN [PLUGIN_OPTIONS]"
-        opts.separator "  Clone a client setup:"
-        opts.separator "    #{program_name} [OPTIONS] clone " +
-                       "CLIENT_KEY NEW_CLIENT_NAME"
-        opts.separator ""
-        opts.separator "CLIENT_KEY is the indentification key assigned to"
-        opts.separator "this client by the server."
-        opts.separator ""
-        opts.separator "PATH_TO_PLUGIN is the file system path to a Ruby file"
-        opts.separator "that contains a Scout plugin."
-        opts.separator ""
-        opts.separator "PLUGIN_OPTIONS can be the code for a Ruby Hash or the"
-        opts.separator "path to a YAML options file containing defaults.  These"
-        opts.separator "options will be used for the plugin run."
-        opts.separator ""
-        opts.separator "NEW_CLIENT_NAME is name you wish to use for the new"
-        opts.separator "client the server creates."
-        opts.separator ""
+        opts.separator "[PLUGIN_OPTIONS] format: opt1=val1 opt2=val2 opt2=val3 ..."
+        opts.separator "Plugin will use internal defaults if options aren't provided."
+        opts.separator " "
         opts.separator "Note: This client is meant to be installed and"
         opts.separator "invoked through cron or any other scheduler."
-        opts.separator ""
+        opts.separator " "
         opts.separator "Specific Options:"
-
+        opts.separator "--------------------------------------------------------------------------"
         opts.on( "-s", "--server SERVER", String,
                  "The URL for the server to report to." ) do |url|
           options[:server] = url
         end
 
-        opts.separator ""
-
         opts.on( "-d", "--data DATA", String,
                  "The data file used to track history." ) do |file|
           options[:history] = file
         end
         opts.on( "-l", "--level LEVEL",
                  Logger::SEV_LABEL.map { |l| l.downcase },
-                 "The level of logging to report." ) do |level|
+                 "The level of logging to report. Use -ldebug for most detail." ) do |level|
           options[:level] = level
         end
 
+        opts.separator " "
         opts.separator "Common Options:"
-
+        opts.separator "--------------------------------------------------------------------------"
         opts.on( "-h", "--help",
                  "Show this message." ) do
           puts opts
@@ -89,31 +75,46 @@ module Scout
                  "Turn on logging to STDOUT" ) do |bool|
           options[:verbose] = bool
         end
-        
+
         opts.on( "-V", "--version",
                  "Display the current version") do |version|
           puts Scout::VERSION
           exit
         end
 
-        begin
-          opts.parse!
-          @usage = opts.to_s
-        rescue
-          puts opts
-          exit
+        opts.on( "-F", "--force", "Force checkin to Scout server regardless of last checkin time") do |bool|
+          options[:force] = bool
         end
+
+        opts.separator " "
+        opts.separator "Examples: "
+        opts.separator "--------------------------------------------------------------------------"
+        opts.separator "1. Normal run (replace w/your own key):"
+        opts.separator "     scout 6ecad322-0d17-4cb8-9b2c-a12c4541853f"
+        opts.separator "2. Normal run with logging to standard out (replace w/your own key):"
+        opts.separator "     scout --verbose 6ecad322-0d17-4cb8-9b2c-a12c4541853f"
+        opts.separator "3. Test a plugin:"
+        opts.separator "     scout test my_plugin.rb foo=18 bar=42"
+
+      end
+
+      begin
+        op.parse!(argv)
+        @usage = op.to_s
+      rescue
+        puts op
+        exit
       end
-      
       options
     end
     private_class_method :parse_options
-    
+
     def self.dispatch(argv)
+      # capture help command
+      argv.push("--help") if argv.first == 'help'
       options = parse_options(argv)
       command = if name_or_key = argv.shift
-                  if cls = Scout::Command.const_get(name_or_key.capitalize) \
-                             rescue nil
+                  if cls = (Scout::Command.const_get(name_or_key.capitalize) rescue nil)
                     cls.new(options, argv)
                   else
                     Run.new(options, [name_or_key] + argv)
@@ -121,9 +122,9 @@ module Scout
                 else
                   Install.new(options, argv)
                 end
-      command.create_pid_file_or_exit.run
+      command.run
     end
-    
+
     def initialize(options, args)
       @server  = options[:server]  || "https://scoutapp.com/"
       @history = options[:history] ||
@@ -132,23 +133,24 @@ module Scout
                             "client_history.yaml" )
       @verbose = options[:verbose] || false
       @level   = options[:level]   || "info"
-      
+      @force   = options[:force]   || false
+
       @args    = args
     end
-    
+
     attr_reader :server, :history
-    
+
     def config_dir
       return @config_dir if defined? @config_dir
       @config_dir = File.dirname(history)
       FileUtils.mkdir_p(@config_dir) # ensure dir exists
       @config_dir
     end
-    
+
     def verbose?
       @verbose
     end
-    
+
     def log
       return @log if defined? @log
       @log = if verbose?
@@ -160,15 +162,15 @@ module Scout
                nil
              end
     end
-    
+
     def level
       Logger.const_get(@level.upcase) rescue Logger::INFO
     end
-    
+
     def user
       @user ||= Command.user
     end
-    
+
     def program_name
       @program_name ||= Command.program_name
     end
@@ -176,11 +178,11 @@ module Scout
     def program_path
       @program_path ||= Command.program_path
     end
-    
+
     def usage
       @usage ||= Command.usage
     end
-    
+
     def create_pid_file_or_exit
       pid_file = File.join(config_dir, "scout_client_pid.txt")
       begin
@@ -228,7 +230,7 @@ module Scout
           retry
         end
       end
-      
+
       self
     end
   end

data/lib/scout/command/install.rb

@@ -4,23 +4,25 @@ module Scout
   class Command
     class Install < Command
       def run
+        create_pid_file_or_exit
+
         abort usage unless $stdin.tty?
         
         puts <<-END_INTRO.gsub(/^ {8}/, "")
         === Scout Installation Wizard ===
 
-        You need the Client Key displayed in the Client Settings tab.
+        You need the Server Key displayed in the Server Settings tab.
         It looks like:
 
           6ecad322-0d17-4cb8-9b2c-a12c4541853f
 
-        Enter the Client Key:
+        Enter the Server Key:
         END_INTRO
         key = gets.to_s.strip
 
         puts "\nAttempting to contact the server..."
         begin
-          Scout::Server.new(server, key, history, log) { |scout| scout.test }
+          Scout::Server.new(server, key, history, log) { |scout| scout.fetch_plan }
 
           puts <<-END_SUCCESS.gsub(/^ {10}/, "")
           Success!
@@ -31,14 +33,14 @@ module Scout
           (usually located at /etc/crontab):
 
           ****** START CRONTAB SAMPLE ******
-          */30 * * * *  #{user} #{program_path} #{key}
+          * * * * *  #{user} #{program_path} #{key}
           ******  END CRONTAB SAMPLE  ******
 
           If you are using this current user's crontab
           (using crontab -e to edit):
 
           ****** START CRONTAB SAMPLE ******
-          */30 * * * *  #{program_path} #{key}
+          * * * * *  #{program_path} #{key}
           ******  END CRONTAB SAMPLE  ******
 
           For help setting up Scout with crontab, please visit:
@@ -47,9 +49,10 @@ module Scout
 
           END_SUCCESS
         rescue SystemExit
+          puts $!.message
           puts <<-END_ERROR.gsub(/^ {10}/, "")
 
-          Could not contact server. The client key may be incorrect.
+          Failed. 
           For more help, please visit:
 
           http://scoutapp.com/help

data/lib/scout/command/run.rb

@@ -5,8 +5,25 @@ module Scout
     class Run < Command
       def run
         key = @args.first
-        Scout::Server.new(server, key, history, log) do |scout|
-          scout.run_plugins_by_plan
+        # too much external logic of command doing things to server ... should be moved into server class
+        @scout = Scout::Server.new(server, key, history, log)
+        @scout.load_history
+        @scout.fetch_plan
+
+
+        if @scout.new_plan || @scout.time_to_checkin?  || @force
+          if @scout.new_plan
+            log.info("Now checking in with new plugin plan") if log
+          elsif @scout.time_to_checkin?
+            log.info("It is time to checkin") if log
+          elsif @force
+            log.info("overriding checkin schedule with --force and checking in now.") if log
+          end
+          create_pid_file_or_exit
+          @scout.run_plugins_by_plan
+          @scout.save_history
+        else
+          log.info "Not time to checkin yet. Next checkin in #{@scout.next_checkin}. Override by passing --force to the scout command" if log
         end
       end
     end

data/lib/scout/command/test.rb

@@ -6,22 +6,43 @@ module Scout
   class Command
     class Test < Command
       def run
-        plugin, options = @args
-        
+        create_pid_file_or_exit
+        plugin, *provided_options = @args
         # read the plugin_code from the file specified
         plugin_code    = File.read(plugin)
-        plugin_options = if options.to_s[0, 1] == "{"
-          eval(options)  # options from command-line
-        elsif options
-          # 
-          # read the plugin_options from the YAML file specified,
-          # parse each option and use the default value specified
-          # in the options as the value to be passed to the test plugin
-          # 
-          Hash[ *File.open(options) { |f| YAML.load(f) }["options"].
-                 map { |name, details| [name, details["default"]] }.flatten ]
+
+        options_for_run = {}
+
+        # deal with embedded options yaml
+        if  options_yaml = Scout::Plugin.extract_options_yaml_from_code(plugin_code)
+          options=Scout::PluginOptions.from_yaml(options_yaml)
+
+          if options.error
+            puts "Problem parsing option definition in the plugin code (ignoring and continuing):"
+            puts options_yaml
+          else
+            puts "== Plugin options: "
+            puts options.to_s
+            options.select{|o|o.has_default?}.each{|o|options_for_run[o.name]=o.default}
+          end
+        else
+          puts "== This plugin doesn't have option metadata."
+        end
+
+        # provided_options are what the user gave us in the command line. Here, we merge them into
+        # the defaults we've already established (if any) for this run.
+        provided_options.each do |e|
+          if e.include?('=')
+            k,v=e.split('=',2)
+            options_for_run[k]=v
+          else
+            puts "ERROR: Option '#{e}' is no good -- provided options should be in the format name=value."
+          end
+        end
+        if options_for_run.any?
+          puts "== Running plugin with: #{options_for_run.to_a.map{|a| "#{a.first}=#{a.last}"}.join('; ') }"
         else
-          Hash.new
+          puts "== You haven't provided any options for running this plugin."
         end
 
         Scout::Server.new(nil, nil, history, log) do |scout|
@@ -30,8 +51,9 @@ module Scout
                                 'plugin_id' => 1,
                                 'name'      => "Local Plugin",
                                 'code'      => plugin_code,
-                                'options'   => plugin_options,
+                                'options'   => options_for_run,
                                 'path'      => plugin )
+          puts "== Output:"
           scout.show_checkin(:pp)
         end  
       end

data/lib/scout/plugin.rb

@@ -1,7 +1,12 @@
 #!/usr/bin/env ruby -wKU
 
+
 module Scout
+
   class Plugin
+
+    EMBEDDED_OPTIONS_REGEX = /OPTIONS ?= ?<<-?([A-Z_]+)(.*)\1/m
+
     class << self
       attr_accessor :last_defined
 
@@ -32,6 +37,18 @@ module Scout
           needs.push(*libraries.flatten)
         end
       end
+
+      # true if the code seems to have embedded options
+      def has_embedded_options?(code)
+        code =~ EMBEDDED_OPTIONS_REGEX
+      end
+
+      # extracts the internal YAML, if any, and returns the YAML string.
+      # returns nil if no embedded options.
+      def extract_options_yaml_from_code(code)
+        code =~ EMBEDDED_OPTIONS_REGEX
+        return $2
+      end
     end
 
     # Creates a new Scout Plugin to run.

data/lib/scout/plugin_options.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby -wKU
+
+require 'yaml'
+
+module Scout
+  # a data structure of an individual plugin option
+  class PluginOption
+    attr_reader :name, :notes, :default, :advanced, :password, :required
+    def initialize(name, h)
+      @name=name
+      @notes=h['notes'] || ''
+      @default=h['default'] || ''
+      @attributes=h['attributes'] || ''
+      @advanced = @attributes.include?('advanced')
+      @password = @attributes.include?('password')
+      @required = @attributes.include?('required')
+    end
+
+    # convenience -- for nicer syntax
+    def advanced?; @advanced; end
+    def password?; @password; end
+    def required?; @required; end
+    def has_default?; default != '';end
+
+    def to_s
+      required_string = required? ? " (required). " : ""
+      default_string = default == '' ? '' : " Default: #{default}. " 
+      "'#{name}'#{required_string}#{default_string}#{notes}"
+    end
+  end
+
+  # A collection of pluginOption
+  # Create: opts=PluginOptions.from_yaml(yaml_string)
+  # Check if there were any problems -- opts.error -- should be nil.
+  #
+  # A valid options yaml looks like this:
+  #    max_swap_used:
+  #      notes: If swap is larger than this amount, an alert is generated. Amount should be in MB.
+  #      default: 2048  # 2 GB
+  #    max_swap_ratio:
+  #      notes: If swap used over memory used is larger than this amount, an alert is generated
+  #      default: 3
+  #      attributes: required advanced
+  class PluginOptions < Array
+
+    attr_accessor :error
+
+    # Should be valid YAML, a hash of hashes ... if not, will be caught in the rescue below
+    def self.from_yaml(string)
+      options_array=[]
+      error=nil
+
+      items=YAML.load(string)
+      items.each_pair {|name, hash| options_array.push(PluginOption.new(name,hash)) }
+    rescue
+      error="Invalid Plugin Options"
+    ensure
+      res=PluginOptions.new(options_array)
+      res.error=error
+      return res
+    end
+
+    def advanced
+      select{|o|o.advanced? }
+    end
+
+    def regular
+      select{|o|!o.advanced? }
+    end
+
+    def to_s
+      res=[]
+      each_with_index do |opt,i|
+        res.push "#{i+1}. #{opt.to_s}"
+      end
+      res.join("\n")
+    end
+
+  end
+end

data/lib/scout/server.rb

@@ -34,7 +34,10 @@ module Scout
     # We consider the interval close enough at this point.
     # 
     RUN_DELTA = 30
-    
+
+    attr_reader :new_plan
+    attr_reader :directives
+
     # Creates a new Scout Server connection.
     def initialize(server, client_key, history_file, logger = nil)
       @server       = server
@@ -42,56 +45,116 @@ module Scout
       @history_file = history_file
       @history      = Hash.new
       @logger       = logger
-      
+      @plugin_plan  = []
+      @directives   = {} # take_snapshots
+      @new_plan     = false
+
+      # the block is only passed for install and test, since we split plan retrieval outside the lockfile for run
       if block_given?
         load_history
         yield self
         save_history
       end
     end
-    
-    # Prepares a check-in data structure to hold Plugin generated data.
-    def prepare_checkin
-      @checkin = { :reports   => Array.new,
-                   :alerts    => Array.new,
-                   :errors    => Array.new,
-                   :summaries => Array.new }
-    end
-    
-    def show_checkin(printer = :p)
-      send(printer, @checkin)
-    end
-    
-    # 
-    # Loads the history file from disk. If the file does not exist, 
-    # it creates one.
+
     #
-    def load_history
-      unless File.exist? @history_file
-        debug "Creating empty history file..."
-        File.open(@history_file, "w") do |file|
-          YAML.dump({"last_runs" => Hash.new, "memory" => Hash.new}, file)
+    # Retrieves the Plugin Plan from the server. This is the list of plugins
+    # to execute, along with all options.
+    #
+    # This method has a couple of side effects:
+    # 1) it sets the @plugin plan with either A) whatever is in history, B) the results of the /plan retrieval
+    # 2) it sets @checkin_to = true IF so directed by the scout server
+    def fetch_plan
+      url = urlify(:plan)
+      info "Pinging server at #{url}..."
+      headers = Hash.new
+      if @history["plan_last_modified"] and @history["old_plugins"]
+        headers["If-Modified-Since"] = @history["plan_last_modified"]
+      end
+      get(url, "Could not retrieve plan from server.", headers) do |res|
+        if res.is_a? Net::HTTPNotModified
+          info "Plan not modified. Will reuse saved plan."
+          @plugin_plan = Array(@history["old_plugins"])
+          @directives = @history["directives"] || Hash.new
+        else
+          info "plan has been modified. Will run the new plan now."
+          begin
+            body = res.body
+            if res["Content-Encoding"] == "gzip" and body and not body.empty?
+              body = Zlib::GzipReader.new(StringIO.new(body)).read
+            end
+
+            body_as_hash = JSON.parse(body)
+            @plugin_plan = Array(body_as_hash["plugins"])
+            @directives = body_as_hash["directives"].is_a?(Hash) ? body_as_hash["directives"] : Hash.new
+
+            @history["plan_last_modified"] = res["last-modified"]
+            @history["old_plugins"]        = @plugin_plan
+            @history["directives"]         = @directives
+
+            info "Plan loaded.  (#{@plugin_plan.size} plugins:  " +
+                 "#{@plugin_plan.map { |p| p['name'] }.join(', ')})" +
+                 ". Directives: #{@directives.to_a.map{|a|  "#{a.first}:#{a.last}"}.join(", ")}"
+
+            @new_plan = true # used in determination if we should checkin this time or not
+          rescue Exception
+            fatal "Plan from server was malformed."
+            exit
+          end
         end
-        info "History file created."
       end
-      debug "Loading history file..."
-      @history = File.open(@history_file) { |file| YAML.load(file) }
-      info "History file loaded."
     end
-    
-    # Saves the history file to disk.
-    def save_history
-      debug "Saving history file..."
-      File.open(@history_file, "w") { |file| YAML.dump(@history, file) }
-      info "History file saved."
+
+    # uses values from history and current time to determine if we should checkin at this time
+    def time_to_checkin?
+      @history['last_checkin'] == nil ||
+              @directives['interval'] == nil ||
+              (Time.now.to_i - Time.at(@history['last_checkin']).to_i).abs+15 > @directives['interval'].to_i*60
+    rescue
+      debug "Failed to calculate time_to_checkin. @history['last_checkin']=#{@history['last_checkin']}. "+
+              "@directives['interval']=#{@directives['interval']}. Time.now.to_i=#{Time.now.to_i}"
+      return true
     end
-    
-    # Runs all plugins from a given plan. Calls process_plugin on each plugin.
+
+    # uses values from history and current time to determine if we should ping the server at this time
+    def time_to_ping?
+      return true if
+      @history['last_ping'] == nil ||
+              @directives['ping_interval'] == nil ||
+              (Time.now.to_i - Time.at(@history['last_ping']).to_i).abs+15 > @directives['ping_interval'].to_i*60
+    rescue
+      debug "Failed to calculate time_to_ping. @history['last_ping']=#{@history['last_ping']}. "+
+              "@directives['ping_interval']=#{@directives['ping_interval']}. Time.now.to_i=#{Time.now.to_i}"
+      return true
+    end
+
+    # returns a human-readable representation of the next checkin, i.e., 5min 30sec
+    def next_checkin
+      secs= @directives['interval'].to_i*60 - (Time.now.to_i - Time.at(@history['last_checkin']).to_i).abs
+      minutes=(secs.to_f/60).floor
+      secs=secs%60
+      "#{minutes}min #{secs} sec"
+    rescue
+      "[next scout invocation]"
+    end
+
+    # Runs all plugins from the given plan. Calls process_plugin on each plugin.
+    # @plugin_execution_plan is populated by calling fetch_plan
     def run_plugins_by_plan
       prepare_checkin
-      plan do |plugin|
-        process_plugin(plugin)
+      @plugin_plan.each do |plugin|
+        begin
+          process_plugin(plugin)
+        rescue Exception
+          @checkin[:errors] << build_report(
+            plugin['id'],
+            :subject => "Exception:  #{$!.message}.",
+            :body    => $!.backtrace
+          )
+          error("Encountered an error: #{$!.message}")
+        end
       end
+      take_snapshot if @directives['take_snapshots']
       checkin
     end
     
@@ -105,7 +168,7 @@ module Scout
     # set memory and last_run information in the history file.
     # 
     def process_plugin(plugin)
-      info "Processing the #{plugin['name']} plugin:"
+      info "Processing the '#{plugin['name']}' plugin:"
       id_and_name = "#{plugin['id']}-#{plugin['name']}".sub(/\A-/, "")
       last_run    = @history["last_runs"][id_and_name] ||
                     @history["last_runs"][plugin['name']]
@@ -126,6 +189,7 @@ module Scout
         rescue Exception
           raise if $!.is_a? SystemExit
           error "Plugin would not compile: #{$!.message}"
+          @checkin[:errors] << build_report(plugin['id'],:subject => "Plugin would not compile", :body=>$!.message)
           return
         end
         debug "Loading plugin..."
@@ -140,13 +204,19 @@ module Scout
             Timeout.timeout(timeout, PluginTimeoutError) do
               data = job.run
             end
-          rescue Timeout::Error
+          rescue Timeout::Error, PluginTimeoutError
             error "Plugin took too long to run."
+            @checkin[:errors] << build_report(plugin['id'],
+                                              :subject => "Plugin took too long to run",
+                                              :body=>"Execution timed out.")
             return
           rescue Exception
             raise if $!.is_a? SystemExit
             error "Plugin failed to run: #{$!.class}: #{$!.message}\n" +
                   "#{$!.backtrace.join("\n")}"
+            @checkin[:errors] << build_report(plugin['id'],
+                                              :subject => "Plugin failed to run",
+                                              :body=>"#{$!.class}: #{$!.message}\n#{$!.backtrace.join("\n")}")
           end
           info "Plugin completed its run."
           
@@ -168,7 +238,7 @@ module Scout
           @history["memory"][id_and_name]    = data[:memory]
         else
           @checkin[:errors] << build_report(
-            plugin_id['id'],
+            plugin['id'],
             :subject => "Plugin would not load."
           )
         end
@@ -189,57 +259,62 @@ module Scout
           error "Unable to remove plugin."
         end
       end
-      info "Plugin #{plugin['name']} processing complete."
+      info "Plugin '#{plugin['name']}' processing complete."
     end
-    
-    # 
-    # Retrieves the Plugin Plan from the server. This is the list of plugins 
-    # to execute, along with all options.
-    # 
-    def plan
-      url = urlify(:plan)
-      info "Loading plan from #{url}..."
-      headers = Hash.new
-      if @history["last_modified_for_plugins"] and @history["old_plugins"]
-        headers["If-Modified-Since"] = @history["last_modified_for_plugins"]
+
+
+    # captures a list of processes running at this moment
+    def take_snapshot
+      info "Taking a process snapshot"
+      ps=%x(ps aux).split("\n")[1..-1].join("\n") # get rid of the header line
+      @checkin[:snapshot]=ps
+      rescue Exception
+        error "unable to capture processes on this server. #{$!.message}"
+        return nil
+    end
+
+    # Prepares a check-in data structure to hold Plugin generated data.
+    def prepare_checkin
+      @checkin = { :reports   => Array.new,
+                   :alerts    => Array.new,
+                   :errors    => Array.new,
+                   :summaries => Array.new,
+                   :snapshot  => '' }
+    end
+
+    def show_checkin(printer = :p)
+      send(printer, @checkin)
+    end
+
+    #
+    # Loads the history file from disk. If the file does not exist,
+    # it creates one.
+    #
+    def load_history
+      unless File.exist? @history_file
+        create_blank_history
       end
-      get(url, "Could not retrieve plan from server.", headers) do |res|
-        if res.is_a? Net::HTTPNotModified
-          info "Plan not modified.  Reusing saved plan."
-          plugin_execution_plan = Array(@history["old_plugins"])
-        else
-          begin
-            body = res.body
-            if res["Content-Encoding"] == "gzip" and body and not body.empty?
-              body = Zlib::GzipReader.new(StringIO.new(body)).read
-            end
-            plugin_execution_plan = Array(JSON.parse(body)["plugins"])
-            if res["Last-Modified"]
-              @history["last_modified_for_plugins"] = res["last-modified"]
-              @history["old_plugins"]               = plugin_execution_plan
-            end
-            info "Plan loaded.  (#{plugin_execution_plan.size} plugins:  " +
-                 "#{plugin_execution_plan.map { |p| p['name'] }.join(', ')})"
-          rescue Exception
-            fatal "Plan from server was malformed."
-            exit
-          end
-        end
-        plugin_execution_plan.each do |plugin|
-          begin
-            yield plugin if block_given?
-          rescue RuntimeError
-            @checkin[:errors] << build_report(
-              plugin_id['id'],
-              :subject => "Exception:  #{$!.message}.",
-              :body    => $!.backtrace
-            )
-          end
-        end
+      debug "Loading history file..."
+      @history = File.open(@history_file) { |file| YAML.load(file) }
+      info "History file loaded."
+    end
+
+    # creates a blank history file
+    def create_blank_history
+      debug "Creating empty history file..."
+      File.open(@history_file, "w") do |file|
+        YAML.dump({"last_runs" => Hash.new, "memory" => Hash.new}, file)
       end
+      info "History file created."      
+    end    
+
+    # Saves the history file to disk.
+    def save_history
+      debug "Saving history file..."
+      File.open(@history_file, "w") { |file| YAML.dump(@history, file) }
+      info "History file saved."
     end
-    alias_method :test, :plan
-    
+
     private
     
     def build_report(plugin_id, fields)
@@ -293,8 +368,9 @@ module Scout
       when Net::HTTPSuccess, Net::HTTPNotModified
         response_handler[response] unless response_handler.nil?
       else
+        error = "Server says: #{response['x-scout-msg']}" if response['x-scout-msg']
         fatal error
-        exit
+        raise SystemExit.new(error)
       end
     rescue Timeout::Error
       fatal "Request timed out."
@@ -306,6 +382,7 @@ module Scout
     end
     
     def checkin
+      @history['last_checkin'] = Time.now.to_i # might have to save the time of invocation and use here to prevent drift
       io   =  StringIO.new
       gzip =  Zlib::GzipWriter.new(io)
       gzip << @checkin.to_json

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: scout
 version: !ruby/object:Gem::Version 
-  version: 4.0.2
+  version: 5.0.2
 platform: ruby
 authors: 
 - Highgroove Studios
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-07 00:00:00 -05:00
+date: 2009-12-23 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -46,18 +46,12 @@ files:
 - lib/scout/command/test.rb
 - lib/scout/command.rb
 - lib/scout/plugin.rb
+- lib/scout/plugin_options.rb
 - lib/scout/server.rb
 - lib/scout.rb
 - data/cacert.pem
 - data/gpl-2.0.txt
 - data/lgpl-2.1.txt
-- vendor/json_pure/CHANGES
-- vendor/json_pure/GPL
-- vendor/json_pure/README
-- vendor/json_pure/RUBY
-- vendor/json_pure/Rakefile
-- vendor/json_pure/TODO
-- vendor/json_pure/VERSION
 - vendor/json_pure/benchmarks/data-p4-3GHz-ruby18/GeneratorBenchmarkComparison.log
 - vendor/json_pure/benchmarks/data-p4-3GHz-ruby18/GeneratorBenchmarkExt#generator_fast-autocorrelation.dat
 - vendor/json_pure/benchmarks/data-p4-3GHz-ruby18/GeneratorBenchmarkExt#generator_fast.dat
@@ -93,6 +87,7 @@ files:
 - vendor/json_pure/benchmarks/parser_benchmark.rb
 - vendor/json_pure/bin/edit_json.rb
 - vendor/json_pure/bin/prettify_json.rb
+- vendor/json_pure/CHANGES
 - vendor/json_pure/data/example.json
 - vendor/json_pure/data/index.html
 - vendor/json_pure/data/prototype.js
@@ -106,26 +101,30 @@ files:
 - vendor/json_pure/ext/json/ext/parser/parser.rl
 - vendor/json_pure/ext/json/ext/parser/unicode.c
 - vendor/json_pure/ext/json/ext/parser/unicode.h
+- vendor/json_pure/GPL
 - vendor/json_pure/install.rb
-- vendor/json_pure/lib/json/Array.xpm
-- vendor/json_pure/lib/json/FalseClass.xpm
-- vendor/json_pure/lib/json/Hash.xpm
-- vendor/json_pure/lib/json/Key.xpm
-- vendor/json_pure/lib/json/NilClass.xpm
-- vendor/json_pure/lib/json/Numeric.xpm
-- vendor/json_pure/lib/json/String.xpm
-- vendor/json_pure/lib/json/TrueClass.xpm
 - vendor/json_pure/lib/json/add/core.rb
 - vendor/json_pure/lib/json/add/rails.rb
+- vendor/json_pure/lib/json/Array.xpm
 - vendor/json_pure/lib/json/common.rb
 - vendor/json_pure/lib/json/editor.rb
 - vendor/json_pure/lib/json/ext.rb
+- vendor/json_pure/lib/json/FalseClass.xpm
+- vendor/json_pure/lib/json/Hash.xpm
 - vendor/json_pure/lib/json/json.xpm
+- vendor/json_pure/lib/json/Key.xpm
+- vendor/json_pure/lib/json/NilClass.xpm
+- vendor/json_pure/lib/json/Numeric.xpm
 - vendor/json_pure/lib/json/pure/generator.rb
 - vendor/json_pure/lib/json/pure/parser.rb
 - vendor/json_pure/lib/json/pure.rb
+- vendor/json_pure/lib/json/String.xpm
+- vendor/json_pure/lib/json/TrueClass.xpm
 - vendor/json_pure/lib/json/version.rb
 - vendor/json_pure/lib/json.rb
+- vendor/json_pure/Rakefile
+- vendor/json_pure/README
+- vendor/json_pure/RUBY
 - vendor/json_pure/tests/fixtures/fail1.json
 - vendor/json_pure/tests/fixtures/fail10.json
 - vendor/json_pure/tests/fixtures/fail11.json
@@ -163,8 +162,10 @@ files:
 - vendor/json_pure/tests/test_json_generate.rb
 - vendor/json_pure/tests/test_json_rails.rb
 - vendor/json_pure/tests/test_json_unicode.rb
+- vendor/json_pure/TODO
 - vendor/json_pure/tools/fuzz.rb
 - vendor/json_pure/tools/server.rb
+- vendor/json_pure/VERSION
 - Rakefile
 - AUTHORS
 - COPYING