jobmanager 1.0.1 → 1.1.0

data/History.txt

@@ -1,4 +1,10 @@
-=== 1.0.1 / 2007-08-27
+=== 1.1.0 / 2009-06-01
+The following changes were made:
+* jobmanager no longer generates a job log file (nor rotates) in the case that the job output is empty.
+* jobmanager can now be configured to email job results only when the job output is not empty ("on_job_output_or_failure").
+* jobmanager can now be configured to not rotate the job log files
+* jobmanager can now be configured to prepend the date/time to each line of a job log file.
+=== 1.0.1 / 2008-08-27
 Remove the dependency on the sys-host gem.
 === 1.0.0 / 2008-07-18
 Initial release of jobmanager.  This package is unit tested fully.

data/Manifest.txt

@@ -7,21 +7,23 @@ Rakefile
 bin/jobmanager
 examples/email_settings.rb
 examples/example.rb
-examples/mysql_backup.rb
 examples/jobmanager.yaml
 lib/jobmanager.rb
 lib/jobmanager/applicationconfig.rb
 lib/jobmanager/applicationlogger.rb
 lib/jobmanager/applicationoptionparser.rb
 lib/jobmanager/application.rb
+lib/jobmanager/openonfirstwritefile.rb
 lib/jobmanager/system.rb
 lib/jobmanager/teestream.rb
+lib/jobmanager/timestampedstream.rb
 lib/jobmanager/util.rb
 test/helpers.rb
 test/mock_syslog.rb
 test/test_applicationlogger.rb
 test/test_config.rb
 test/test_jobmanager.rb
+test/test_openonfirstwritefile.rb
 test/test_system.rb
 test/test_teestream.rb
 test/configs/email_settings.rb
@@ -37,6 +39,8 @@ test/configs/jobmanager_3.yaml
 test/configs/jobmanager_4_bad_central_log_file.yaml
 test/configs/jobmanager_4_bad_email_settings_file.yaml
 test/configs/jobmanager_4_bad_job_logs_directory_1.yaml
-test/configs/jobmanager_4_bad_job_logs_directory_2.yaml
+test/configs/jobmanager_5_bad_job_log_file.yaml
+test/configs/jobmanager_6.yaml
+test/configs/jobmanager_7_no_log_rotation.yaml
 test/configs/minimum_plus_email_settings.yaml
 test/configs/minimum_required.yaml

data/README.txt

@@ -25,11 +25,11 @@ added value:
 Lets walk through an example invocation of +jobmanager+ via cron.  
 
 Here is an example +crontab+ entry that invokes a simplified database
-backup script via +jobmanager+ every day at 22:00.
- 00 22 * * * jobmanager --job_name nightly_backup "mysql_backup test"
+backup script via +jobmanager+ every day at 17:16.
+ 16 17 * * * jobmanager --job_name nightly_backup "mysql_backup test"
 
 Here is the example +mysql_backup+ script referenced above:
-======<tt>examples/mysql_backup.rb</tt>:
+======<tt>examples/mysql_backup</tt>:
  #!/usr/bin/env ruby
  
  print "=================================================\n"
@@ -50,10 +50,10 @@ Here is the example +mysql_backup+ script referenced above:
  
 
 
-Here is the configuration file to be read by +jobmanager+.
+Here is the example configuration file to be read by +jobmanager+.
 ======<tt>/etc/jobmanager.yaml</tt>:
  ################################################################################
- # The jobmanager configuration file.
+ # An example jobmanager configuration file.
  #
  # For a full description of each of the fields, and their default values,
  # see the CONFIGURATION FILE section in README.txt.
@@ -76,14 +76,14 @@ Here is the configuration file to be read by +jobmanager+.
  # variables: user_name.
  central_log_file: /tmp/logs/jobmanager.log
  
- # The path to search for the command that jobmanager is invoked with.  
+ # The path to search for the command that jobmanager is invoked with.
  #command_path: /usr/bin:/usr/designingpatterns/bin
  
  # Whether jobmanager should print debug trace to the central log file.
- debug: false
+ #debug: true
  
  # The condition upon which condition results should be emailed.
- # Possible values are: always, never, on_failure.  
+ # Possible values are: always, never, on_failure, on_job_output_or_failure.
  email_condition: always
  
  # The configuration file for the simpleemail gem.  This parameter will
@@ -96,21 +96,31 @@ Here is the configuration file to be read by +jobmanager+.
  # Allowed variables: job_name, command, host_name, results, user_name.
  email_subject: "jobmanager results for <%=job_name%> on <%=host_name%> : <%=result%>"
  
- # The extension of the rotated job log file.  If true, the extension
- # is a date_time.  Otherwise, it is a simple count (.1, .2, etc.).
- date_time_extension: true
+ # Whether the job log file should be rotated.
+ #rotate_job_log: false
+ 
+ # The extension of the rotated job log file.  
+ # True -> The extension is a date_time.
+ # False -> It is a simple count (.1, .2, etc.).
+ #date_time_extension: true
  
  # If date_time_extension is true, this field will be used as the
  # format for the date/time extension of the rotated job log file
  # name.
- date_time_extension_format: '%F_%T'
+ #date_time_extension_format: '%F_%T'
  
  # Whether the rotated job log file should be zipped.
- zip_rotated_log_file: false
+ #zip_rotated_log_file: true
  
  # The timeout (in seconds).  If not present, no timeout will be used.
  timeout: 1800
  
+ # Whether each line in the job log file will be prepended with the date/time.
+ #job_log_prepend_date_time: true
+ 
+ # The date/time format of the prepended date/time.
+ #job_log_prepend_date_time: '%F_%T'
+ 
  # The sender of emails sent from jobmanager.  This can also be
  # specified in the email_settings_file (attribute default_from).
  #email_from_address: "Sender <sender@gmail.com>"
@@ -141,15 +151,21 @@ sendmail is also an option.  This file is documented further in the
  SimpleEmail::Email.default_to = "Receiver Address <receiver_address@gmail.com>"
 
 
+Note: In order to run this example oneself, either
+* +mysql_backup+ script must live in a directory that is in one's path, or
+* the +command_path+ field in +jobmanager.yaml+ must be set to include the path 
+  where +mysql_backup+ lives.
+
 Here is the central log file that +jobmanager+ updated.
 ======<tt>/tmp/logs/jobmanager.log</tt>:
- I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Command (/usr/bin/mysql_backup test) launched, pid = 2302.
- I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Exited successfully
- I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Job log rotated to /tmp/logs/nightly_backup.log.2008-07-30_22:00:00.
+ I, [2009-06-01T17:16:32 #32235]  INFO -- : [janet, nightly_backup] Command (/usr/bin/mysql_backup test) launched, pid = 32237.
+ I, [2009-06-01T17:16:33 #32235]  INFO -- : [janet, nightly_backup] Job exited successfully
+ I, [2009-06-01T17:16:33 #32235]  INFO -- : [janet, nightly_backup] Job log rotated to /tmp/logs/nightly_backup.log.2009-06-01_17:16:33.
+ I, [2009-06-01T17:16:33 #32235]  INFO -- : [janet, nightly_backup] Sent mail to Receiver Address <receiver_address@gmail.com>
 
 
 Here is the rotated job log file.
-======<tt>/tmp/logs/nightly_backup.log.2008-07-30_22:00:00</tt>:
+======<tt>/tmp/logs/nightly_backup.log.2009-06-01_17:16:33</tt>:
  =================================================
  Backing up Database
  =================================================
@@ -157,6 +173,7 @@ Here is the rotated job log file.
  
  Success!
 
+
 Here is the subject and body of the email that was sent upon job completion.
 
 ======<tt>Email Subject</tt>:
@@ -166,9 +183,9 @@ Here is the subject and body of the email that was sent upon job completion.
  ---------------------------------------------------------
  jobmanager Output:
  ---------------------------------------------------------
- I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Command (/usr/bin/mysql_backup test) launched, pid = 2302.
- I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Exited successfully
- I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Job log rotated to /tmp/logs/nightly_backup.log.2008-08-01_11:29:47.
+ I, [2009-06-01T17:16:23 #32219]  INFO -- : [janet, nightly_backup] Command (/usr/bin/mysql_backup test) launched, pid = 32222.
+ I, [2009-06-01T17:16:24 #32219]  INFO -- : [janet, nightly_backup] Job exited successfully
+ I, [2009-06-01T17:16:24 #32219]  INFO -- : [janet, nightly_backup] Job log rotated to /tmp/logs/nightly_backup.log.2009-06-01_17:16:24.
  
  ---------------------------------------------------------
  Job Output:
@@ -216,6 +233,15 @@ The configuration file provides the following parameters:
 [+number_of_job_logs+: optional, default: +3+]
    The number of logs to be kept per job.
 
+[+job_log_prepend_date_time+: optional, default: +false+]
+   Whether the current date/time should be prepended to each line of the
+   job log file.
+
+[+job_log_prepend_date_time_format+: optional, default: <tt>'%F_%T'</tt> ]
+   if +job_log_prepend_date_time+ is +true+, this parameter will be used as
+   the format for the date/time that is prepended to each line of the job
+   log file.
+
 [+command_path+: optional, default: <tt>ENV['PATH']</tt> ]
    The path to be searched for the command that +jobmanager+ is
    invoked with.  If unspecified, the environment path will be used.
@@ -225,7 +251,9 @@ The configuration file provides the following parameters:
 
 [+email_condition+: optional, default: +on_failure+]
    The condition upon which results should be emailed.  Possible
-   values are: <tt>always, never, on_failure</tt>.
+   values are: <tt>always, never, on_failure, on_job_output_or_failure</tt>.
+   The condition +on_job_output_or_failure+ denotes that an email will be
+   sent if the job failed and/or the job output was non-empty.
 
 [+email_settings_file+: optional, default: +email_settings.rb+]
   The configuration file for the
@@ -243,34 +271,38 @@ The configuration file provides the following parameters:
   separate email settings files.
 
 
-[+email_subject+, optional, default: <tt>"jobmanager results for <%=job_name%> on <%=host_name%> : <%=result%>"</tt>]
+[+email_subject+: optional, default: <tt>"jobmanager results for <%=job_name%> on <%=host_name%> : <%=result%>"</tt>]
   The email subject, to be interpreted by ERB.  Allowed variables
   inside the string are: <tt>job_name, command, host_name, results, user_name</tt>.
 
-[+date_time_extension+, optional, default: +true+]
+[+rotate_job_log+: optional, default: +true+]
+   Whether the job log file should be rotated.  If the job log file is not
+   rotated, it will simply be appended to during each run.
+
+[+date_time_extension+: optional, default: +true+]
    This refers to the extension of the rotated job log file.  If
    +date_time_extension+ is present and set to +true+, the extension
    represents a date and time.  Otherwise, it is a simple count (.1, .2, etc.).
 
-[+date_time_extension_format+, optional, default: <tt>'%F_%T'</tt>]
+[+date_time_extension_format+: optional, default: <tt>'%F_%T'</tt>]
    If +date_time_extension+ is +true+, this parameter will be used as the
    format for the date and time extension of the rotated job log file.
 
-[+zip_rotated_log_file+, optional, default: +false+]
+[+zip_rotated_log_file+: optional, default: +false+]
    Whether the rotated job log file should be gzip'ed.
 
-[+timeout+, optional]
+[+timeout+: optional]
    The timeout (in seconds).  If the job spawned by +jobmanager+ does not
    exit after +timeout+ seconds, +jobmanager+ will kill the process, and
    report failure.  If +timeout+ is unspecifed, +jobmanager+ will let the
    process run for an unlimited amount of time (+jobmanager+ will simply
    wait til it returns).
 
-[+email_from_address+, optional]
+[+email_from_address+: optional]
    The sender of emails sent from +jobmanager+.  This can also be
    specified in the +email_settings_file+ (attribute +default_from+).
 
-[+email_to_address+, optional]
+[+email_to_address+: optional]
    The receiver of emails sent from +jobmanager+.  This can also be
    specified in the +email_settings_file+ (attribute +default_to+).
 
@@ -321,7 +353,8 @@ listed above are required for the proper functioning of the
 
 2. Set up the +jobmanager+ configuration file (+jobmanager.yaml+).
    For more detailed instructions, see the CONFIGURATION FILE section
-   above.
+   above.  There is an example file provided in this distribution:
+   +examples/jobmanager.yaml+.
 
 3. Set up the simpleemail configuration file (+email_settings.rb+).
    Alternately, if you want to disable email, set the configuration
@@ -329,9 +362,10 @@ listed above are required for the proper functioning of the
    the {+simpleemail+}[http://simpleemail.rubyforge.org] gem rdoc for
    more details.
 
-4. Confirm that the configuration files are valid by invoking
-   +jobmanager+ from the command line with one of your cron jobs or a
-   test command.
+4. Confirm that the configuration files are valid by invoking +jobmanager+
+   from the command line with one of your cron jobs or a test command.  If 
+   +jobmanager+ is invoked via the command line, the central log will be 
+   redirected to screen (instead of the central log file).
 
 5. Edit your +crontab+ to run new and/or existing cron jobs through
    +jobmanager+.

data/Rakefile

@@ -2,14 +2,14 @@
 require 'rubygems'
 require 'hoe'
 
-Hoe.new('jobmanager', "1.0.1") do |p|
+Hoe.new('jobmanager', "1.1.0") do |p|
   p.remote_rdoc_dir = ''
   p.developer('DesigningPatterns', 'technical.inquiries@designingpatterns.com')
 
   p.extra_deps << ['simpleemail']
   p.extra_deps << ['configtoolkit', '>= 2.2']
   p.extra_deps << ['relative']
-  p.extra_deps << ['logrotate']
+  p.extra_deps << ['logrotate', '>= 1.1']
   p.extra_deps << ['SyslogLogger']
 end
 

data/examples/jobmanager.yaml

@@ -1,5 +1,5 @@
 ################################################################################
-# The jobmanager configuration file.
+# An example jobmanager configuration file.
 #
 # For a full description of each of the fields, and their default values,
 # see the CONFIGURATION FILE section in README.txt.
@@ -22,14 +22,14 @@ central_log_mode: file
 # variables: user_name.
 central_log_file: /tmp/logs/jobmanager.log
 
-# The path to search for the command that jobmanager is invoked with.  
+# The path to search for the command that jobmanager is invoked with.
 #command_path: /usr/bin:/usr/designingpatterns/bin
 
 # Whether jobmanager should print debug trace to the central log file.
-debug: false
+#debug: true
 
 # The condition upon which condition results should be emailed.
-# Possible values are: always, never, on_failure.  
+# Possible values are: always, never, on_failure, on_job_output_or_failure.
 email_condition: always
 
 # The configuration file for the simpleemail gem.  This parameter will
@@ -42,21 +42,31 @@ email_settings_file: email_settings.rb
 # Allowed variables: job_name, command, host_name, results, user_name.
 email_subject: "jobmanager results for <%=job_name%> on <%=host_name%> : <%=result%>"
 
-# The extension of the rotated job log file.  If true, the extension
-# is a date_time.  Otherwise, it is a simple count (.1, .2, etc.).
-date_time_extension: true
+# Whether the job log file should be rotated.
+#rotate_job_log: false
+
+# The extension of the rotated job log file.  
+# True -> The extension is a date_time.
+# False -> It is a simple count (.1, .2, etc.).
+#date_time_extension: true
 
 # If date_time_extension is true, this field will be used as the
 # format for the date/time extension of the rotated job log file
 # name.
-date_time_extension_format: '%F_%T'
+#date_time_extension_format: '%F_%T'
 
 # Whether the rotated job log file should be zipped.
-zip_rotated_log_file: false
+#zip_rotated_log_file: true
 
 # The timeout (in seconds).  If not present, no timeout will be used.
 timeout: 1800
 
+# Whether each line in the job log file will be prepended with the date/time.
+#job_log_prepend_date_time: true
+
+# The date/time format of the prepended date/time.
+#job_log_prepend_date_time: '%F_%T'
+
 # The sender of emails sent from jobmanager.  This can also be
 # specified in the email_settings_file (attribute default_from).
 #email_from_address: "Sender <sender@gmail.com>"

data/lib/jobmanager/application.rb

@@ -22,7 +22,9 @@ require 'jobmanager/applicationconfig'
 require 'jobmanager/applicationoptionparser'
 require 'jobmanager/system'
 require 'jobmanager/teestream'
+require 'jobmanager/timestampedstream'
 require 'jobmanager/applicationlogger'
+require 'jobmanager/openonfirstwritefile'
 
 module JobManager
 
@@ -182,20 +184,15 @@ module JobManager
     def run()      
       success = false
       
-      begin
-        FileUtils.mkdir_p(@config.job_logs_directory)
-      rescue => e
-        raise ComposedError.new("Error creating job_logs_directory", e)
-      end
-      
       job_log_file = File.join(@config.job_logs_directory, "#{@config.job_name}.log")
-      @mgr_logger.debug("Opening job log file #{job_log_file}.")
+      @mgr_logger.debug("Job log file: #{job_log_file}.")
       
-      begin
-        job_log_file_stream = File.open(job_log_file, "w")
-      rescue => e
-        raise ComposedError.new("Error opening job log file", e)
-      end
+      #
+      # Create a stream that only opens the specified file when the
+      # first write is called.  This is to prevent empty files from
+      # being created.
+      #
+      job_log_file_stream = OpenOnFirstWriteFile.new(job_log_file, "a")
       
       #
       # The output of the job that will be invoked will be sent back
@@ -216,9 +213,13 @@ module JobManager
       # TeeStream to forward strings to the job log file stream and a
       # string stream (which will be later used for emailing results).
       #
+      job_output = ""
       begin
-        job_tee_stream = TeeStream.new(:file => job_log_file_stream,
-                                       :stringio => StringIO.new())
+        job_stream = TeeStream.new(:file => job_log_file_stream,
+                                   :stringio => StringIO.new())
+        if (@config.job_log_prepend_date_time)
+          job_stream = TimestampedStream.new(job_stream, @config.job_log_prepend_date_time_format)
+        end
         
         optional_args = {}
         if @config.timeout then optional_args[:timeout] = @config.timeout end
@@ -226,23 +227,23 @@ module JobManager
         
         # invoke the command - fork and exec the process, and wait til it finishes to reap the status.
         success = System::invoke_command(@config.command, 
-                                         job_tee_stream,
+                                         job_stream,
                                          @mgr_logger,
                                          optional_args)
         
-        job_output = job_tee_stream.get_stream(:stringio).string()
-        job_tee_stream.close()
+        if (job_stream.is_a?(TimestampedStream))
+          job_stream = job_stream.stream()
+        end
+        job_output = job_stream.stream(:stringio).string()
+        job_stream.close()
         
       rescue => e
         @mgr_logger.record_tagged_exception("Error running job", e)
       end
       
       # Rotate the job log file.
-      begin
-        if (File.file?(job_log_file))
-          
-          before_entries = Dir.glob("#{@config.job_logs_directory}/#{@config.job_name}*")
-          
+      if (@config.rotate_job_log && File.file?(job_log_file))
+        begin
           logrotate_options = { 
             :count => @config.number_of_job_logs,
             :date_time_ext => @config.date_time_extension,
@@ -250,20 +251,20 @@ module JobManager
             :gzip => @config.zip_rotated_log_file
           }
           
-          LogRotate.rotate_file(job_log_file, logrotate_options)
+          result = LogRotate.rotate_file(job_log_file, logrotate_options)
           
-          rotated_file = (Dir.glob("#{@config.job_logs_directory}/#{@config.job_name}*") - before_entries)[0]
-          @mgr_logger.info("Job log rotated to #{rotated_file}.")
+          @mgr_logger.info("Job log rotated to #{result.new_rotated_file}.")
+        rescue => e
+          success = false
+          @mgr_logger.record_tagged_exception("Error rotating file #{job_log_file}", e)
         end
-      rescue => e
-        success = false
-        @mgr_logger.record_tagged_exception("Error rotating file #{job_log_file}", e)
       end
       
       # Email the results!
       begin
         if (@config.email_condition == :always || 
-            (@config.email_condition == :on_failure && !success))
+            (@config.email_condition == :on_failure && !success) ||
+            (@config.email_condition == :on_job_output_or_failure && (!success || job_output.length > 0)))
           
           email_results(success, job_output)
         end
@@ -340,7 +341,7 @@ module JobManager
           
           @config.email_settings_file = value
         end
-
+        
         # Note: From/To email addresses can be specified in either the
         # jobmanager configuration file or the simpleemail gem
         # configuration file.
@@ -372,7 +373,7 @@ module JobManager
         begin
           new_logger = ApplicationFileLogger.new(@config.central_log_file,
                                                  @user_name)
-
+          
           old_logger = @mgr_logger
           @mgr_logger = new_logger
           old_logger.close