logging 1.6.2 → 1.7.0

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+
+before_install: "gem install bones"
+install:        "rake gem:install_dependencies"
+
+script: "rake"
+
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby
+

data/History.txt

@@ -1,3 +1,13 @@
+== 1.7.0 / 2012-02-18
+
+Enhancements
+- Move appender factories [issue #28]
+- ActionMail compatible options in the email appender [issue #27]
+- Add TLS support to the email appender [issue #25]
+- Refactoring appender shutdown [issue #20]
+Bug Fixes
+- File locking fails on windows using JRuby [issue #22]
+
 == 1.6.2 / 2012-01-05
 
 Bug Fixes

data/README.rdoc

@@ -1,5 +1,5 @@
-Logging
-    by Tim Pease
+= Logging
+by Tim Pease {<img src="https://secure.travis-ci.org/TwP/logging.png">}[http://travis-ci.org/TwP/logging]
 
 * {Homepage}[http://rubygems.org/gems/logging]
 * {Github Project}[http://github.com/TwP/logging]
@@ -116,4 +116,25 @@ Always remember that "rake -T" is your friend!
 
 == LICENSE
 
-Ruby
+The MIT License
+
+Copyright (c) 2012 Tim Pease
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -17,7 +17,7 @@ Bones {
 
   rdoc.exclude << '^data'
   rdoc.include << '^examples/.*\.rb'
-  rcov.opts    << '-x' << '~/.rvm/'
+  #rcov.opts    << '-x' << '~/.rvm/'
 
   use_gmail
 
@@ -25,6 +25,6 @@ Bones {
 
   depend_on 'flexmock',     :development => true
   depend_on 'bones-git',    :development => true
-  depend_on 'bones-rcov',   :development => true
+  #depend_on 'bones-rcov',   :development => true
 }
 

data/lib/logging.rb

@@ -493,7 +493,7 @@ module Logging
     end
 
     # Close all appenders
-    def shutdown
+    def shutdown( *args )
       log_internal {'shutdown called - closing all appenders'}
       ::Logging::Appenders.each {|appender| appender.close}
     end
@@ -511,34 +511,34 @@ module Logging
     end
     # :startdoc:
   end
-end  # module Logging
-
-
-Logging.libpath {
-  require 'logging/appender'
-  require 'logging/layout'
-  require 'logging/log_event'
-  require 'logging/logger'
-  require 'logging/repository'
-  require 'logging/root_logger'
-  require 'logging/stats'
-  require 'logging/color_scheme'
-  require 'logging/appenders'
-  require 'logging/layouts'
-  require 'logging/proxy'
 
-  require 'logging/config/configurator'
-  require 'logging/config/yaml_configurator'
-
-  require 'logging/rails_compat'
-}
+  require libpath('logging/appender')
+  require libpath('logging/layout')
+  require libpath('logging/log_event')
+  require libpath('logging/logger')
+  require libpath('logging/repository')
+  require libpath('logging/root_logger')
+  require libpath('logging/stats')
+  require libpath('logging/color_scheme')
+  require libpath('logging/appenders')
+  require libpath('logging/layouts')
+  require libpath('logging/proxy')
+
+  require libpath('logging/config/configurator')
+  require libpath('logging/config/yaml_configurator')
+
+  require libpath('logging/rails_compat')
+end  # module Logging
 
 
-# This exit handler will close all the appenders that exist in the system.
+# This finalizer will close all the appenders that exist in the system.
 # This is needed for closing IO streams and connections to the syslog server
 # or e-mail servers, etc.
 #
-at_exit { Logging.shutdown }
+# You can prevent the finalizer from running by calling `exit!` from your
+# application. This is required when daemonizing.
+#
+ObjectSpace.define_finalizer self, Logging.method(:shutdown)
 
 end  # unless defined?
 

data/lib/logging/appender.rb

@@ -42,13 +42,16 @@ class Appender
     self.level = opts.getopt(:level)
 
     @mutex = ReentrantMutex.new
-    header = @layout.header
 
-    unless header.nil? || header.empty?
-      begin
-        write(header)
-      rescue StandardError => err
-        ::Logging.log_internal(-2) {err}
+    if opts.getopt(:header, true)
+      header = @layout.header
+
+      unless header.nil? || header.empty?
+        begin
+          write(header)
+        rescue StandardError => err
+          ::Logging.log_internal(-2) {err}
+        end
       end
     end
 

data/lib/logging/appenders.rb

@@ -2,75 +2,6 @@
 module Logging
   module Appenders
 
-    # Accessor / Factory for the Email appender.
-    #
-    def email( *args )
-      return ::Logging::Appenders::Email if args.empty?
-      ::Logging::Appenders::Email.new(*args)
-    end
-
-    # Accessor / Factory for the File appender.
-    #
-    def file( *args )
-      return ::Logging::Appenders::File if args.empty?
-      ::Logging::Appenders::File.new(*args)
-    end
-
-    # Accessor / Factory for the Growl appender.
-    #
-    def growl( *args )
-      return ::Logging::Appenders::Growl if args.empty?
-      ::Logging::Appenders::Growl.new(*args)
-    end
-
-    # Accessor / Factory for the IO appender.
-    #
-    def io( *args )
-      return ::Logging::Appenders::IO if args.empty?
-      ::Logging::Appenders::IO.new(*args)
-    end
-
-    # Accessor / Factory for the RollingFile appender.
-    #
-    def rolling_file( *args )
-      return ::Logging::Appenders::RollingFile if args.empty?
-      ::Logging::Appenders::RollingFile.new(*args)
-    end
-
-    # Accessor / Factory for the Stderr appender.
-    #
-    def stderr( *args )
-      if args.empty?
-        return self['stderr'] || ::Logging::Appenders::Stderr.new
-      end
-      ::Logging::Appenders::Stderr.new(*args)
-    end
-
-    # Accessor / Factory for the Stdout appender.
-    #
-    def stdout( *args )
-      if args.empty?
-        return self['stdout'] || ::Logging::Appenders::Stdout.new
-      end
-      ::Logging::Appenders::Stdout.new(*args)
-    end
-
-    # Accessor / Factory for the StringIo appender.
-    #
-    def string_io( *args )
-      return ::Logging::Appenders::StringIo if args.empty?
-      ::Logging::Appenders::StringIo.new(*args)
-    end
-
-  if HAVE_SYSLOG
-    # Accessor / Factory for the Syslog appender.
-    #
-    def syslog( *args )
-      return ::Logging::Appenders::Syslog if args.empty?
-      ::Logging::Appenders::Syslog.new(*args)
-    end
-  end
-
     # call-seq:
     #    Appenders[name]
     #
@@ -118,19 +49,16 @@ module Logging
 
     extend self
     @appenders = Hash.new
-
-  end  # module Appenders
-end  # module Logging
-
-Logging.libpath {
-  require 'logging/appenders/buffering'
-  require 'logging/appenders/io'
-  require 'logging/appenders/console'
-  require 'logging/appenders/email'
-  require 'logging/appenders/file'
-  require 'logging/appenders/growl'
-  require 'logging/appenders/rolling_file'
-  require 'logging/appenders/string_io'
-  require 'logging/appenders/syslog'
-}
+  end  # Appenders
+
+  require libpath('logging/appenders/buffering')
+  require libpath('logging/appenders/io')
+  require libpath('logging/appenders/console')
+  require libpath('logging/appenders/email')
+  require libpath('logging/appenders/file')
+  require libpath('logging/appenders/growl')
+  require libpath('logging/appenders/rolling_file')
+  require libpath('logging/appenders/string_io')
+  require libpath('logging/appenders/syslog')
+end  # Logging
 

data/lib/logging/appenders/buffering.rb

@@ -390,6 +390,6 @@ module Logging::Appenders
     end  # class PeriodicFlusher
     # :startdoc:
 
-  end  # module Buffering
-end  # module Logging::Appenders
+  end  # Buffering
+end  # Logging::Appenders
 

data/lib/logging/appenders/console.rb

@@ -1,6 +1,15 @@
 
 module Logging::Appenders
 
+  # Accessor / Factory for the Stdout appender.
+  #
+  def self.stdout( *args )
+    if args.empty?
+      return self['stdout'] || ::Logging::Appenders::Stdout.new
+    end
+    ::Logging::Appenders::Stdout.new(*args)
+  end
+
   # This class provides an Appender that can write to STDOUT.
   #
   class Stdout < ::Logging::Appenders::IO
@@ -26,7 +35,17 @@ module Logging::Appenders
 
       super(name, STDOUT, opts)
     end
-  end  # class Stdout
+  end  # Stdout
+
+
+  # Accessor / Factory for the Stderr appender.
+  #
+  def self.stderr( *args )
+    if args.empty?
+      return self['stderr'] || ::Logging::Appenders::Stderr.new
+    end
+    ::Logging::Appenders::Stderr.new(*args)
+  end
 
   # This class provides an Appender that can write to STDERR.
   #
@@ -53,7 +72,6 @@ module Logging::Appenders
 
       super(name, STDERR, opts)
     end
-  end  # class Stderr
-
-end  # module Logging::Appenders
+  end  # Stderr
+end  # Logging::Appenders
 

data/lib/logging/appenders/email.rb

@@ -2,70 +2,175 @@
 require 'net/smtp'
 require 'time' # get rfc822 time format
 
-# a replacement EmailOutputter.  This is essentially the default EmailOutputter from Log4r but with the following
-# changes:
-#   1) if there is data to send in an email, then do not send anything
-#   2) connect to the smtp server at the last minute, do not connect at startup and then send later on.
-#   3) Fix the To: field so that it looks alright.
 module Logging::Appenders
 
-class Email < ::Logging::Appender
-  include Buffering
-
-  attr_reader :server, :port, :domain, :acct, :authtype, :subject
-
-  # TODO: make the from/to fields modifiable
-  #       possibly the subject, too
-
-  def initialize( name, opts = {} )
-    super(name, opts)
-
-    af = opts.getopt(:buffsize) ||
-         opts.getopt(:buffer_size) ||
-         100
-    configure_buffering({:auto_flushing => af}.merge(opts))
-
-    # get the SMTP parameters
-    @from = opts.getopt(:from)
-    raise ArgumentError, 'Must specify from address' if @from.nil?
-
-    @to = opts.getopt(:to, '').split(',')
-    raise ArgumentError, 'Must specify recipients' if @to.empty?
-
-    @server   = opts.getopt :server, 'localhost'
-    @port     = opts.getopt :port, 25, :as => Integer
-    @domain   = opts.getopt(:domain, ENV['HOSTNAME']) || 'localhost.localdomain'
-    @acct     = opts.getopt :acct
-    @passwd   = opts.getopt :passwd
-    @authtype = opts.getopt :authtype, :cram_md5, :as => Symbol
-    @subject  = opts.getopt :subject, "Message of #{$0}"
-    @params   = [@server, @port, @domain, @acct, @passwd, @authtype]
-  end
-
-
-private
-
-  # This method is called by the buffering code when messages need to be
-  # sent out as an email.
+  # Accessor / Factory for the Email appender.
   #
-  def canonical_write( str )
-    ### build a mail header for RFC 822
-    rfc822msg =  "From: #{@from}\n"
-    rfc822msg << "To: #{@to.join(",")}\n"
-    rfc822msg << "Subject: #{@subject}\n"
-    rfc822msg << "Date: #{Time.new.rfc822}\n"
-    rfc822msg << "Message-Id: <#{"%.8f" % Time.now.to_f}@#{@domain}>\n\n"
-    rfc822msg << str
-
-    ### send email
-    Net::SMTP.start(*@params) {|smtp| smtp.sendmail(rfc822msg, @from, @to)}
-    self
-  rescue StandardError, TimeoutError => err
-    self.level = :off
-    ::Logging.log_internal {'e-mail notifications have been disabled'}
-    ::Logging.log_internal(-2) {err}
+  def self.email( *args )
+    return ::Logging::Appenders::Email if args.empty?
+    ::Logging::Appenders::Email.new(*args)
   end
 
-end   # class Email
-end   # module Logging::Appenders
+  # Provides an appender that can send log messages via email to a list of
+  # recipients.
+  #
+  class Email < ::Logging::Appender
+    include Buffering
+
+    attr_reader :authentication, :to, :port
+    attr_accessor :address, :domain, :from, :subject
+    attr_accessor :user_name, :password, :enable_starttls_auto
+
+    # call-seq:
+    #    Email.new( name, :from => 'me@example.com', :to => 'you@example.com', :subject => 'Whoops!' )
+    #
+    # Create a new email appender that will buffer messages and then send them
+    # out in batches to the listed recipients. See the options below to
+    # configure how emails are sent through you mail server of choice. All the
+    # buffering options apply to the email appender.
+    #
+    # The following options are required:
+    #
+    #  :from - The base filename to use when constructing new log
+    #          filenames.
+    #  :to   - The list of email recipients either as an Array or a comma
+    #          separated list.
+    #
+    # The following options are optional:
+    #
+    #  :subject   - The subject line for the email.
+    #  :address   - Allows you to use a remote mail server. Just change it
+    #               from its default "localhost" setting.
+    #  :port      - On the off chance that your mail server doesn't run on
+    #               port 25, you can change it.
+    #  :domain    - If you need to specify a HELO domain, you can do it here.
+    #  :user_name - If your mail server requires authentication, set the user
+    #               name in this setting.
+    #  :password  - If your mail server requires authentication, set the
+    #               password in this setting.
+    #  :authentication - If your mail server requires authentication, you need
+    #                    to specify the authentication type here. This is a
+    #                    symbol and one of :plain (will send the password in
+    #                    the clear), :login (will send password Base64
+    #                    encoded) or :cram_md5 (combines a Challenge/Response
+    #                    mechanism to exchange information and a cryptographic
+    #                    Message Digest 5 algorithm to hash important
+    #                    information)
+    #  :enable_starttls_auto - When set to true, detects if STARTTLS is
+    #                          enabled in your SMTP server and starts to use it.
+    #
+    # Example:
+    #
+    # Setup an email appender that will buffer messages for up to 1 minute,
+    # and only send messages for ERROR and FATAL messages. This example uses
+    # Google's SMTP server with authentication to send out messages.
+    #
+    #   Logger.appenders.email( 'email',
+    #       :from       => "server@example.com",
+    #       :to         => "developers@example.com",
+    #       :subject    => "Application Error [#{%x(uname -n).strip}]",
+    #
+    #       :address    => "smtp.google.com",
+    #       :port       => 443,
+    #       :domain     => "google.com",
+    #       :user_name  => "example",
+    #       :password   => "12345",
+    #       :authentication => :plain,
+    #       :enable_starttls_auto => true,
+    #
+    #       :auto_flushing => 200,     # send an email after 200 messages have been buffered
+    #       :flush_period  => 60,      # send an email after one minute
+    #       :level         => :error   # only process log events that are "error" or "fatal"
+    #   )
+    #
+    def initialize( name, opts = {} )
+      opts[:header] = false
+      super(name, opts)
+
+      af = opts.getopt(:buffsize) ||
+           opts.getopt(:buffer_size) ||
+           100
+      configure_buffering({:auto_flushing => af}.merge(opts))
+
+      # get the SMTP parameters
+      self.from = opts.getopt :from
+      raise ArgumentError, 'Must specify from address' if @from.nil?
+
+      self.to = opts.getopt :to
+      raise ArgumentError, 'Must specify recipients' if @to.empty?
+
+      self.subject   = opts.getopt :subject, "Message from #{$0}"
+      self.address   = opts.getopt(:server) || opts.getopt(:address) || 'localhost'
+      self.port      = opts.getopt(:port, 25)
+      self.domain    = opts.getopt(:domain, ENV['HOSTNAME']) || 'localhost.localdomain'
+      self.user_name = opts.getopt(:acct) || opts.getopt(:user_name)
+      self.password  = opts.getopt(:passwd) || opts.getopt(:password)
+      self.enable_starttls_auto = opts.getopt(:enable_starttls_auto, false)
+      self.authentication = opts.getopt(:authtype) || opts.getopt(:authentication) || :plain
+    end
+
+    # Close the email appender. If the layout contains a foot, it will not be
+    # sent as an email.
+    #
+    def close( *args )
+      super(false)
+    end
+
+    # If your mail server requires authentication, you need to specify the
+    # authentication type here. This is a symbol and one of :plain (will send
+    # the password in the clear), :login (will send password Base64 encoded)
+    # or :cram_md5 (combines a Challenge/Response mechanism to exchange
+    # information and a cryptographic Message Digest 5 algorithm to hash
+    # important information)
+    #
+    def authentication=( val )
+      @authentication = val.to_s.to_sym
+    end
+
+    # On the off chance that your mail server doesn't run on port 25, you can
+    # change it.
+    #
+    def port=( val )
+      @port = Integer(val)
+    end
+
+    # The list of email recipients. This can either be an Array of recipients
+    # or a comma separated list. A single recipient is also valid.
+    #
+    #   email.to = ['mike@example.com', 'tony@example.com']
+    #   email.to = 'alicia@example.com'
+    #   email.to = 'bob@example.com, andy@example.com, john@example.com'
+    #
+    def to=( val )
+      @to = val.respond_to?(:split) ?  val.split(',') : Array(val)
+    end
+
+
+  private
+
+    # This method is called by the buffering code when messages need to be
+    # sent out as an email.
+    #
+    def canonical_write( str )
+      ### build a mail header for RFC 822
+      rfc822msg =  "From: #{@from}\n"
+      rfc822msg << "To: #{@to.join(",")}\n"
+      rfc822msg << "Subject: #{@subject}\n"
+      rfc822msg << "Date: #{Time.new.rfc822}\n"
+      rfc822msg << "Message-Id: <#{"%.8f" % Time.now.to_f}@#{@domain}>\n\n"
+      rfc822msg << str
+
+      ### send email
+      smtp = Net::SMTP.new(@address, @port)
+      smtp.enable_starttls_auto if @enable_starttls_auto and smtp.respond_to? :enable_starttls_auto
+      smtp.start(@domain, @user_name, @password, @authentication) { |s| s.sendmail(rfc822msg, @from, @to) }
+      self
+    rescue StandardError, TimeoutError => err
+      self.level = :off
+      ::Logging.log_internal {'e-mail notifications have been disabled'}
+      ::Logging.log_internal(-2) {err}
+    end
+
+  end   # Email
+end   # Logging::Appenders