class Hitimes::TimedValueMetric

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.

Attributes

timed_stats[R]

holds all the Timed statistics

value_stats[R]

holds all the Value statistics

Public Class Methods

new( 'name') → TimedValueMetric click to toggle source
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

Calls superclass method Hitimes::Metric::new
# File lib/hitimes/timed_value_metric.rb, line 58
def initialize( name, additional_data = {} )
  super( name, additional_data )
  @timed_stats      = Stats.new
  @value_stats      = Stats.new
  @current_interval = Interval.new
end
now( 'name' ) → TimedValueMetric click to toggle source

Return a TimedValueMetric that has been started

# File lib/hitimes/timed_value_metric.rb, line 43
def now( name, additional_data = {} )
  t = TimedValueMetric.new( name, additional_data )
  t.start
  return t
end

Public Instance Methods

duration → Float click to toggle source

The duration of measured time from the metric.

# File lib/hitimes/timed_value_metric.rb, line 172
def duration
  @timed_stats.sum
end
measure( value ) { ... } → Object click to toggle source

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.

# File lib/hitimes/timed_value_metric.rb, line 129
def measure( value, &block )
  return_value = nil
  begin
    start
    return_value = yield
  ensure
    stop( value )
  end
  return return_value
end
rate → Float click to toggle source

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 ) )
# File lib/hitimes/timed_value_metric.rb, line 212
def rate
  @value_stats.sum / @timed_stats.sum
end
running? → true or false click to toggle source

return whether or not the metric is currently timing something.

# File lib/hitimes/timed_value_metric.rb, line 71
def running?
  @current_interval.running?
end
split( value ) → Float click to toggle source

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.

# File lib/hitimes/timed_value_metric.rb, line 154
def split( value )
  if @current_interval.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
start → nil click to toggle source

Start the current timer, if the current timer is already started, then this is a noop.

# File lib/hitimes/timed_value_metric.rb, line 82
def start
  if not @current_interval.running? then
    @current_interval.start
    @sampling_start_time ||= self.utc_microseconds() 
    @sampling_start_interval ||= Interval.now
  end
  nil
end
stop( count ) → Float or nil click to toggle source

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.

# File lib/hitimes/timed_value_metric.rb, line 106
def stop( value )
  if @current_interval.running? then
    d = @current_interval.stop
    @timed_stats.update( d )
    @current_interval = Interval.new
    @value_stats.update( value )

    # update the lenght of time we have been sampling
    @sampling_delta = @sampling_start_interval.duration_so_far

    return d
  end
  return false
end
to_hash → Hash click to toggle source

Convert the metric to a hash

Calls superclass method Hitimes::Metric#to_hash
# File lib/hitimes/timed_value_metric.rb, line 222
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
unit_count → Float click to toggle source

The sum of all values passed to stop or skip or measure

# File lib/hitimes/timed_value_metric.rb, line 182
def unit_count
  @value_stats.sum
end