logging 0.9.2 → 0.9.3

data/History.txt

@@ -1,3 +1,9 @@
+== 0.9.3 / 2008-09-12
+
+2 minor enhancement
+  - Added a class for tracking basic statistics
+  - Will use the 'fastthread' gem if availble
+
 == 0.9.2 / 2008-09-03
 
 2 bug fixes

data/Manifest.txt

@@ -25,6 +25,7 @@ lib/logging/log_event.rb
 lib/logging/logger.rb
 lib/logging/repository.rb
 lib/logging/root_logger.rb
+lib/logging/stats.rb
 lib/logging/utils.rb
 tasks/ann.rake
 tasks/bones.rake
@@ -57,4 +58,5 @@ test/test_logger.rb
 test/test_logging.rb
 test/test_repository.rb
 test/test_root_logger.rb
+test/test_stats.rb
 test/test_utils.rb

data/Rakefile

@@ -16,7 +16,7 @@ PROJ.rdoc.dir = 'doc/rdoc'
 #PROJ.rdoc.remote_dir = 'rdoc'
 PROJ.rdoc.remote_dir = ''
 PROJ.version = Logging::VERSION
-PROJ.release_name = %q{Meta Class Madness}
+PROJ.release_name = %q{Log-O-Stat}
 
 PROJ.exclude << %w[^tags$ ^tasks/archive ^coverage]
 PROJ.rdoc.exclude << '^data'

data/lib/logging.rb

@@ -3,6 +3,9 @@
 # Used to prevent the class/module from being loaded more than once
 unless defined? Logging
 
+require 'thread'
+begin require 'fastthread'; rescue LoadError; end
+
 # TODO: Windows Log Service appender
 
 #
@@ -10,7 +13,7 @@ unless defined? Logging
 module Logging
 
   # :stopdoc:
-  VERSION = '0.9.2'
+  VERSION = '0.9.3'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   WIN32 = %r/djgpp|(cyg|ms|bcc)win|mingw/ =~ RUBY_PLATFORM

data/lib/logging/appender.rb

@@ -1,6 +1,4 @@
 
-require 'thread'
-
 module Logging
 
 # The +Appender+ class is provides methods for appending log events to a

data/lib/logging/logger.rb

@@ -1,6 +1,4 @@
 
-require 'thread'
-
 module Logging
 
   # The +Logger+ class is the primary interface to the +Logging+ framework.

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

data/lib/logging/utils.rb

@@ -102,4 +102,29 @@ class Module
   end
 end
 
+class ReentrantMutex < Mutex
+
+  def initialize
+    super
+    @locker = nil
+  end
+
+  alias :original_synchronize :synchronize
+
+  def synchronize
+    if @locker == Thread.current
+      yield
+    else
+      original_synchronize {
+        begin
+          @locker = Thread.current
+          yield
+        ensure
+          @locker = nil
+        end
+      }
+    end
+  end
+end  # class ReentrantMutex
+
 # EOF

data/test/test_stats.rb

@@ -0,0 +1,274 @@
+
+require File.join(File.dirname(__FILE__), %w[setup])
+
+module TestLogging
+module TestStats
+
+  class TestSampler < Test::Unit::TestCase
+    include LoggingTestCase
+
+    def setup
+      super
+      @sampler = ::Logging::Stats::Sampler.new('test')
+    end
+
+    def test_reset
+      (1..10).each {|n| @sampler.sample n}
+
+      assert_equal 55,  @sampler.sum
+      assert_equal 385, @sampler.sumsq
+      assert_equal 10,  @sampler.num
+      assert_equal 1,   @sampler.min
+      assert_equal 10,  @sampler.max
+      assert_equal 10,  @sampler.last
+
+      @sampler.reset
+
+      assert_equal 0, @sampler.sum
+      assert_equal 0, @sampler.sumsq
+      assert_equal 0, @sampler.num
+      assert_equal 0, @sampler.min
+      assert_equal 0, @sampler.max
+      assert_nil @sampler.last
+    end
+
+    def test_coalesce
+      other = ::Logging::Stats::Sampler.new('other')
+      (1..5).each {|n| other.sample n}
+      (6..10).each {|n| @sampler.sample n}
+
+      assert_equal 5, @sampler.num
+
+      @sampler.coalesce other
+
+      assert_equal 55,  @sampler.sum
+      assert_equal 385, @sampler.sumsq
+      assert_equal 10,  @sampler.num
+      assert_equal 1,   @sampler.min
+      assert_equal 10,  @sampler.max
+      assert_equal 5,   @sampler.last
+
+      @sampler.coalesce ::Logging::Stats::Sampler.new('tmp')
+
+      assert_equal 55,  @sampler.sum
+      assert_equal 385, @sampler.sumsq
+      assert_equal 10,  @sampler.num
+      assert_equal 1,   @sampler.min
+      assert_equal 10,  @sampler.max
+      assert_equal 5,   @sampler.last
+    end
+
+    def test_sample
+      @sampler.sample 1
+
+      assert_equal 1, @sampler.sum
+      assert_equal 1, @sampler.sumsq
+      assert_equal 1, @sampler.num
+      assert_equal 1, @sampler.min
+      assert_equal 1, @sampler.max
+      assert_equal 1, @sampler.last
+
+      @sampler.sample 2
+
+      assert_equal 3, @sampler.sum
+      assert_equal 5, @sampler.sumsq
+      assert_equal 2, @sampler.num
+      assert_equal 1, @sampler.min
+      assert_equal 2, @sampler.max
+      assert_equal 2, @sampler.last
+    end
+
+    def test_to_s
+      (1..10).each {|n| @sampler.sample n}
+      assert_equal(
+        "[test]: SUM=55.000000, SUMSQ=385.000000, NUM=10, MEAN=5.500000, SD=3.027650, MIN=1.000000, MAX=10.000000",
+        @sampler.to_s
+      )
+    end
+
+    def test_to_a
+      (1..10).each {|n| @sampler.sample n}
+      assert_equal(
+        ['test', 55, 385, 10, 5.5, @sampler.sd, 1, 10],
+        @sampler.to_a
+      )
+    end
+
+    def test_to_hash
+      (1..10).each {|n| @sampler.sample n}
+      assert_equal(
+        {:name => 'test', :sum => 55, :sumsq => 385, :num => 10, :mean => 5.5, :sd => @sampler.sd, :min => 1, :max => 10},
+        @sampler.to_hash
+      )
+    end
+
+    def test_mean
+      assert_equal 0, @sampler.mean
+
+      @sampler.sample 10
+      assert_equal 10, @sampler.mean
+
+      @sampler.sample 20
+      assert_equal 15, @sampler.mean
+    end
+
+    def test_sd
+      assert_equal 0, @sampler.sd
+
+      @sampler.sample 1
+      assert_equal 0, @sampler.sd
+
+      @sampler.sample 2
+      assert_in_delta 0.707106781186548, @sampler.sd, 1e-10
+
+      @sampler.sample 3
+      assert_in_delta 1.0, @sampler.sd, 1e-10
+
+      @sampler.sample 4
+      assert_in_delta 1.29099444873581, @sampler.sd, 1e-10
+    end
+
+    def test_mark_and_tick
+      10.times do
+        @sampler.mark
+        sleep 0.01
+        @sampler.tick
+      end
+
+      assert_equal 10, @sampler.num
+      assert_in_delta 0.01, @sampler.mean, 1e-3
+    end
+  end  # class TestSampler
+
+  class TestTracker < Test::Unit::TestCase
+    include LoggingTestCase
+
+    def setup
+      super
+      @tracker = ::Logging::Stats::Tracker.new
+      @stats = @tracker.stats
+    end
+
+    def test_coalesce
+      1.times {|n| @tracker.sample('foo', n)}
+      2.times {|n| @tracker.sample('bar', n)}
+      3.times {|n| @tracker.sample('baz', n)}
+
+      assert_equal %w[bar baz foo], @stats.keys.sort
+      assert_equal 1, @stats['foo'].num
+      assert_equal 2, @stats['bar'].num
+      assert_equal 3, @stats['baz'].num
+
+      # when other is empty, nothing should change in our tracker
+      other = ::Logging::Stats::Tracker.new
+      @tracker.coalesce other
+
+      assert_equal %w[bar baz foo], @stats.keys.sort
+      assert_equal 1, @stats['foo'].num
+      assert_equal 2, @stats['bar'].num
+      assert_equal 3, @stats['baz'].num
+
+      # now add some samples to other
+      4.times {|n| other.sample('buz', n)}
+      5.times {|n| other.sample('bar', n)}
+      @tracker.coalesce other
+
+      assert_equal %w[bar baz buz foo], @stats.keys.sort
+      assert_equal 1, @stats['foo'].num
+      assert_equal 7, @stats['bar'].num
+      assert_equal 3, @stats['baz'].num
+      assert_equal 4, @stats['buz'].num
+    end
+
+    def test_mark
+      assert @stats.empty?
+      @tracker.mark 'foo'
+      assert !@stats.empty?
+
+      sampler = @stats['foo']
+      assert_equal 0, sampler.num
+    end
+
+    def test_tick
+      assert @stats.empty?
+      @tracker.tick 'foo'
+      assert !@stats.empty?
+
+      sampler = @stats['foo']
+      assert_equal 1, sampler.num
+    end
+
+    def test_sample
+      assert @stats.empty?
+      @tracker.sample 'foo', 1
+      assert !@stats.empty?
+
+      sampler = @stats['foo']
+      assert_equal 1, sampler.num
+      assert_equal 1, sampler.last
+
+      @tracker.sample 'foo', 2
+      assert_equal 2, sampler.num
+      assert_equal 2, sampler.last
+      assert_equal 3, sampler.sum
+    end
+
+    def test_time
+      assert @stats.empty?
+      @tracker.time('foo') {sleep 0.05}
+      assert !@stats.empty?
+
+      sampler = @stats['foo']
+      assert_equal 1, sampler.num
+      assert_in_delta 0.05, sampler.sum, 1e-3
+
+      @tracker.time('foo') {sleep 0.05}
+      assert_equal 2, sampler.num
+      assert_in_delta 0.10, sampler.sum, 1e-2
+
+      assert_raise(RuntimeError) do
+        @tracker.time('foo') {raise 'Uh Oh!'}
+      end
+      assert_equal 3, sampler.num
+    end
+
+    def test_reset
+      1.times {|n| @tracker.sample('foo', n)}
+      2.times {|n| @tracker.sample('bar', n)}
+      3.times {|n| @tracker.sample('baz', n)}
+
+      assert_equal 1, @stats['foo'].num
+      assert_equal 2, @stats['bar'].num
+      assert_equal 3, @stats['baz'].num
+
+      @tracker.reset
+
+      assert_equal 0, @stats['foo'].num
+      assert_equal 0, @stats['bar'].num
+      assert_equal 0, @stats['baz'].num
+    end
+
+    def test_reentrant_synchronization
+      assert_nothing_raised do
+        @tracker.sync {
+          @tracker.sample('foo', Math::PI)
+          @tracker.reset
+        }
+      end
+    end
+
+    def test_periodically_run
+      @tracker.periodically_run(0.1) {
+        @tracker.tick 'foo'
+      }
+      sleep 0.5
+      @tracker.stop
+
+      assert(@stats['foo'].num > 1)
+    end
+  end  # class TestTracker
+
+end  # module TestStats
+end  # module TestLogging
+
+# EOF

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: logging
 version: !ruby/object:Gem::Version 
-  version: 0.9.2
+  version: 0.9.3
 platform: ruby
 authors: 
 - Tim Pease
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-03 00:00:00 -06:00
+date: 2008-09-13 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -69,6 +69,7 @@ files:
 - lib/logging/logger.rb
 - lib/logging/repository.rb
 - lib/logging/root_logger.rb
+- lib/logging/stats.rb
 - lib/logging/utils.rb
 - tasks/ann.rake
 - tasks/bones.rake
@@ -101,6 +102,7 @@ files:
 - test/test_logging.rb
 - test/test_repository.rb
 - test/test_root_logger.rb
+- test/test_stats.rb
 - test/test_utils.rb
 has_rdoc: true
 homepage: http://logging.rubyforge.org/
@@ -148,4 +150,5 @@ test_files:
 - test/test_logging.rb
 - test/test_repository.rb
 - test/test_root_logger.rb
+- test/test_stats.rb
 - test/test_utils.rb