aggregate 0.1.2 → 0.2.0

data/README

@@ -1,2 +1,169 @@
-Aggregate is a ruby implementation of a statistics aggregator including histogram support
+Aggregate is an intuitive ruby implementation of a statistics aggregator
+including both default and configurable histogram support. It does this
+without recording/storing any of the actual sample values, making it
+suitable for tracking statistics across millions/billions of sample
+without any impact on performance or memory footprint. Originally
+inspired by the Aggregate support in SystemTap (http://sourceware.org/systemtap/)
 
+Aggregates are easy to instantiate, populate with sample data, and examine
+statistics:
+
+#After instantiation use the << operator to add a sample to the aggregate:
+stats = Aggregate.new
+
+loop do
+  # Take some action that generates a sample measurement
+  stats << sample
+end
+
+# The number of samples
+stats.count
+
+# The average
+stats.mean
+
+# Max sample value
+stats.max
+
+# Min sample value
+stats.min
+
+# The standard deviation
+stats.std_dev
+
+Perhaps more importantly than the basic aggregate statistics detailed above
+Aggregate also maintains a histogram of samples. Good explanation of why
+its important: http://37signals.com/svn/posts/1836-the-problem-with-averages
+
+The histogram is maintained as a set of "buckets". Each bucket represents a
+range of possible sample values. The set of all buckets represents the range
+of "normal" sample values. By default this is a binary histogram, where
+each bucket represents a range twice as large as the preceding bucket i.e.
+[1,1], [2,3], [4,5,6,7], [8,9,10,11,12,13,14,15]. The default binary histogram
+provides for 128 buckets, theoretically covering the range [1, (2^127) - 1]
+(See NOTES below for a discussion on the effects in practice of insufficient
+precision.)
+
+Binary histograms are useful when we have little idea about what the
+sample distribution may look like as almost any positive value will
+fall into some bucket. After using binary histograms to determine
+the coarse-grained characteristics of your sample space you can
+configure a linear histogram to examine it in closer detail.
+
+Linear histograms are specified with the three values low, high, and width.
+Low and high specifiy a range [low, high) of values included in the
+histogram (all others are outliers). Width specifies the number of
+values represented by each bucket and therefore the number of
+buckets i.e. granularity of the histogram. The histogram range
+(high - low) must be a multiple of width:
+
+#Want to track aggregate stats on response times in ms
+response_stats = Aggregate.new(0, 2000, 50)
+
+The example above creates a linear histogram that tracks the
+response times from 0 ms to 2000 ms in buckets of width 50 ms. Hopefully
+most of your samples fall in the first couple buckets! Any values added to the
+aggregate that fall outside of the histogram range are recorded as outliers:
+
+# Number of samples that fall below the normal range
+stats.outliers_low
+
+# Number of samples that fall above the normal range
+stats.outliers_high
+
+Once a histogram is populated Aggregate provides iterator support for
+examining the contents of buckets. The iterators provide both the
+number of samples in the bucket, as well as its range:
+
+#Examine every bucket
+@stats.each do |bucket, count|
+end
+
+#Examine only buckets containing samples
+@stats.each_nonzero do |bucket, count|
+end
+
+Finally Aggregate contains sophisticated pretty-printing support that for
+any given number of columns >= 80 (defaults to 80) and sample distribution
+properly sets a marker weight based on the samples per bucket and aligns all
+output. Empty buckets are skipped to conserve screen space.
+
+# Generate and display an 80 column histogram
+puts stats.to_s
+
+# Generate and display a 120 column histogram
+puts stats.to_s(120)
+
+The following code populates both a binary and linear histogram with the same
+set of 65536 values generated by rand to produce two histograms:
+
+require 'rubygems'
+require 'aggregate'
+
+# Create an Aggregate instance
+binary_aggregate = Aggregate.new
+linear_aggregate = Aggregate.new(0, 65536, 8192)
+
+65536.times do
+  x = rand(65536)
+  binary_aggregate << x
+  linear_aggregate << x
+end
+
+puts binary_aggregate.to_s
+puts linear_aggregate.to_s
+
+** OUTPUT **
+** Binary Histogram**
+value |------------------------------------------------------------------| count
+    1 |                                                                  |     3
+    2 |                                                                  |     1
+    4 |                                                                  |     5
+    8 |                                                                  |     9
+   16 |                                                                  |    15
+   32 |                                                                  |    29
+   64 |                                                                  |    62
+  128 |                                                                  |   115
+  256 |                                                                  |   267
+  512 |@                                                                 |   523
+ 1024 |@                                                                 |   970
+ 2048 |@@@                                                               |  1987
+ 4096 |@@@@@@@@                                                          |  4075
+ 8192 |@@@@@@@@@@@@@@@@                                                  |  8108
+16384 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@                                  | 16405
+32768 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@| 32961
+      ~
+Total |------------------------------------------------------------------| 65535
+
+** Linear (0, 65536, 4096) Histogram **
+value |------------------------------------------------------------------| count
+    0 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  |  4094
+ 4096 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@|  4202
+ 8192 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  |  4118
+12288 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@   |  4059
+16384 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@    |  3999
+20480 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  |  4083
+24576 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  |  4134
+28672 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ |  4143
+32768 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ |  4152
+36864 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@   |  4033
+40960 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@   |  4064
+45056 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@   |  4012
+49152 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@   |  4070
+53248 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  |  4090
+57344 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  |  4135
+61440 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ |  4144
+Total |------------------------------------------------------------------| 65532
+
+We can see from these histograms that Ruby's rand function does a relatively good
+job of distributing returned values in the requested range.
+
+** NOTES **
+Ruby doesn't have a log2 function built into Math, so we approximate with
+log(x)/log(2). Theoretically log( 2^n - 1 )/ log(2) == n-1. Unfortunately due
+to precision limitations, once n reaches a certain size (somewhere > 32)
+this starts to return n. The larger the value of n, the more numbers i.e.
+(2^n - 2), (2^n - 3), etc fall trap to this errors. Could probably look into
+using something like BigDecimal, but for the current purposes of the binary
+histogram i.e. a simple coarse-grained view the current implementation is
+sufficient.

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/aggregate.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{aggregate}
-  s.version = "0.1.2"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Joseph Ruscio"]
-  s.date = %q{2009-08-16}
+  s.date = %q{2009-09-12}
   s.description = %q{Aggregate is a Ruby class for accumulating aggregate statistics and includes histogram support}
   s.email = %q{jruscio@gmail.com}
   s.extra_rdoc_files = [
@@ -28,7 +28,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://github.com/josephruscio/aggregate}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.3}
+  s.rubygems_version = %q{1.3.5}
   s.summary = %q{Aggregate is a Ruby class for accumulating aggregate statistics and includes histogram support}
   s.test_files = [
     "test/ts_aggregate.rb"

data/lib/aggregate.rb

@@ -5,15 +5,15 @@ class Aggregate
   #The current average of all samples
   attr_reader :mean
 
-  #The current number of samples 
+  #The current number of samples
   attr_reader :count
-  
+
   #The maximum sample value
   attr_reader :max
-  
+
   #The minimum samples value
   attr_reader :min
-  
+
   #The sum of all samples
   attr_reader :sum
 
@@ -22,7 +22,7 @@ class Aggregate
 
   #The number of samples falling above the highest valued histogram bucket
   attr_reader :outliers_high
- 
+
   # The number of buckets in the binary logarithmic histogram (low => 2**0, high => 2**@@LOG_BUCKETS)
   @@LOG_BUCKETS = 128
 
@@ -36,7 +36,9 @@ class Aggregate
     @outliers_low = 0
     @outliers_high = 0
 
-    # If the user asks we maintain a linear histogram
+    # If the user asks we maintain a linear histogram where
+    # values in the range [low, high) are bucketed in multiples
+    # of width
     if (nil != low && nil != high && nil != width)
 
       #Validate linear specification
@@ -48,6 +50,10 @@ class Aggregate
         raise ArgumentError, "Histogram width must be <= histogram range"
       end
 
+      if 0 != (high - low).modulo(width)
+	raise ArgumentError, "Histogram range (high - low) must be a multiple of width"
+      end
+
       @low = low
       @high = high
       @width = width
@@ -73,7 +79,7 @@ class Aggregate
     end
 
     # Update the running info
-    @count += 1 
+    @count += 1
     @sum += data
     @sum2 += (data * data)
 
@@ -119,6 +125,9 @@ class Aggregate
       total += count
     end
 
+    #XXX: Better to print just header --> footer
+    return "Empty histogram" if 0 == disp_buckets.length
+
     #Figure out how wide the value and count columns need to be based on their
     #largest respective numbers
     value_str = "value"
@@ -144,7 +153,7 @@ class Aggregate
 
     #Loop through each bucket to be displayed and output the correct number
     prev_index = disp_buckets[0][0] - 1
-    
+
     disp_buckets.each do |x|
       #Denote skipped empty buckets with a ~
       histogram << skip_row(value_width) unless prev_index == x[0] - 1
@@ -173,9 +182,9 @@ class Aggregate
     histogram << "| "
     histogram << sprintf("%#{count_width}d\n", total)
   end
- 
-  #Iterate through each bucket in the histogram regardless of 
-  #its contents 
+
+  #Iterate through each bucket in the histogram regardless of
+  #its contents
   def each
     @buckets.each_with_index do |count, index|
       yield(to_bucket(index), count)
@@ -200,7 +209,7 @@ class Aggregate
 
     if data < @low
       @outliers_low += 1
-    elsif data > @high
+    elsif data >= @high
       @outliers_high += 1
     else
       return false
@@ -222,7 +231,7 @@ class Aggregate
       return 2**(index)
     end
   end
-    
+
   def right_bucket? index, data
 
     # check invariant
@@ -270,8 +279,9 @@ class Aggregate
   end
 
   # log2(x) returns j, | i = j-1 and 2**i <= data < 2**j
+  @@LOG2_DIVEDEND = Math.log(2)
   def log2( x )
-   Math.log(x) / Math.log(2)
+   Math.log(x) / @@LOG2_DIVEDEND
   end
- 
+
 end

data/test/ts_aggregate.rb

@@ -73,7 +73,7 @@ class SimpleStatsTest < Test::Unit::TestCase
 =end
 
   #XXX: Update test_bucket_contents() if you muck with @@DATA
-  @@DATA = [ 1, 5, 4, 6, 1028, 1972, 16384, 16385, 16383 ]
+  @@DATA = [ 1, 5, 4, 6, 1028, 1972, 16384, 16385, 16383]
   def test_bucket_contents
     #XXX: This is the only test so far that cares about the actual contents
     # of @@DATA, so if you update that array ... update this method too
@@ -83,7 +83,7 @@ class SimpleStatsTest < Test::Unit::TestCase
     i = 0
     @stats.each_nonzero do |bucket, count|
       assert_equal expected_buckets[i], bucket
-      assert_equal expected_counts[i],  count 
+      assert_equal expected_counts[i],  count
       # Increment for the next test
       i += 1
     end
@@ -96,12 +96,19 @@ class SimpleStatsTest < Test::Unit::TestCase
   def test_outlier
     assert_equal 0, @stats.outliers_low
     assert_equal 0, @stats.outliers_high
-    
+
     @stats << -1
     @stats << -2
-    @stats << 2**129
+    @stats << 0
+
+    @stats << 2**128
 
-    assert_equal 2, @stats.outliers_low
+    # This should be the last value in the last bucket, but Ruby's native
+    # floats are not precise enough. Somewhere past 2^32 the log(x)/log(2)
+    # breaks down. So it shows up as 128 (outlier) instead of 127
+    #@stats << (2**128) - 1
+
+    assert_equal 3, @stats.outliers_low
     assert_equal 1, @stats.outliers_high
   end
 
@@ -120,23 +127,33 @@ class LinearHistogramTest < Test::Unit::TestCase
   end
 
   def test_validation
+
+    # Range cannot be 0
     assert_raise(ArgumentError) {bad_stats = Aggregate.new(32,32,4)}
+
+    # Range cannot be negative
     assert_raise(ArgumentError) {bad_stats = Aggregate.new(32,16,4)}
+
+    # Range cannot be < single bucket
     assert_raise(ArgumentError) {bad_stats = Aggregate.new(16,32,17)}
+
+    # Range % width must equal 0 (for now)
+    assert_raise(ArgumentError) {bad_stats = Aggregate.new(1,16384,1024)}
   end
 
   #XXX: Update test_bucket_contents() if you muck with @@DATA
-  @@DATA = [ 1, 5, 4, 6, 1028, 1972, 16384, 16385, 16383 ]
+  # 32768 is an outlier
+  @@DATA = [ 0, 1, 5, 4, 6, 1028, 1972, 16384, 16385, 16383, 32768]
   def test_bucket_contents
     #XXX: This is the only test so far that cares about the actual contents
     # of @@DATA, so if you update that array ... update this method too
     expected_buckets  = [0, 1024,  15360, 16384]
-    expected_counts =   [4, 2,     1,     2]
+    expected_counts =   [5, 2,     1,     2]
 
     i = 0
     @stats.each_nonzero do |bucket, count|
       assert_equal expected_buckets[i], bucket
-      assert_equal expected_counts[i],  count 
+      assert_equal expected_counts[i],  count
       # Increment for the next test
       i += 1
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: aggregate
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors: 
 - Joseph Ruscio
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-16 00:00:00 -07:00
+date: 2009-09-12 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -54,7 +54,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.3
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: Aggregate is a Ruby class for accumulating aggregate statistics and includes histogram support