logging 2.2.2 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: bb433e2db44c13bc4956095561ad2ad34cd4fabf
-  data.tar.gz: 6d6a401267834a2b1dad3c5992bb4c4c28ea05a0
+SHA256:
+  metadata.gz: f7bb89dcc5956ebabbf591d8f8d348e0e3cfdc7cb5fa356e9995168278b45a95
+  data.tar.gz: be4ad44cf88417be5abe80fbaf0b1d28a2f4899df2c00d1d4818af78cc440443
 SHA512:
-  metadata.gz: 44ad1070f56d8618f9e6c118876364f70442723424d055716928e422a6699a40e744c68a86619227ed8fd5eea26e6c1fd6850f50877c74769a5160d6133b5140
-  data.tar.gz: bf24fb750a15937f18d75b2acc738e323a8ea718661bb9877ea64b0d23eea12def864c3175e71cd1f9b7ccff69c44d661455ff3526e5c192cc0f67c026a77a7f
+  metadata.gz: b61a6a3bcda67484ec4334a89adfd6149d2aa91be51ba0ca476514c7c4532d0b4040cc202ce58d30e9d93ba5821e6eedbde77d8bdeaac7a82224731796d79eda
+  data.tar.gz: 55c888af479f8c01eb89f96eda24b2cc9cd92f52cc0b1f21d5fde7fcb7e91e573b6007998c67b00781cf8c5ea3eadcb9462b9df2da26dbcfe0464deb13340d18

data/.gitignore

@@ -12,3 +12,4 @@ tmp/
 vendor/
 .rbx
 .rvmrc
+.tool-versions

data/.travis.yml

@@ -9,6 +9,8 @@ rvm:
   - 2.0.0-p648
   - 2.1.10
   - 2.2.7
-  - 2.3.4
-  - 2.4.1
-  - jruby-9.1.8.0
+  - 2.3.8
+  - 2.4.9
+  - 2.5.7
+  - 2.6.5
+  - jruby-9.2.9.0

data/History.txt

@@ -1,3 +1,24 @@
+== 2.3.1 / 2022-05-24
+
+Bug Fixes
+- logging hangs on JRuby when the stdout appender is closed [PR #237]
+- initialize the Logging framework when a Filter is created [PR #238]
+
+== 2.3.0 / 2020-07-04
+
+Enhancements
+- all appender output is now synchronized [PR #219]
+- renamed the `LogEvent#method` to no longer conflict with `Kernel#method` [PR #218]
+- @bhuga (not the Fortnite star) added a `raise_errors` method for debugging [PR #203]
+- thanks to @olleolleolle for keeping on top of Travis and Ruby versions
+
+Bug Fixes
+- conosle appenders can be reopened [PR #220]
+- fixed a race condition in the rolling file appender [PR #216]
+- fixed a race condition when opening log file destinations [PR #208 #217]
+- @MikaelSmith fixed a race condition in Logger creation [PR #201]
+- documentation bug fixes [PR #184 #185 #188 #194 #209]
+
 == 2.2.2 / 2017-04-11
 
 Enhancements

data/Rakefile

@@ -26,9 +26,9 @@ Bones {
   use_gmail
 
   depend_on 'little-plugger', '~> 1.1'
-  depend_on 'multi_json',     '~> 1.10'
+  depend_on 'multi_json',     '~> 1.14'
 
-  depend_on 'test-unit', '~> 3.1', :development => true
+  depend_on 'test-unit', '~> 3.3', :development => true
   depend_on 'bones-git', '~> 1.3', :development => true
   #depend_on 'bones-rcov',   :development => true
 }

data/examples/appenders.rb

@@ -1,7 +1,7 @@
 # :stopdoc:
 #
 # Appenders are used to output log events to some logging destination. The
-# same log event can be sent to multiple desitnations by associating
+# same log event can be sent to multiple destinations by associating
 # multiple appenders with the logger.
 #
 # The following is a list of all the available appenders and a brief

data/examples/mdc.rb

@@ -29,9 +29,9 @@
   Logging.mdc['first'] = 'John'
   Logging.mdc['last']  = 'Doe'
 
-  # in this first thread we will log some quotes by Allan Rickman
+  # in this first thread we will log some quotes by Alan Rickman
   t1 = Thread.new {
-    Logging.mdc['first'] = 'Allan'
+    Logging.mdc['first'] = 'Alan'
     Logging.mdc['last']  = 'Rickman'
 
     [ %q{I've never been able to plan my life. I just lurch from indecision to indecision.},

data/lib/logging/appender.rb

@@ -9,11 +9,6 @@ module Logging
 # Each subclass should provide a +write+ method that will write log
 # messages to the logging destination.
 #
-# A private +sync+ method is provided for use by subclasses. It is used to
-# synchronize writes to the logging destination, and can be used by
-# subclasses to synchronize the closing or flushing of the logging
-# destination.
-#
 class Appender
 
   attr_reader :name, :layout, :level, :filters
@@ -263,13 +258,9 @@ class Appender
     "<%s name=\"%s\">" % [self.class.name.sub(%r/^Logging::/, ''), self.name]
   end
 
-  # Returns the current Encoding for the appender or nil if an encoding has
-  # not been set.
-  #
-  def encoding
-    return @encoding if defined? @encoding
-    @encoding = Object.const_defined?(:Encoding) ? Encoding.default_external : nil
-  end
+  # Returns the current Encoding for the appender. The default external econding
+  # will be used if none is explicitly set.
+  attr_reader :encoding
 
   # Set the appender encoding to the given value. The value can either be an
   # Encoding instance or a String or Symbol referring to a valid encoding.
@@ -282,9 +273,9 @@ class Appender
   # Raises ArgumentError if the value is not a valid encoding.
   def encoding=( value )
     if value.nil?
-      @encoding = nil
+      @encoding = Encoding.default_external
     else
-      @encoding = Object.const_defined?(:Encoding) ? Encoding.find(value.to_s) : nil
+      @encoding = Encoding.find(value.to_s)
     end
   end
 
@@ -328,17 +319,6 @@ private
     nil
   end
 
-  # call-seq:
-  #    sync { block }
-  #
-  # Obtains an exclusive lock, runs the block, and releases the lock when
-  # the block completes. This method is re-entrant so that a single thread
-  # can call +sync+ multiple times without hanging the thread.
-  #
-  def sync( &block )
-    @mutex.synchronize(&block)
-  end
-
 end  # class Appender
 end  # module Logging
 

data/lib/logging/appenders/buffering.rb

@@ -79,7 +79,7 @@ module Logging::Appenders
       return self if @buffer.empty?
 
       ary = nil
-      sync {
+      @mutex.synchronize {
         ary = @buffer.dup
         @buffer.clear
       }
@@ -100,7 +100,7 @@ module Logging::Appenders
     # Clear the underlying buffer of all log events. These events will not be
     # appended to the logging destination; they will be lost.
     def clear!
-      sync { @buffer.clear }
+      @mutex.synchronize { @buffer.clear }
     end
 
     # Configure the levels that will trigger an immediate flush of the
@@ -285,7 +285,7 @@ module Logging::Appenders
         canonical_write(str)
       else
         str = str.force_encoding(encoding) if encoding && str.encoding != encoding
-        sync {
+        @mutex.synchronize {
           @buffer << str
         }
         flush_now = @buffer.length >= @auto_flushing || immediate?(event)

data/lib/logging/appenders/console.rb

@@ -22,17 +22,39 @@ module Logging::Appenders
     #
     def initialize( *args )
       name = self.class.name.split("::").last.downcase
-      io   = Object.const_get(name.upcase)
 
       opts = args.last.is_a?(Hash) ? args.pop : {}
       name = args.shift unless args.empty?
 
-      opts[:encoding] = io.external_encoding if io.respond_to? :external_encoding
+      io = open_fd
+      opts[:encoding] = io.external_encoding
 
       super(name, io, opts)
-    rescue NameError
-      raise RuntimeError, "Please do not use the `Logging::Appenders::Console` class directly - " +
-                          "use `Logging::Appenders::Stdout` and `Logging::Appenders::Stderr` instead"
+    end
+
+    # Reopen the connection to the underlying logging destination. If the
+    # connection is currently closed then it will be opened. If the connection
+    # is currently open then it will be closed and immediately reopened.
+    def reopen
+      @mutex.synchronize {
+        flush if defined? @io && @io
+        @io = open_fd
+      }
+      super
+      self
+    end
+
+  private
+
+    def open_fd
+      case self.class.name
+      when "Logging::Appenders::Stdout"; STDOUT
+      when "Logging::Appenders::Stderr"; STDERR
+      else
+        raise RuntimeError, "Please do not use the `Logging::Appenders::Console` class directly - " +
+                            "use `Logging::Appenders::Stdout` and `Logging::Appenders::Stderr` instead" +
+                            " [class #{self.class.name}]"
+      end
     end
   end
 
@@ -43,7 +65,6 @@ module Logging::Appenders
   Stderr = Class.new(Console)
 
   # Accessor / Factory for the Stdout appender.
-  #
   def self.stdout( *args )
     if args.empty?
       return self['stdout'] || ::Logging::Appenders::Stdout.new
@@ -52,7 +73,6 @@ module Logging::Appenders
   end
 
   # Accessor / Factory for the Stderr appender.
-  #
   def self.stderr( *args )
     if args.empty?
       return self['stderr'] || ::Logging::Appenders::Stderr.new

data/lib/logging/appenders/file.rb

@@ -2,14 +2,12 @@
 module Logging::Appenders
 
   # Accessor / Factory for the File appender.
-  #
   def self.file( *args )
     fail ArgumentError, '::Logging::Appenders::File needs a name as first argument.' if args.empty?
     ::Logging::Appenders::File.new(*args)
   end
 
   # This class provides an Appender that can write to a File.
-  #
   class File < ::Logging::Appenders::IO
 
     # call-seq:
@@ -21,15 +19,14 @@ module Logging::Appenders
     # writable.
     #
     # An +ArgumentError+ is raised if any of these assertions fail.
-    #
     def self.assert_valid_logfile( fn )
       if ::File.exist?(fn)
-        if not ::File.file?(fn)
+        if !::File.file?(fn)
           raise ArgumentError, "#{fn} is not a regular file"
-        elsif not ::File.writable?(fn)
+        elsif !::File.writable?(fn)
           raise ArgumentError, "#{fn} is not writeable"
         end
-      elsif not ::File.writable?(::File.dirname(fn))
+      elsif !::File.writable?(::File.dirname(fn))
         raise ArgumentError, "#{::File.dirname(fn)} is not writable"
       end
       true
@@ -45,41 +42,65 @@ module Logging::Appenders
     # created. If the :truncate option is set to +true+ then the file will
     # be truncated before writing begins; otherwise, log messages will be
     # appended to the file.
-    #
     def initialize( name, opts = {} )
-      @fn = opts.fetch(:filename, name)
-      raise ArgumentError, 'no filename was given' if @fn.nil?
+      @filename = opts.fetch(:filename, name)
+      raise ArgumentError, 'no filename was given' if @filename.nil?
 
-      @fn = ::File.expand_path(@fn)
-      self.class.assert_valid_logfile(@fn)
-      @mode = opts.fetch(:truncate, false) ? 'w' : 'a'
+      @filename = ::File.expand_path(@filename).freeze
+      self.class.assert_valid_logfile(@filename)
 
       self.encoding = opts.fetch(:encoding, self.encoding)
-      @mode = "#{@mode}:#{self.encoding}" if self.encoding
 
-      super(name, ::File.new(@fn, @mode), opts)
+      io = open_file
+      super(name, io, opts)
+
+      truncate if opts.fetch(:truncate, false)
     end
 
     # Returns the path to the logfile.
-    #
-    def filename() @fn.dup end
+    attr_reader :filename
 
     # Reopen the connection to the underlying logging destination. If the
     # connection is currently closed then it will be opened. If the connection
     # is currently open then it will be closed and immediately opened.
-    #
     def reopen
       @mutex.synchronize {
-        if defined? @io and @io
+        if defined? @io && @io
           flush
           @io.close rescue nil
         end
-        @io = ::File.new(@fn, @mode)
+        @io = open_file
       }
       super
       self
     end
 
-  end  # FileAppender
-end  # Logging::Appenders
 
+  protected
+
+    def truncate
+      @mutex.synchronize {
+        begin
+          @io.flock(::File::LOCK_EX)
+          @io.truncate(0)
+        ensure
+          @io.flock(::File::LOCK_UN)
+        end
+      }
+    end
+
+    def open_file
+      mode = ::File::WRONLY | ::File::APPEND
+      ::File.open(filename, mode: mode, external_encoding: encoding)
+    rescue Errno::ENOENT
+      create_file
+    end
+
+    def create_file
+      mode = ::File::WRONLY | ::File::APPEND | ::File::CREAT | ::File::EXCL
+      ::File.open(filename, mode: mode, external_encoding: encoding)
+    rescue Errno::EEXIST
+      open_file
+    end
+  end
+end

data/lib/logging/appenders/io.rb

@@ -2,7 +2,6 @@
 module Logging::Appenders
 
   # Accessor / Factory for the IO appender.
-  #
   def self.io( *args )
     return ::Logging::Appenders::IO if args.empty?
     ::Logging::Appenders::IO.new(*args)
@@ -10,14 +9,12 @@ module Logging::Appenders
 
   # This class provides an Appender that can write to any IO stream
   # configured for writing.
-  #
   class IO < ::Logging::Appender
     include Buffering
 
     # The method that will be used to close the IO stream. Defaults to :close
     # but can be :close_read, :close_write or nil. When nil, the IO stream
     # will not be closed when the appender's close method is called.
-    #
     attr_accessor :close_method
 
     # call-seq:
@@ -26,7 +23,6 @@ module Logging::Appenders
     #
     # Creates a new IO Appender using the given name that will use the _io_
     # stream as the logging destination.
-    #
     def initialize( name, io, opts = {} )
       unless io.respond_to? :write
         raise TypeError, "expecting an IO object but got '#{io.class.name}'"
@@ -47,13 +43,12 @@ module Logging::Appenders
     # destination if the _footer_ flag is set to +true+. Log events will
     # no longer be written to the logging destination after the appender
     # is closed.
-    #
     def close( *args )
       return self if @io.nil?
       super
 
       io, @io = @io, nil
-      unless [STDIN, STDERR, STDOUT].include?(io)
+      if ![STDIN, STDERR, STDOUT].include?(io)
         io.send(@close_method) if @close_method && io.respond_to?(@close_method)
       end
     rescue IOError
@@ -61,16 +56,25 @@ module Logging::Appenders
       return self
     end
 
+    # Reopen the connection to the underlying logging destination. If the
+    # connection is currently closed then it will be opened. If the connection
+    # is currently open then it will be closed and immediately opened. If
+    # supported, the IO will have its sync mode set to `true` so that all writes
+    # are immediately flushed to the underlying operating system.
+    def reopen
+      super
+      @io.sync = true if @io.respond_to? :sync=
+      self
+    end
 
   private
 
     # This method is called by the buffering code when messages need to be
     # written to the logging destination.
-    #
     def canonical_write( str )
       return self if @io.nil?
       str = str.force_encoding(encoding) if encoding && str.encoding != encoding
-      @io.write str
+      @mutex.synchronize { @io.write str }
       self
     rescue StandardError => err
       handle_internal_error(err)
@@ -82,6 +86,5 @@ module Logging::Appenders
       ::Logging.log_internal {"appender #{name.inspect} has been disabled"}
       ::Logging.log_internal_error(err)
     end
-
-  end  # IO
-end  # Logging::Appenders
+  end
+end

data/lib/logging/appenders/rolling_file.rb

@@ -84,24 +84,32 @@ module Logging::Appenders
     #               'date'.
     #
     def initialize( name, opts = {} )
-      @roller = Roller.new name, opts
+      @roller = Roller.new(
+        opts.fetch(:filename, name),
+        age:     opts.fetch(:age, nil),
+        size:    opts.fetch(:size, nil),
+        roll_by: opts.fetch(:roll_by, nil),
+        keep:    opts.fetch(:keep, nil)
+      )
 
       # grab our options
       @size = opts.fetch(:size, nil)
       @size = Integer(@size) unless @size.nil?
 
-      @age_fn = filename + '.age'
+      @age_fn = self.filename + '.age'
       @age_fn_mtime = nil
       @age = opts.fetch(:age, nil)
 
       # create our `sufficiently_aged?` method
       build_singleton_methods
-      FileUtils.touch(@age_fn) if @age && !test(?f, @age_fn)
+      FileUtils.touch(@age_fn) if @age && !::File.file?(@age_fn)
 
       # we are opening the file in read/write mode so that a shared lock can
       # be used on the file descriptor => http://pubs.opengroup.org/onlinepubs/009695399/functions/fcntl.html
-      @mode = encoding ? "a+:#{encoding}" : 'a+'
-      super(name, ::File.new(filename, @mode), opts)
+      self.encoding = opts.fetch(:encoding, self.encoding)
+
+      io = open_file
+      super(name, io, opts)
 
       # if the truncate flag was set to true, then roll
       roll_now = opts.fetch(:truncate, false)
@@ -121,11 +129,11 @@ module Logging::Appenders
     # is currently open then it will be closed and immediately opened.
     def reopen
       @mutex.synchronize {
-        if defined?(@io) && @io
+        if defined? @io && @io
           flush
           @io.close rescue nil
         end
-        @io = ::File.new(filename, @mode)
+        @io = open_file
       }
       super
       self
@@ -134,6 +142,20 @@ module Logging::Appenders
 
   private
 
+    def open_file
+      mode = ::File::RDWR | ::File::APPEND
+      ::File.open(filename, mode: mode, external_encoding: encoding)
+    rescue Errno::ENOENT
+      create_file
+    end
+
+    def create_file
+      mode = ::File::RDWR | ::File::APPEND | ::File::CREAT | ::File::EXCL
+      ::File.open(filename, mode: mode, external_encoding: encoding)
+    rescue Errno::EEXIST
+      open_file
+    end
+
     # Returns the file name to use as the temporary copy location. We are
     # using copy-and-truncate semantics for rolling files so that the IO
     # file descriptor remains valid during rolling.
@@ -157,14 +179,18 @@ module Logging::Appenders
       return self if @io.nil?
 
       str = str.force_encoding(encoding) if encoding && str.encoding != encoding
-      @io.flock_sh { @io.write str }
+      @mutex.synchronize {
+        @io.flock_sh { @io.write str }
+      }
 
       if roll_required?
-        @io.flock? {
-          @age_fn_mtime = nil
-          copy_truncate if roll_required?
+        @mutex.synchronize {
+          @io.flock? {
+            @age_fn_mtime = nil
+            copy_truncate if roll_required?
+          }
+          @roller.roll_files
         }
-        @roller.roll_files
       end
       self
     rescue StandardError => err
@@ -193,7 +219,7 @@ module Logging::Appenders
     def copy_truncate
       return unless ::File.exist?(filename)
       FileUtils.concat filename, copy_file
-      @io.truncate 0
+      @io.truncate(0)
 
       # touch the age file if needed
       if @age
@@ -255,22 +281,22 @@ module Logging::Appenders
       # Create a new roller. See the RollingFile#initialize documentation for
       # the list of options.
       #
-      # name - The appender name as a String
-      # opts - The options Hash
+      # filename - the name of the file to roll
+      # age      - the age of the file at which it should be rolled
+      # size     - the size of the file in bytes at which it should be rolled
+      # roll_by  - roll either by 'number' or 'date'
+      # keep     - the number of log files to keep when rolling
       #
-      def initialize( name, opts )
+      def initialize( filename, age: nil, size: nil, roll_by: nil, keep: nil )
         # raise an error if a filename was not given
-        @fn = opts.fetch(:filename, name)
+        @fn = filename
         raise ArgumentError, 'no filename was given' if @fn.nil?
 
         if (m = RGXP.match @fn)
           @roll_by = ("#{m[2]}%d" == m[1]) ? :number : :date
         else
-          age = opts.fetch(:age, nil)
-          size = opts.fetch(:size, nil)
-
           @roll_by =
-              case opts.fetch(:roll_by, nil)
+              case roll_by
               when 'number'; :number
               when 'date'; :date
               else
@@ -293,8 +319,7 @@ module Logging::Appenders
         ::Logging::Appenders::File.assert_valid_logfile(filename)
 
         @roll = false
-        @keep = opts.fetch(:keep, nil)
-        @keep = Integer(keep) unless keep.nil?
+        @keep = keep.nil? ? nil : Integer(keep)
       end
 
       attr_reader :keep, :roll_by
@@ -347,7 +372,6 @@ module Logging::Appenders
         files.delete copy_file
 
         self.send "roll_by_#{roll_by}", files
-
         nil
       ensure
         self.roll = false

data/lib/logging/appenders/string_io.rb

@@ -62,7 +62,7 @@ module Logging::Appenders
     %w[read readline readlines].each do|m|
       class_eval <<-CODE, __FILE__, __LINE__+1
         def #{m}( *args )
-          sync {
+          @mutex.synchronize {
             begin
               @sio.seek @pos
               rv = @sio.#{m}(*args)

data/lib/logging/appenders/syslog.rb

@@ -188,7 +188,7 @@ module Logging::Appenders
         end
       return if message.empty?
 
-      @syslog.log(pri, '%s', message)
+      @mutex.synchronize { @syslog.log(pri, '%s', message) }
       self
     end
 
@@ -205,11 +205,10 @@ module Logging::Appenders
         level = level.to_s.upcase
         self.class.const_get level
       else
-        raise ArgumentError, "unkonwn level '#{level}'"
+        raise ArgumentError, "unknown level '#{level}'"
       end
     end
 
   end  # Syslog
 end  # Logging::Appenders
 end  # HAVE_SYSLOG
-

data/lib/logging/filter.rb

@@ -8,10 +8,17 @@ module Logging
   # Otherwise the `allow` method should return `nil`.
   class Filter
 
-    # Returns the event if it should be allowed into the log. Returns `nil` if
-    # the event should _not_ be allowed into the log. Subclasses should override
-    # this method and provide their own filtering semantics.
-    def allow( event )
+    # Creates a new level filter that will pass all log events. Create a
+    # subclass and override the `allow` method to filter log events.
+    def initialize
+      ::Logging.init unless ::Logging.initialized?
+    end
+
+    # Returns the event if it should be forwarded to the logging appender.
+    # Returns `nil` if the event should _not_ be forwarded to the logging
+    # appender. Subclasses should override this method and provide their own
+    # filtering semantics.
+    def allow(event)
       event
     end
   end

data/lib/logging/filters/level.rb

@@ -4,8 +4,7 @@ module Logging
   module Filters
 
     # The `Level` filter class provides a simple level-based filtering mechanism
-    # that filters messages to only include those from an enumerated list of
-    # levels to log.
+    # that allows events whose log level matches a preconfigured list of values.
     class Level < ::Logging::Filter
 
       # Creates a new level filter that will only allow the given _levels_ to
@@ -15,15 +14,19 @@ module Logging
       # Examples
       #     Logging::Filters::Level.new(:debug, :info)
       #
-      def initialize( *levels )
-        levels  = levels.map { |level| ::Logging::level_num(level) }
-        @levels = Set.new levels
+      def initialize(*levels)
+        super()
+        levels  = levels.flatten.map {|level| ::Logging::level_num(level)}
+        @levels = Set.new(levels)
       end
 
-      def allow( event )
+      # Returns the event if it should be forwarded to the logging appender.
+      # Otherwise, `nil` is returned. The log event is allowed if the
+      # `event.level` matches one of the levels provided to the filter when it
+      # was constructred.
+      def allow(event)
         @levels.include?(event.level) ? event : nil
       end
-
     end
   end
 end