sgeorgi-logging 1.4.2

data/lib/logging/repository.rb

@@ -0,0 +1,232 @@
+
+require 'singleton'
+
+module Logging
+
+  # The Repository is a hash that stores references to all Loggers
+  # that have been created. It provides methods to determine parent/child
+  # relationships between Loggers and to retrieve Loggers from the hash.
+  #
+  class Repository
+    include Singleton
+
+    PATH_DELIMITER = '::'  # :nodoc:
+
+    # nodoc:
+    #
+    # This is a singleton class -- use the +instance+ method to obtain the
+    # +Repository+ instance.
+    #
+    def initialize
+      @masters = []
+      @h = {:root => ::Logging::RootLogger.new}
+
+      # configures the internal logger which is disabled by default
+      logger = ::Logging::Logger.allocate
+      logger._setup(
+          to_key(::Logging),
+          :parent   => @h[:root],
+          :additive => false,
+          :level    => ::Logging::LEVELS.length   # turns this logger off
+      )
+      @h[logger.name] = logger
+    end
+
+    # call-seq:
+    #    instance[name]
+    #
+    # Returns the +Logger+ named _name_.
+    #
+    # When _name_ is a +String+ or a +Symbol+ it will be used "as is" to
+    # retrieve the logger. When _name_ is a +Class+ the class name will be
+    # used to retrieve the logger. When _name_ is an object the name of the
+    # object's class will be used to retrieve the logger.
+    #
+    # Example:
+    #
+    #   repo = Repository.instance
+    #   obj = MyClass.new
+    #
+    #   log1 = repo[obj]
+    #   log2 = repo[MyClass]
+    #   log3 = repo['MyClass']
+    #
+    #   log1.object_id == log2.object_id         # => true
+    #   log2.object_id == log3.object_id         # => true
+    #
+    def []( key ) @h[to_key(key)] end
+
+    # call-seq:
+    #    instance[name] = logger
+    #
+    # Stores the _logger_ under the given _name_.
+    #
+    # When _name_ is a +String+ or a +Symbol+ it will be used "as is" to
+    # store the logger. When _name_ is a +Class+ the class name will be
+    # used to store the logger. When _name_ is an object the name of the
+    # object's class will be used to store the logger.
+    #
+    def []=( key, val ) @h[to_key(key)] = val end
+
+    # call-seq:
+    #    fetch( name )
+    #
+    # Returns the +Logger+ named _name_. An +IndexError+ will be raised if
+    # the logger does not exist.
+    #
+    # When _name_ is a +String+ or a +Symbol+ it will be used "as is" to
+    # retrieve the logger. When _name_ is a +Class+ the class name will be
+    # used to retrieve the logger. When _name_ is an object the name of the
+    # object's class will be used to retrieve the logger.
+    #
+    def fetch( key ) @h.fetch(to_key(key)) end
+
+    # call-seq:
+    #    has_logger?( name )
+    #
+    # Returns +true+ if the given logger exists in the repository. Returns
+    # +false+ if this is not the case.
+    #
+    # When _name_ is a +String+ or a +Symbol+ it will be used "as is" to
+    # retrieve the logger. When _name_ is a +Class+ the class name will be
+    # used to retrieve the logger. When _name_ is an object the name of the
+    # object's class will be used to retrieve the logger.
+    #
+    def has_logger?( key ) @h.has_key?(to_key(key)) end
+
+    # call-seq:
+    #    parent( key )
+    #
+    # Returns the parent logger for the logger identified by _key_ where
+    # _key_ follows the same identification rules described in
+    # <tt>Repository#[]</tt>. A parent is returned regardless of the
+    # existence of the logger referenced by _key_.
+    #
+    # A note about parents -
+    #
+    # If you have a class A::B::C, then the parent of C is B, and the parent
+    # of B is A. Parents are determined by namespace.
+    #
+    def parent( key )
+      name = parent_name(to_key(key))
+      return if name.nil?
+      @h[name]
+    end
+
+    # call-seq:
+    #    children( key )
+    #
+    # Returns an array of the children loggers for the logger identified by
+    # _key_ where _key_ follows the same identification rules described in
+    # +Repository#[]+. Children are returned regardless of the
+    # existence of the logger referenced by _key_.
+    #
+    def children( parent )
+      ary = []
+      parent = to_key(parent)
+
+      @h.each_pair do |child,logger|
+        next if :root == child
+        ary << logger if parent == parent_name(child)
+      end
+      return ary.sort
+    end
+
+    # call-seq:
+    #    to_key( key )
+    #
+    # Takes the given _key_ and converts it into a form that can be used to
+    # retrieve a logger from the +Repository+ hash.
+    #
+    # When _key_ is a +String+ or a +Symbol+ it will be returned "as is".
+    # When _key_ is a +Class+ the class name will be returned. When _key_ is
+    # an object the name of the object's class will be returned.
+    #
+    def to_key( key )
+      case key
+      when :root, 'root'; :root
+      when String; key
+      when Symbol; key.to_s
+      when Module; key.logger_name
+      when Object; key.class.logger_name
+      end
+    end
+
+    # Returns the name of the parent for the logger identified by the given
+    # _key_. If the _key_ is for the root logger, then +nil+ is returned.
+    #
+    def parent_name( key )
+      return if :root == key
+
+      a = key.split PATH_DELIMITER
+      p = :root
+      while a.slice!(-1) and !a.empty?
+        k = a.join PATH_DELIMITER
+        if @h.has_key? k then p = k; break end
+      end
+      p
+    end
+
+    # call-seq:
+    #    add_master( 'First::Name', 'Second::Name', ... )
+    #
+    # Add the given logger names to the list of consolidation masters. All
+    # classes in the given namespace(s) will use these loggers instead of
+    # creating their own individual loggers.
+    #
+    def add_master( *args )
+      args.map do |key|
+        key = to_key(key)
+        @masters << key unless @masters.include? key
+        key
+      end
+    end
+
+    # call-seq:
+    #    master_for( key )
+    #
+    # Retruns the consolidation master name for the given _key_. If there is
+    # no consolidation master, then +nil+ is returned.
+    #
+    def master_for( key )
+      return if @masters.empty?
+      key = to_key(key)
+
+      loop do
+        break key if @masters.include? key
+        break nil if :root == key
+
+        if index = key.rindex(PATH_DELIMITER)
+          key = key.slice(0, index)
+        else
+          key = :root
+        end
+      end
+    end
+
+    # :stopdoc:
+    def self.reset
+      if defined?(@singleton__instance__)
+        @singleton__mutex__.synchronize {
+          @singleton__instance__ = nil
+        }
+      else
+        @__instance__ = nil
+        class << self
+          nonce = class << Singleton; self; end
+          if defined?(nonce::FirstInstanceCall)
+            define_method(:instance, nonce::FirstInstanceCall)
+          else
+            remove_method(:instance)
+            Singleton.__init__(::Logging::Repository)
+          end
+        end
+      end
+      return nil
+    end
+    # :startdoc:
+
+  end  # class Repository
+end  # module Logging
+
+# EOF

data/lib/logging/root_logger.rb

@@ -0,0 +1,61 @@
+
+module Logging
+
+  # The root logger exists to ensure that all loggers have a parent and a
+  # defined logging level. If a logger is additive, eventually its log
+  # events will propogate up to the root logger.
+  #
+  class RootLogger < Logger
+
+    # undefine the methods that the root logger does not need
+    %w(additive additive= parent parent=).each do |m|
+      undef_method m.intern
+    end
+
+    attr_reader :level
+
+    # call-seq:
+    #    RootLogger.new
+    #
+    # Returns a new root logger instance. This method will be called only
+    # once when the +Repository+ singleton instance is created.
+    #
+    def initialize( )
+      ::Logging.init unless ::Logging.const_defined? 'MAX_LEVEL_LENGTH'
+
+      @name = 'root'
+      @appenders = []
+      @additive = false
+      @trace = false
+      @level = 0
+      ::Logging::Logger.define_log_methods(self)
+    end
+
+    # call-seq:
+    #    log <=> other
+    #
+    # Compares this logger by name to another logger. The normal return codes
+    # for +String+ objects apply.
+    #
+    def <=>( other )
+      case other
+      when self; 0
+      when ::Logging::Logger; -1
+      else raise ArgumentError, 'expecting a Logger instance' end
+    end
+
+    # call-seq:
+    #    level = :all
+    #
+    # Set the level for the root logger. The functionality of this method is
+    # the same as +Logger#level=+, but setting the level to +nil+ for the
+    # root logger is not allowed. The level is silently set to :all.
+    #
+    def level=( level )
+      super(level || 0)
+    end
+
+  end  # class RootLogger
+end  # module Logging
+
+# EOF

data/lib/logging/stats.rb

@@ -0,0 +1,278 @@
+# Simple statistics collection and logging module.
+#
+module Logging::Stats
+
+  # A very simple little class for doing some basic fast statistics
+  # sampling. You feed it either samples of numeric data you want measured
+  # or you call Sampler#tick to get it to add a time delta between the last
+  # time you called it. When you're done either call sum, sumsq, num, min,
+  # max, mean or sd to get the information. The other option is to just
+  # call to_s and see everything.
+  #
+  # It does all of this very fast and doesn't take up any memory since the
+  # samples are not stored but instead all the values are calculated on the
+  # fly.
+  #
+  class Sampler
+
+    attr_reader :name, :sum, :sumsq, :num, :min, :max, :last
+
+    # Create a new sampler.
+    #
+    def initialize( name )
+      @name = name
+      reset
+    end
+
+    # Resets the internal counters so you can start sampling again.
+    #
+    def reset
+      @sum = 0.0
+      @sumsq = 0.0
+      @num = 0
+      @min = 0.0
+      @max = 0.0
+      @last = nil
+      @last_time = Time.now.to_f
+      self
+    end
+
+    # Coalesce the statistics from the _other_ sampler into this one. The
+    # _other_ sampler is not modified by this method.
+    #
+    # Coalescing the same two samplers mutliple times should only be done if
+    # one of the samplers is reset between calls to this method. Otherwise
+    # statistics will be counted multiple times.
+    #
+    def coalesce( other )
+      @sum += other.sum
+      @sumsq += other.sumsq
+      if other.num > 0
+        @min = other.min if @min > other.min
+        @max = other.max if @max < other.max
+        @last = other.last
+      end
+      @num += other.num
+    end
+
+    # Adds a sampling to the calculations.
+    #
+    def sample( s )
+      @sum += s
+      @sumsq += s * s
+      if @num == 0
+        @min = @max = s
+      else
+        @min = s if @min > s
+        @max = s if @max < s
+      end
+      @num += 1
+      @last = s
+    end
+
+    # Returns statistics in a common format.
+    #
+    def to_s  
+      "[%s]: SUM=%0.6f, SUMSQ=%0.6f, NUM=%d, MEAN=%0.6f, SD=%0.6f, MIN=%0.6f, MAX=%0.6f" % to_a
+    end
+
+    # An array of the values: [name,sum,sumsq,num,mean,sd,min,max]
+    #
+    def to_a
+      [name, sum, sumsq, num, mean, sd, min, max]
+    end
+
+    # Class method that returns the headers that a CSV file would have for the
+    # values that this stats object is using.
+    #
+    def self.keys
+      %w[name sum sumsq num mean sd min max]
+    end
+
+    def to_hash
+      {:name => name, :sum => sum, :sumsq => sumsq, :num => num,
+       :mean => mean, :sd => sd, :min => min, :max => max}
+    end
+
+    # Calculates and returns the mean for the data passed so far.
+    #
+    def mean
+      return 0.0 if num < 1
+      sum / num
+    end
+
+    # Calculates the standard deviation of the data so far.
+    #
+    def sd
+      return 0.0 if num < 2
+
+      # (sqrt( ((s).sumsq - ( (s).sum * (s).sum / (s).num)) / ((s).num-1) ))
+      begin
+        return Math.sqrt( (sumsq - ( sum * sum / num)) / (num-1) )
+      rescue Errno::EDOM
+        return 0.0
+      end
+    end
+
+    # You can just call tick repeatedly if you need the delta times
+    # between a set of sample periods, but many times you actually want
+    # to sample how long something takes between a start/end period.
+    # Call mark at the beginning and then tick at the end you'll get this
+    # kind of measurement.  Don't mix mark/tick and tick sampling together
+    # or the measurement will be meaningless.
+    #
+    def mark
+      @last_time = Time.now.to_f
+    end
+
+    # Adds a time delta between now and the last time you called this.  This
+    # will give you the average time between two activities.
+    # 
+    # An example is:
+    #
+    #  t = Sampler.new("do_stuff")
+    #  10000.times { do_stuff(); t.tick }
+    #  t.dump("time")
+    #
+    def tick
+      now = Time.now.to_f
+      sample(now - @last_time)
+      @last_time = now
+    end
+  end  # class Sampler
+
+  # The Tracker class provides synchronized access to a collection of
+  # related samplers.
+  #
+  class Tracker
+
+    attr_reader :stats
+
+    # Create a new Tracker instance. An optional boolean can be bassed in to
+    # change the "threadsafe" value of the tracker. By default all trackers
+    # are created to be threadsafe.
+    #
+    def initialize( threadsafe = true )
+      @stats = Hash.new do |h,name|
+        h[name] = ::Logging::Stats::Sampler.new(name)
+      end
+      @mutex = threadsafe ? ReentrantMutex.new : nil
+      @runner = nil
+    end
+
+    # Coalesce the samplers from the _other_ tracker into this one. The
+    # _other_ tracker is not modified by this method.
+    #
+    # Coalescing the same two trackers mutliple times should only be done if
+    # one of the trackers is reset between calls to this method. Otherwise
+    # statistics will be counted multiple times.
+    #
+    # Only this tracker is locked when the coalescing is happening. It is
+    # left to the user to lock the other tracker if that is the desired
+    # behavior. This is a deliberate choice in order to prevent deadlock
+    # situations where two threads are contending on the same mutex.
+    #
+    def coalesce( other )
+      sync {
+        other.stats.each do |name,sampler|
+          stats[name].coalesce(sampler)
+        end
+      }
+    end
+
+    # Add the given _value_ to the named _event_ sampler. The sampler will
+    # be created if it does not exist.
+    #
+    def sample( event, value )
+      sync {stats[event].sample(value)}
+    end
+
+    # Mark the named _event_ sampler. The sampler will be created if it does
+    # not exist.
+    #
+    def mark( event )
+      sync {stats[event].mark}
+    end
+
+    # Tick the named _event_ sampler. The sampler will be created if it does
+    # not exist.
+    #
+    def tick( event )
+      sync {stats[event].tick}
+    end
+
+    # Time the execution of the given block and store the results in the
+    # named _event_ sampler. The sampler will be created if it does not
+    # exist.
+    #
+    def time( event )
+      sync {stats[event].mark}
+      yield
+    ensure
+      sync {stats[event].tick}
+    end
+
+    # Reset all the samplers managed by this tracker.
+    #
+    def reset
+      sync {stats.each_value {|sampler| sampler.reset}}
+      self
+    end
+
+    # Periodically execute the given _block_ at the given _period_. The
+    # tracker will be locked while the block is executing.
+    #
+    # This method is useful for logging statistics at given interval.
+    #
+    # Example
+    #
+    #    periodically_run( 300 ) {
+    #      logger = Logging::Logger['stats']
+    #      tracker.each {|sampler| logger << sampler.to_s}
+    #      tracker.reset
+    #    }
+    #
+    def periodically_run( period, &block )
+      raise ArgumentError, 'a runner already exists' unless @runner.nil?
+
+      @runner = Thread.new do
+        start = stop = Time.now.to_f
+        loop do
+          seconds = period - (stop-start)
+          seconds = period if seconds <= 0
+          sleep seconds
+
+          start = Time.now.to_f
+          break if Thread.current[:stop] == true
+          if @mutex then @mutex.synchronize(&block)
+          else block.call end
+          stop = Time.now.to_f
+        end
+      end
+    end
+
+    # Stop the current periodic runner if present.
+    #
+    def stop
+      return if @runner.nil?
+      @runner[:stop] = true
+      @runner.wakeup if @runner.status
+      @runner = 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
+      return yield if @mutex.nil?
+      @mutex.synchronize {yield}
+    end
+  end  # class Tracker
+
+end  # module Logging::Stats
+
+# EOF