hitimes 0.4.1-x86-mswin32-60 → 1.0.0-x86-mswin32-60

data/lib/hitimes/timed_value_metric.rb

@@ -0,0 +1,240 @@
+#--
+# Copyright (c) 2008, 2009 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'hitimes'
+
+module Hitimes
+  #
+  # A TimedValueMetric holds the metrics on how long it takes to do a batch of something.
+  # something.  For measuring how long a method takes to operate on N items.
+  #
+  #   tm = TimedValueMetric.new( 'my-batch-method' )
+  #
+  #   42.times do 
+  #     tm.start
+  #     number_of_items_processed = do_something
+  #     tm.stop( number_of_items_processed )
+  #   end
+  #
+  #   puts "#{ tm.name } operated at a rate of #{ tm.rate } calls per second"
+  #
+  # TimedValueMetric combines the usefulness of a ValueMetric and a TimedMetric.
+  # The stats are available for both the time it took to do the operation and
+  # the sizes of the batches that were run.
+  #
+  # A TimedValueMetric keeps track of both the time it took to do an operation
+  # and the size of the batch that was operated on.  These metrics are kept
+  # separately as +timed_stats+ and +value_stats+ accessors.
+  #
+  class TimedValueMetric < Metric
+    # holds all the Timed statistics
+    attr_reader :timed_stats
+
+    # holds all the Value statistics
+    attr_reader :value_stats
+
+    class << TimedValueMetric
+      #
+      # :call-seq:
+      #   TimedValueMetric.now( 'name' ) -> TimedValueMetric
+      #
+      # Return a TimedValueMetric that has been started
+      #
+      def now( name, additional_data = {} )
+        t = TimedValueMetric.new( name, additional_data )
+        t.start
+        return t
+      end
+    end
+
+    #
+    # :call-seq:
+    #   TimedValueMetric.new( 'name') -> TimedValueMetric
+    #   TimedValueMetric.new( 'name', 'other' => 'data') -> TimedValueMetric
+    #
+    # Create a new TimedValueMetric giving it a name and additional data.
+    # +additional_data+ may be anything that follows the +to_hash+ protocol
+    #
+    def initialize( name, additional_data = {} )
+      super( name, additional_data )
+      @current_interval = nil
+      @timed_stats      = Stats.new
+      @value_stats      = Stats.new
+    end
+
+    #
+    # :call-seq:
+    #   timed_value_metric.current_interval -> Interval
+    #
+    # Return the current interval, if one doesn't exist create one.
+    #
+    def current_interval
+      @current_interval ||= Interval.new
+    end
+
+
+    #
+    # :call-seq:
+    #   timed_value_metric.running? -> true or false
+    #
+    # return whether or not the metric is currently timing something.
+    #
+    def running?
+      current_interval.running?
+    end
+
+    # 
+    # :call-seq:
+    #   timed_value_metric.start -> nil
+    #
+    # Start the current timer, if the current timer is already started, then
+    # this is a noop.  
+    #
+    def start
+      current_interval.start unless running?
+      @sampling_start_time ||= self.utc_microseconds() 
+      nil
+    end
+
+    #
+    # :call-seq:
+    #   timed_value_metric.stop( count ) -> Float or nil
+    #
+    # Stop the current metric.  The +count+ parameter must be a
+    # value to update to the _value_ portion of the TimedValueMetric.  Generally
+    # this is probably the number of things that were operated upon since
+    # +start+ was invoked.
+    #
+    # This updates both the +value_stats+ and +timed_stats+ stats and removes
+    # the current interval. If the metric is stopped then the duration of the
+    # last Interval is returned.  If the metric was already stopped before this
+    # call, then false is returned and no stats are updated.
+    # 
+    #
+    def stop( value )
+      if running? then
+        d = current_interval.stop
+        @current_interval = nil
+        @sampling_stop_time = self.utc_microseconds()
+        @timed_stats.update( d )
+        @value_stats.update( value )
+        return d
+      end
+      return false
+    end
+
+    #
+    # :call-seq:
+    #   timed_value_metric.measure( value ) {  ... } -> Object
+    #
+    # Measure the execution of a block and add those stats to the running stats.
+    # The return value is the return value of the block.  A value must be passed
+    # into +measure+ to update the +value_stats+ portion of the TimedValueMetric.
+    #
+    def measure( value, &block )
+      return_value = nil
+      begin
+        start
+        return_value = yield
+      ensure
+        stop( value )
+      end
+      return return_value
+    end
+
+    #
+    # :call-seq:
+    #   timed_value_metric.split( value ) -> Float
+    #
+    # Split the current metric.  Essentially, mark a split time.  This means
+    # stop the current interval, with the givein +value+ and create a new
+    # interval, but make sure that the new interval lines up exactly, timewise,
+    # behind the previous interval.
+    #
+    # If the metric is running, then split returns the duration of the previous
+    # interval, i.e. the split-time.  If the metric is not running, nothing
+    # happens, no stats are updated, and false is returned.  
+    #
+    #
+    def split( value )
+      if running? then 
+        next_interval = current_interval.split
+        d = current_interval.duration
+        @timed_stats.update( d )
+        @value_stats.update( value )
+        @current_interval = next_interval 
+        return d
+      end 
+      return false
+    end
+
+    #
+    # :call-seq:
+    #   timed_value_metric.duration -> Float
+    #
+    # The duration of measured time from the metric.
+    #
+    def duration
+      @timed_stats.sum
+    end
+
+    #
+    # :call-seq:
+    #   timed_value_metric.unit_count -> Float
+    #
+    # The sum of all values passed to +stop+ or +skip+ or +measure+
+    #
+    def unit_count
+      @value_stats.sum
+    end
+
+    #
+    # :call-seq:
+    #   timed_value_metric.rate -> Float
+    #
+    # Rate in the context of the TimedValueMetric is different than the
+    # TimedMetric.  In the TimedValueMetric, each measurement of time is
+    # associated with a quantity of things done during that unit of time.  So
+    # the +rate+ for a TimedValueMetric is the (sum of all quantities sampled) /
+    # ( sum of all durations measured )
+    # 
+    # For example, say you were measuring, using a TimedValueMetric batch jobs
+    # that had individual units of work.
+    #
+    #   tvm = TimedValueMetric.new( 'some-batch' )
+    #   tvm.start
+    #   # process a batch of 12 units
+    #   duration1 = tvm.stop( 12 )
+    #
+    #   tvm.start
+    #   # process a larger batch of 42 units
+    #   duration2 = tvm.stop( 42 )
+    #
+    # At this point the rate of units per second is calculated as ( 12 + 42 ) / ( duration1 + duration2 )
+    #
+    #   some_batch_rate = tvm.rate # returns ( 34 / ( duration1+duration2 ) )
+    # 
+    def rate
+      @value_stats.sum / @timed_stats.sum
+    end
+
+    #
+    # :call-seq:
+    #   metric.to_hash -> Hash
+    #   
+    # Convert the metric to a hash
+    #
+    def to_hash
+      h = super
+      h['timed_stats'] = @timed_stats.to_hash
+      h['value_stats'] = @value_stats.to_hash( Stats::STATS - %w[ rate ] )
+      h['rate'] = self.rate
+      h['unit_count'] = self.unit_count
+      return h
+    end
+
+
+  end
+end

data/lib/hitimes/value_metric.rb

@@ -0,0 +1,69 @@
+#--
+# Copyright (c) 2008, 2009 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'forwardable'
+require 'hitimes'
+module Hitimes
+  #
+  # A ValueMetric holds the data from measuring a single value over a period of
+  # time.  In most cases this may be a single measurement at a single point in
+  # time.
+  #
+  # A good example of a ValueMetric is measuring the number of items in a queue.
+  #
+  # A ValueMetric contains a Stats object, therefore ValueMetric has +count+, +max+, 
+  # +mean+, +min+, +stddev+, +sum+, +sumsq+ methods that delegate to that Stats
+  # object for convenience.
+  #
+  class ValueMetric < Metric
+
+    # holds all the statistics
+    attr_reader :stats
+    
+    #
+    # :call-seq:
+    #   ValueMetric.new( 'my_metric' ) -> ValueMetric
+    #   ValueMetric.new( 'my_metric', 'foo' => 'bar', 'this' => 42 ) -> ValueMetric
+    #
+    # Create a new ValueMetric giving it a name and additional data.
+    # +additional_data+ may be anything that follows the +to_hash+ protocol.
+    #
+    def initialize( name, additional_data = {} )
+      super( name, additional_data )
+      @stats = Stats.new
+    end
+
+    #
+    # :call-seq:
+    #   metric.measure( value ) -> Float
+    #
+    # Give the +value+ as the measurement to the metric.  The value is returned
+    #
+    def measure( value )
+      now = self.utc_microseconds()
+      @sampling_start_time ||= now
+      @sampling_stop_time = now
+      @stats.update( value )
+    end
+
+    #
+    # :call-seq:
+    #   metric.to_hash -> Hash
+    #   
+    # Convert the metric to a hash
+    #
+    def to_hash
+      h = super
+      (Stats::STATS - %w[ rate ]).each do |s|
+        h[s] = self.send( s ) 
+      end
+      return h
+    end
+
+    # forward appropriate calls directly to the stats object
+    extend Forwardable
+    def_delegators :@stats, :count, :sum, :max, :mean, :min, :stddev, :sum, :sumsq
+ end
+end

data/lib/hitimes/version.rb

@@ -9,9 +9,14 @@ module Hitimes
   #
   module Version
 
-    MAJOR   = 0
-    MINOR   = 4
-    BUILD   = 1
+    # Major version number
+    MAJOR   = 1
+
+    # Minor version number
+    MINOR   = 0
+
+    # Build number
+    BUILD   = 0
 
     #
     # :call-seq:
@@ -19,24 +24,34 @@ module Hitimes
     #
     # Return the version as an array of Integers
     #
-    def to_a
+    def self.to_a
       [MAJOR, MINOR, BUILD]
     end
 
     #
     # :call-seq:
-    #   Version.to_s -> MAJOR.MINOR.BUILD
+    #   Version.to_s -> "MAJOR.MINOR.BUILD"
     #
     # Return the version as a String with dotted notation
     #
-    def to_s
+    def self.to_s
       to_a.join(".")
     end
 
-    module_function :to_a
-    module_function :to_s
+    #
+    # :call-seq:
+    #   Version.to_hash -> { :major => ..., :minor => ..., :build => ... }
+    #
+    # Return the version as a Hash
+    #
+    def self.to_hash
+      { :major => MAJOR, :minor => MINOR, :build => BUILD }
+    end
 
+    # The Version in MAJOR.MINOR.BUILD dotted notation
     STRING = Version.to_s
   end
+
+  # The Version in MAJOR.MINOR.BUILD dotted notation
   VERSION = Version.to_s
 end

data/spec/metric_spec.rb

@@ -0,0 +1,30 @@
+require File.expand_path( File.join( File.dirname( __FILE__ ), "spec_helper.rb" ) )
+
+require 'hitimes/metric'
+
+describe Hitimes::Metric do
+  before( :each ) do
+    @metric = Hitimes::Metric.new( "testing" )
+  end
+
+  it 'has a name' do
+    @metric.name.should == "testing"
+  end
+
+  it "has associated data from initialization" do
+    m = Hitimes::Metric.new( "more-data", 'foo' => 'bar', 'this' => 'that' )
+    m.additional_data['foo'].should == 'bar'
+    m.additional_data['this'].should == 'that'
+    
+    m = Hitimes::Metric.new( "more-data", { 'foo' => 'bar', 'this' => 'that' } )
+    m.additional_data['foo'].should == 'bar'
+    m.additional_data['this'].should == 'that'
+  end
+
+  it "initially has no sampling times" do
+    @metric.sampling_start_time.should == nil
+    @metric.sampling_stop_time.should == nil
+  end
+end
+
+ 

data/spec/stats_spec.rb

@@ -1,6 +1,7 @@
 require File.expand_path( File.join( File.dirname( __FILE__ ), "spec_helper.rb" ) )
 
-require 'hitimes_ext'
+require 'hitimes/stats'
+require 'json'
 
 describe Hitimes::Stats do
   before( :each ) do
@@ -46,6 +47,10 @@ describe Hitimes::Stats do
     @full_stats.stddev.should == 1.0
   end 
 
+  it "calculates the sum of squares " do
+    @full_stats.sumsq.should == 14.0
+  end 
+
   describe "#to_hash " do
     it "converts to a Hash" do
       h = @full_stats.to_hash
@@ -66,7 +71,30 @@ describe Hitimes::Stats do
     it "raises NoMethodError if an invalid stat is used" do
       lambda { @full_stats.to_hash( "wibble" ) }.should raise_error( NoMethodError )
     end
-
   end
 
+  describe "#to_json" do
+    it "converts to a json string" do
+      j = @full_stats.to_json
+      h = JSON.parse( j )
+      h.size.should == ::Hitimes::Stats::STATS.size
+      h.keys.sort.should == ::Hitimes::Stats::STATS
+    end
+
+    it "converts to a limited Hash if given arguments" do
+      j = @full_stats.to_json( "min", "max", "mean" )
+      h = JSON.parse( j )
+      h.size.should == 3
+      h.keys.sort.should == %w[ max mean min  ]
+
+      j = @full_stats.to_json( %w[ count rate ] )
+      h = JSON.parse( j )
+      h.size.should == 2
+      h.keys.sort.should == %w[ count rate ]
+    end
+
+    it "raises NoMethodError if an invalid stat is used" do
+      lambda { @full_stats.to_json( "wibble" ) }.should raise_error( NoMethodError )
+    end
+  end
 end