logsly 1.2.0 → 1.3.0

data/lib/logsly/logging182/appenders/buffering.rb

@@ -0,0 +1,398 @@
+
+module Logsly::Logging182::Appenders
+
+  # The Buffering module is used to implement buffering of the log messages
+  # in a given appender. The size of the buffer can be specified, and the
+  # buffer can be configured to auto-flush at a given threshold. The
+  # threshold can be a single message or a very large number of messages.
+  #
+  # Log messages of a certain level can cause the buffer to be flushed
+  # immediately. If an error occurs, all previous messages and the error
+  # message will be written immediately to the logging destination if the
+  # buffer is configured to do so.
+  #
+  module Buffering
+
+    # Default buffer size
+    #
+    DEFAULT_BUFFER_SIZE = 500;
+
+    # The buffer holding the log messages
+    #
+    attr_reader :buffer
+
+    # The auto-flushing setting. When the buffer reaches this size, all
+    # messages will be be flushed automatically.
+    #
+    attr_reader :auto_flushing
+
+    # When set, the buffer will be flushed at regular intervals defined by the
+    # flush_period.
+    #
+    attr_reader :flush_period
+
+    # Setup the message buffer and other variables for automatically and
+    # periodically flushing the buffer.
+    #
+    def initialize( *args, &block )
+      @buffer = []
+      @immediate = []
+      @auto_flushing = 1
+      @flush_period = @periodic_flusher = nil
+
+      super(*args, &block)
+    end
+
+    # Close the message buffer by flushing all log events to the appender. If a
+    # periodic flusher thread is running, shut it down and allow it to exit.
+    #
+    def close( *args )
+      flush
+
+      if @periodic_flusher
+        @periodic_flusher.stop
+        @periodic_flusher = nil
+        Thread.pass
+      end
+
+      super(*args)
+    end
+
+    # Reopen the connection to the underlying logging destination. In addition
+    # if the appender is configured for periodic flushing, then the flushing
+    # thread will be stopped and restarted.
+    #
+    def reopen
+      _setup_periodic_flusher
+      super
+    end
+
+    # Call +flush+ to force an appender to write out any buffered log events.
+    # Similar to IO#flush, so use in a similar fashion.
+    #
+    def flush
+      return self if @buffer.empty?
+
+      str = nil
+      sync {
+        str = @buffer.join
+        @buffer.clear
+      }
+
+      canonical_write str unless str.empty?
+      self
+    end
+
+    # Configure the levels that will trigger an immediate flush of the
+    # logging buffer. When a log event of the given level is seen, the
+    # buffer will be flushed immediately. Only the levels explicitly given
+    # in this assignment will flush the buffer; if an "error" message is
+    # configured to immediately flush the buffer, a "fatal" message will not
+    # even though it is a higher level. Both must be explicitly passed to
+    # this assignment.
+    #
+    # You can pass in a single level name or number, an array of level
+    # names or numbers, or a string containing a comma separated list of level
+    # names or numbers.
+    #
+    #   immediate_at = :error
+    #   immediate_at = [:error, :fatal]
+    #   immediate_at = "warn, error"
+    #
+    def immediate_at=( level )
+      @immediate.clear
+
+      # get the immediate levels -- no buffering occurs at these levels, and
+      # a log message is written to the logging destination immediately
+      immediate_at =
+        case level
+        when String; level.split(',').map {|x| x.strip}
+        when Array; level
+        else Array(level) end
+
+      immediate_at.each do |lvl|
+        num = ::Logsly::Logging182.level_num(lvl)
+        next if num.nil?
+        @immediate[num] = true
+      end
+    end
+
+    # Configure the auto-flushing threshold. Auto-flushing is used to flush
+    # the contents of the logging buffer to the logging destination
+    # automatically when the buffer reaches a certain threshold.
+    #
+    # By default, the auto-flushing will be configured to flush after each
+    # log message.
+    #
+    # The allowed settings are as follows:
+    #
+    #   N      : flush after every N messages (N is an integer)
+    #   true   : flush after each log message
+    #   false  OR
+    #   nil    OR
+    #   0      : only flush when the buffer is full (500 messages)
+    #
+    # If the default buffer size of 500 is too small, then you can manually
+    # configure it to be as large as you want. This will consume more memory.
+    #
+    #   auto_flushing = 42_000
+    #
+    def auto_flushing=( period )
+      @auto_flushing =
+        case period
+        when true;             1
+        when false, nil, 0;    DEFAULT_BUFFER_SIZE
+        when Integer;          period
+        when String;           Integer(period)
+        else
+          raise ArgumentError,
+                "unrecognized auto_flushing period: #{period.inspect}"
+        end
+
+      if @auto_flushing <= 0
+        raise ArgumentError,
+          "auto_flushing period must be greater than zero: #{period.inspect}"
+      end
+
+      @auto_flushing = DEFAULT_BUFFER_SIZE if @flush_period and @auto_flushing <= 1
+    end
+
+    # Configure periodic flushing of the message buffer. Periodic flushing is
+    # used to flush the contents of the logging buffer at some regular
+    # interval. Periodic flushing is disabled by default.
+    #
+    # When enabling periodic flushing the flush period should be set using one
+    # of the following formats: "HH:MM:SS" or seconds as an numeric or string.
+    #
+    #   "01:00:00"  : every hour
+    #   "00:05:00"  : every 5 minutes
+    #   "00:00:30"  : every 30 seconds
+    #   60          : every 60 seconds (1 minute)
+    #   "120"       : every 120 seconds (2 minutes)
+    #
+    # For the periodic flusher to work properly, the auto-flushing threshold
+    # will be set to the default value of 500. The auto-flushing threshold can
+    # be changed, but it must be greater than 1.
+    #
+    # To disable the periodic flusher simply set the flush period to +nil+.
+    # The auto-flushing threshold will not be changed; it must be disabled
+    # manually if so desired.
+    #
+    def flush_period=( period )
+      period =
+        case period
+        when Integer, Float, nil; period
+        when String;
+          num = _parse_hours_minutes_seconds(period) || _parse_numeric(period)
+          num = ArgumentError.new("unrecognized flush period: #{period.inspect}") if num.nil?
+          num
+        else ArgumentError.new("unrecognized flush period: #{period.inspect}") end
+
+      raise period if Exception === period
+      @flush_period = period
+
+      _setup_periodic_flusher
+    end
+
+  protected
+
+    # Configure the buffering using the arguments found in the give options
+    # hash. This method must be called in order to use the message buffer.
+    # The supported options are "immediate_at" and "auto_flushing". Please
+    # refer to the documentation for those methods to see the allowed
+    # options.
+    #
+    def configure_buffering( opts )
+      ::Logsly::Logging182.init unless ::Logsly::Logging182.initialized?
+
+      self.immediate_at = opts.getopt(:immediate_at, '')
+      self.auto_flushing = opts.getopt(:auto_flushing, true)
+      self.flush_period = opts.getopt(:flush_period, nil)
+    end
+
+    # Returns true if the _event_ level matches one of the configured
+    # immediate logging levels. Otherwise returns false.
+    #
+    def immediate?( event )
+      return false unless event.respond_to? :level
+      @immediate[event.level]
+    end
+
+
+  private
+
+    # call-seq:
+    #    write( event )
+    #
+    # Writes the given _event_ to the logging destination. The _event_ can
+    # be either a LogEvent or a String. If a LogEvent, then it will be
+    # formatted using the layout given to the appender when it was created.
+    #
+    # The _event_ will be formatted and then buffered until the
+    # "auto_flushing" level has been reached. At this time the canonical_write
+    # method will be used to log all events stored in the buffer.
+    #
+    def write( event )
+      str = event.instance_of?(::Logsly::Logging182::LogEvent) ?
+            layout.format(event) : event.to_s
+      return if str.empty?
+
+      if @auto_flushing == 1
+        canonical_write(str)
+      else
+        sync {
+          str = str.force_encoding(encoding) if encoding and str.encoding != encoding
+          @buffer << str
+        }
+        @periodic_flusher.signal if @periodic_flusher
+        flush if @buffer.length >= @auto_flushing || immediate?(event)
+      end
+
+      self
+    end
+
+    # Attempt to parse an hours/minutes/seconds value from the string and return
+    # an integer number of seconds.
+    #
+    #   _parse_hours_minutes_seconds("14:12:42")  #=> 51162
+    #   _parse_hours_minutes_seconds("foo")       #=> nil
+    #
+    def _parse_hours_minutes_seconds( str )
+      m = %r/^\s*(\d{2,}):(\d{2}):(\d{2}(?:\.\d+)?)\s*$/.match(str)
+      return if m.nil?
+
+      (3600 * m[1].to_i) + (60 * m[2].to_i) + (m[3].to_f)
+    end
+
+    # Convert the string into a numeric value. If the string does not
+    # represent a valid Integer or Float then +nil+ is returned.
+    #
+    #   _parse_numeric("10")   #=> 10
+    #   _parse_numeric("1.0")  #=> 1.0
+    #   _parse_numeric("foo")  #=> nil
+    #
+    def _parse_numeric( str )
+      Integer(str) rescue (Float(str) rescue nil)
+    end
+
+    # Using the flush_period, create a new PeriodicFlusher attached to this
+    # appender. If the flush_period is nil, then no action will be taken. If a
+    # PeriodicFlusher already exists, it will be stopped and a new one will be
+    # created.
+    #
+    def _setup_periodic_flusher
+      # stop and remove any existing periodic flusher instance
+      if @periodic_flusher
+        @periodic_flusher.stop
+        @periodic_flusher = nil
+        Thread.pass
+      end
+
+      # create a new periodic flusher if we have a valid flush period
+      if @flush_period
+        @auto_flushing = DEFAULT_BUFFER_SIZE unless @auto_flushing > 1
+        @periodic_flusher = PeriodicFlusher.new(self, @flush_period)
+        @periodic_flusher.start
+      end
+    end
+
+    # :stopdoc:
+
+    # The PeriodicFlusher contains an internal run loop that will periodically
+    # wake up and flush any log events contained in the message buffer of the
+    # owning appender instance. The PeriodicFlusher relies on a _signal_ from
+    # the appender in order to wakeup and perform the flush on the appender.
+    #
+    class PeriodicFlusher
+
+      # Create a new PeriodicFlusher instance that will call the +flush+
+      # method on the given _appender_. The +flush+ method will be called
+      # every _period_ seconds, but only when the message buffer is non-empty.
+      #
+      def initialize( appender, period )
+        @appender = appender
+        @period = period
+
+        @mutex = Mutex.new
+        @cv = ConditionVariable.new
+        @thread = nil
+        @waiting = nil
+        @signaled = false
+      end
+
+      # Start the periodic flusher's internal run loop.
+      #
+      def start
+        return if @thread
+
+        @thread = Thread.new { loop {
+          begin
+            break if Thread.current[:stop]
+            _wait_for_signal
+            sleep @period unless Thread.current[:stop]
+            @appender.flush
+          rescue => err
+            ::Logsly::Logging182.log_internal {"PeriodicFlusher for appender #{@appender.inspect} encountered an error"}
+            ::Logsly::Logging182.log_internal(-2) {err}
+          end
+        }; @thread = nil }
+
+        self
+      end
+
+      # Stop the periodic flusher's internal run loop.
+      #
+      def stop
+        return if @thread.nil?
+        @thread[:stop] = true
+        signal if waiting?
+        self
+      end
+
+      # Signal the periodic flusher. This will wake up the run loop if it is
+      # currently waiting for something to do. If the signal method is never
+      # called, the periodic flusher will never perform the flush action on
+      # the appender.
+      #
+      def signal
+        return if Thread.current == @thread   # don't signal ourselves
+        return if @signaled                   # don't need to signal again
+
+        @mutex.synchronize {
+          @signaled = true
+          @cv.signal
+        }
+        self
+      end
+
+      # Returns +true+ if the flusher is waiting for a signal. Returns +false+
+      # if the flusher is somewhere in the processing loop.
+      #
+      def waiting?
+        @waiting
+      end
+
+    private
+
+      def _wait_for_signal
+        @mutex.synchronize {
+          begin
+            # wait on the condition variable only if we have NOT been signaled
+            unless @signaled
+              @waiting = true
+              @cv.wait(@mutex)
+              @waiting = false
+            end
+          ensure
+            @signaled = false
+          end
+        }
+      ensure
+        @waiting = false
+      end
+    end  # class PeriodicFlusher
+    # :startdoc:
+
+  end  # Buffering
+end  # Logsly::Logging182::Appenders
+

data/lib/logsly/logging182/appenders/console.rb

@@ -0,0 +1,81 @@
+
+module Logsly::Logging182::Appenders
+
+  # Accessor / Factory for the Stdout appender.
+  #
+  def self.stdout( *args )
+    if args.empty?
+      return self['stdout'] || ::Logsly::Logging182::Appenders::Stdout.new
+    end
+    ::Logsly::Logging182::Appenders::Stdout.new(*args)
+  end
+
+  # This class provides an Appender that can write to STDOUT.
+  #
+  class Stdout < ::Logsly::Logging182::Appenders::IO
+
+    # call-seq:
+    #    Stdout.new( name = 'stdout' )
+    #    Stdout.new( :layout => layout )
+    #    Stdout.new( name = 'stdout', :level => 'info' )
+    #
+    # Creates a new Stdout Appender. The name 'stdout' will be used unless
+    # another is given. Optionally, a layout can be given for the appender
+    # to use (otherwise a basic appender will be created) and a log level
+    # can be specified.
+    #
+    # Options:
+    #
+    #    :layout   => the layout to use when formatting log events
+    #    :level    => the level at which to log
+    #
+    def initialize( *args )
+      opts = Hash === args.last ? args.pop : {}
+      name = args.empty? ? 'stdout' : args.shift
+
+      opts[:encoding] = STDOUT.external_encoding if STDOUT.respond_to? :external_encoding
+
+      super(name, STDOUT, opts)
+    end
+  end  # Stdout
+
+
+  # Accessor / Factory for the Stderr appender.
+  #
+  def self.stderr( *args )
+    if args.empty?
+      return self['stderr'] || ::Logsly::Logging182::Appenders::Stderr.new
+    end
+    ::Logsly::Logging182::Appenders::Stderr.new(*args)
+  end
+
+  # This class provides an Appender that can write to STDERR.
+  #
+  class Stderr < ::Logsly::Logging182::Appenders::IO
+
+    # call-seq:
+    #    Stderr.new( name = 'stderr' )
+    #    Stderr.new( :layout => layout )
+    #    Stderr.new( name = 'stderr', :level => 'warn' )
+    #
+    # Creates a new Stderr Appender. The name 'stderr' will be used unless
+    # another is given. Optionally, a layout can be given for the appender
+    # to use (otherwise a basic appender will be created) and a log level
+    # can be specified.
+    #
+    # Options:
+    #
+    #    :layout   => the layout to use when formatting log events
+    #    :level    => the level at which to log
+    #
+    def initialize( *args )
+      opts = Hash === args.last ? args.pop : {}
+      name = args.empty? ? 'stderr' : args.shift
+
+      opts[:encoding] = STDERR.external_encoding if STDERR.respond_to? :external_encoding
+
+      super(name, STDERR, opts)
+    end
+  end  # Stderr
+end  # Logsly::Logging182::Appenders
+

data/lib/logsly/logging182/appenders/email.rb

@@ -0,0 +1,178 @@
+
+require 'net/smtp'
+require 'time' # get rfc822 time format
+
+module Logsly::Logging182::Appenders
+
+  # Accessor / Factory for the Email appender.
+  #
+  def self.email( *args )
+    return ::Logsly::Logging182::Appenders::Email if args.empty?
+    ::Logsly::Logging182::Appenders::Email.new(*args)
+  end
+
+  # Provides an appender that can send log messages via email to a list of
+  # recipients.
+  #
+  class Email < ::Logsly::Logging182::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 = rfc822msg.force_encoding(encoding) if encoding and rfc822msg.encoding != encoding
+      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
+      ::Logsly::Logging182.log_internal {'e-mail notifications have been disabled'}
+      ::Logsly::Logging182.log_internal(-2) {err}
+    end
+
+  end   # Email
+end   # Logsly::Logging182::Appenders
+