tabs 0.7.1 → 0.8.0

data/README.md

@@ -9,7 +9,7 @@ averages, and min/max, and task based stats sliceable by the minute, hour, day,
 
 Add this line to your application's Gemfile:
 
-    gem 'tabs', '~> 0.7.0'
+    gem 'tabs'
 
 And then execute:
 
@@ -19,14 +19,6 @@ Or install it yourself as:
 
     $ gem install tabs
 
-## Breaking Changes in v0.6.0
-
-Please note that when the library version went from v0.5.6 to v0.6.0 some of
-the key patterns used to store metrics in Redis were changed.  If you upgrade
-an app to v0.6.0 the previous set of data will not be picked up by tabs.
-Please use v0.6.x on new applications only.  However, the 'Task' metric
-type will only be available in v0.6.0 and above.
-
 ## Usage
 
 Metrics come in three flavors: counters, values, and tasks.
@@ -61,29 +53,49 @@ To retrieve the counts for a given time period just call `Tabs#get_stats` with t
 Tabs.get_stats("website-visits", 10.days.ago..Time.now, :hour)
 ```
     
-This will return stats for the last 10 days by hour as an array of hashes in which the keys are an instance of `Time` and the value is the count for that time.
-
-```ruby
-[
-  { 2000-01-01 00:00:00 UTC => 1 },
-  { 2000-01-01 01:00:00 UTC => 0 },
-  { 2000-01-01 02:00:00 UTC => 10 },
-  { 2000-01-01 03:00:00 UTC => 1 },
-  { 2000-01-01 04:00:00 UTC => 0 },
-  { 2000-01-01 05:00:00 UTC => 0 },
-  { 2000-01-01 06:00:00 UTC => 3 },
-  { 2000-01-01 07:00:00 UTC => 0 },
+This will return stats for the last 10 days by hour in the form of a `Tabs::Metrics::Counter::Stats` object.  This object is enumerable so you can iterate through the results like so:
+
+```ruby
+results = Tabs.get_stats("website-visits", 10.days.ago..Time.now, :hour)
+results.each { |r| puts r }
+
+#=>
+  { timestamp: 2000-01-01 00:00:00 UTC, count: 1 }
+  { timestamp: 2000-01-01 01:00:00 UTC, count: 0 }
+  { timestamp: 2000-01-01 02:00:00 UTC, count: 10 }
+  { timestamp: 2000-01-01 03:00:00 UTC, count: 1 }
+  { timestamp: 2000-01-01 04:00:00 UTC, count: 0 }
+  { timestamp: 2000-01-01 05:00:00 UTC, count: 0 }
+  { timestamp: 2000-01-01 06:00:00 UTC, count: 3 }
+  { timestamp: 2000-01-01 07:00:00 UTC, count: 0 }
   ...
-]
+```
+
+The results object also provides the following methods:
+
+```ruby
+results.total       #=> The count total for the given period
+results.min         #=> The min count for any timestamp in the period
+results.max         #=> The max count for any timestamp in the period
+results.avg         #=> The avg count for timestamps in the period
+results.period      #=> The timestamp range that was requested
+results.resolution  #=> The resolution requested
 ```
     
-Times for the given period in which no events occurred will be "filled in" with a zero value to make visualizations easier.
+Timestamps for the given period in which no events occurred will be "filled in" with a count value to make visualizations easier.
+
+The timestamps are also normalized.  For example, in hour resolution, the minutes and seconds of the timestamps are set to 00:00.  Likewise for the week resolution, the day is set to the first day of the week.
 
-The `Time` keys are also normalized.  For example, in hour resolution, the minutes and seconds of the `Time` object are set to 00:00.  Likewise for the week resolution, the day is set to the first day of the week.
+Lastly, you can access the overall total for a counter (for all time)
+using the `counter_total` method.
+
+```ruby
+Tabs.counter_total("website-visits") #=> 476873
+```
 
 ### Value Metrics
 
-Value metrics take a value and record the min, max, avg, and sum for a given time resolution.  Creating a value metric is easy:
+Value metrics record a value at a point in time and calculate the min, max, avg, and sum for a given time resolution.  Creating a value metric is easy:
 
 To record a value, simply call `Tabs#record_value`.
 
@@ -111,15 +123,30 @@ Retrieving the stats for a value metric is just like retrieving a counter metric
 Tabs.get_stats("new-user-age", 6.months.ago..Time.now, :month)
 ```
     
-This will return a familiar value, but with an expanded set of values.
+This will return a `Tabs::Metrics::Value::Stats` object.  Again, this
+object is enumerable and encapsulates all the timestamps within the
+given period.
 
 ```ruby
-[
-  { 2000-01-01 00:00:00 UTC => { count: 9, min: 19, max: 54, sum: 226, avg: 38 } },
-  { 2000-02-01 01:00:00 UTC => { count: 0, min: 0, max: 0, sum: 0, avg: 0 } },
-  { 2000-03-01 02:00:00 UTC => { count: 2, min: 22, max: 34, sum: 180, avg: 26 } },
+results = Tabs.get_stats("new-user-age", 6.months.ago..Time.now, :month)
+results.each { |r| puts r }
+#=>
+  { timestamp: 2000-01-01 00:00:00, count: 9, min: 19, max: 54, sum: 226, avg: 38 }
+  { timestamp: 2000-02-01 01:00:00, count: 0, min: 0, max: 0, sum: 0, avg: 0 }
+  { timestamp: 2000-03-01 02:00:00, count: 2, min: 22, max: 34, sum: 180, avg: 26 }
   ...
-]
+```
+
+The results object also provides some aggregates and other methods:
+
+```ruby
+results.count       #=> The total count of recorded values for the period
+results.sum         #=> The sum of all values for the period
+results.min         #=> The min value for any timestamp in the period
+results.max         #=> The max value for any timestamp in the period
+results.avg         #=> The avg value for timestamps in the period
+results.period      #=> The timestamp range that was requested
+results.resolution  #=> The resolution requested
 ```
 
 ### Task Metrics
@@ -155,16 +182,15 @@ Retrieving stats for a task metric is just like the other types:
 Tabs.get_stats("mobile-to-purchase", 6.hours.ago..Time.now, :minute)
 ```
 
-This will return a hash like this:
+This will return a `Tabs::Metrics::Task::Stats` object:
 
 ```ruby
-{
-  started: 3,                     #=> number of items started within the period
-  completed: 2,                   #=> number of items completed within the period
-  completed_within_period: 2,     #=> number started AND completed within the period
-  completion_rate: 0.18,          #=> rate of completion in the specified resolution (e.g. :minute)
-  average_completion_time: 1.5    #=> average completion time in the specified resolution
-}
+results = Tabs.get_stats("mobile-to-purchase", 6.hours.ago..Time.now, :minute)
+results.started_within_period       #=> Number of items started in period
+results.completed_within_period     #=> Number of items completed in period
+results.started_and_completed_within_period  #=> Items wholly started/completed in period
+results.completion_rate             #=> Rate of completion in the given resolution
+results.average_completion_time     #=> Average time for the task to be completed
 ```
 
 ### Resolutions
@@ -201,11 +227,17 @@ Tabs.metric_exists?("foobar") #=> false
 To drop a metric, just call `Tabs#drop_metric`
 
 ```ruby
-Tabs.drop_metric("website-visits")
+Tabs.drop_metric!("website-visits")
 ```
     
 This will drop all recorded values for the metric so it may not be un-done...be careful.
 
+Even more dangerous, you can drop all metrics...be very careful.
+
+```ruby
+Tabs.drop_all_metrics!
+```
+
 ### Configuration
 
 There really isn’t much to configure with Tabs, it just works out of the box.  You can use the following configure block to set the Redis connection instance that Tabs will use.
@@ -222,6 +254,24 @@ Tabs.configure do |config|
 end
 ```
 
+## Breaking Changes
+
+### Breaking Changes in v0.6.0
+
+Please note that when the library version went from v0.5.6 to v0.6.0 some of
+the key patterns used to store metrics in Redis were changed.  If you upgrade
+an app to v0.6.0 the previous set of data will not be picked up by tabs.
+Please use v0.6.x on new applications only.  However, the 'Task' metric
+type will only be available in v0.6.0 and above.
+
+### Breaking Changes in v0.8.0
+
+In version 0.8.0 and higher the get_stats method returns a more robust
+object instead of just an array of hashes.  These stats objects are
+enumerable and most existing code utilizing tabs should continue to
+function.  However, please review the docs for more information if you
+encounter issues when upgrading.
+
 ## Contributing
 
 1. Fork it

data/lib/tabs.rb

@@ -15,9 +15,11 @@ require "tabs/resolutions/week"
 require "tabs/resolutions/month"
 require "tabs/resolutions/year"
 
+require "tabs/metrics/counter/stats"
 require "tabs/metrics/counter"
+require "tabs/metrics/value/stats"
 require "tabs/metrics/value"
-require "tabs/metrics/task"
 require "tabs/metrics/task/token"
+require "tabs/metrics/task"
 
 require "tabs/tabs"

data/lib/tabs/helpers.rb

@@ -14,23 +14,11 @@ module Tabs
     end
 
     def normalize_period(period, resolution)
-      period_start = Tabs::Resolution.normalize(resolution, period.first)
-      period_end = Tabs::Resolution.normalize(resolution, period.last)
+      period_start = Tabs::Resolution.normalize(resolution, period.first.utc)
+      period_end = Tabs::Resolution.normalize(resolution, period.last.utc)
       (period_start..period_end)
     end
 
-    def extract_date_from_key(stat_key, resolution)
-      date_str = stat_key.split(":").last
-      Tabs::Resolution.deserialize(resolution, date_str)
-    end
-
-    def fill_missing_dates(period, date_value_pairs, resolution, default_value=0)
-      all_timestamps = timestamp_range(period, resolution)
-      default_value_timestamps = Hash[all_timestamps.map { |t| [t, default_value] }]
-      merged = default_value_timestamps.merge(Hash[date_value_pairs])
-      merged.to_a
-    end
-
     def round_float(f)
       (f*100).round / 100.0
     end

data/lib/tabs/metrics/counter.rb

@@ -20,14 +20,19 @@ module Tabs
       end
 
       def stats(period, resolution)
-        period = normalize_period(period, resolution)
-        keys = smembers("stat:counter:#{key}:keys:#{resolution}")
-        dates = keys.map { |k| extract_date_from_key(k, resolution) }
-        values = mget(*keys).map(&:to_i)
-        pairs = dates.zip(values)
-        filtered_pairs = pairs.find_all { |p| period.cover?(p[0]) }
-        filtered_pairs = fill_missing_dates(period, filtered_pairs, resolution)
-        filtered_pairs.map { |p| Hash[[p]] }
+        timestamps = timestamp_range period, resolution
+        keys = timestamps.map do |ts|
+          "stat:counter:#{key}:count:#{Tabs::Resolution.serialize(resolution, ts)}"
+        end
+
+        values = mget(*keys).map do |v|
+          {
+            "timestamp" => timestamps.shift,
+            "count" => (v || 0).to_i
+          }.with_indifferent_access
+        end
+
+        Stats.new(period, resolution, values)
       end
 
       def total
@@ -43,7 +48,6 @@ module Tabs
       def increment_resolution(resolution, timestamp)
         formatted_time = Tabs::Resolution.serialize(resolution, timestamp)
         stat_key = "stat:counter:#{key}:count:#{formatted_time}"
-        sadd("stat:counter:#{key}:keys:#{resolution}", stat_key)
         incr(stat_key)
       end
 

data/lib/tabs/metrics/counter/stats.rb

@@ -0,0 +1,50 @@
+module Tabs
+  module Metrics
+    class Counter
+      class Stats
+
+        include Enumerable
+        include Helpers
+
+        attr_reader :period, :resolution, :values
+
+        def initialize(period, resolution, values)
+          @period, @resolution, @values = period, resolution, values
+        end
+
+        def first
+          values.first
+        end
+
+        def last
+          values.last
+        end
+
+        def total
+          @total ||= values.map { |v| v["count"] }.sum
+        end
+
+        def min
+          @min ||= values.min_by { |v| v["count"] }["count"]
+        end
+
+        def max
+          @max ||= values.max_by { |v| v["count"] }["count"]
+        end
+
+        def avg
+          round_float(self.total.to_f / values.size.to_f)
+        end
+
+        def each(&block)
+          values.each(&block)
+        end
+
+        def to_a
+          values
+        end
+
+      end
+    end
+  end
+end

data/lib/tabs/metrics/task.rb

@@ -6,6 +6,14 @@ module Tabs
 
       class UnstartedTaskMetricError < Exception; end
 
+      Stats = Struct.new(
+        :started_within_period,
+        :completed_within_period,
+        :started_and_completed_within_period,
+        :completion_rate,
+        :average_completion_time
+      )
+
       attr_reader :key
 
       def initialize(key)
@@ -30,13 +38,13 @@ module Tabs
         completion_rate = round_float(matching_tokens.size.to_f / range.size)
         elapsed_times = matching_tokens.map { |t| t.time_elapsed(resolution) }
         average_completion_time = (elapsed_times.inject(&:+)) / matching_tokens.size
-        {
-          started: started_tokens.size,
-          completed: completed_tokens.size,
-          completed_within_period: matching_tokens.size,
-          completion_rate: completion_rate,
-          average_completion_time: average_completion_time
-        }
+        Stats.new(
+          started_tokens.size,
+          completed_tokens.size,
+          matching_tokens.size,
+          completion_rate,
+          average_completion_time
+        )
       end
 
       def drop!

data/lib/tabs/metrics/value.rb

@@ -15,21 +15,24 @@ module Tabs
         Tabs::RESOLUTIONS.each do |resolution|
           formatted_time = Tabs::Resolution.serialize(resolution, timestamp)
           stat_key = "stat:value:#{key}:data:#{formatted_time}"
-          sadd("stat:value:#{key}:keys:#{resolution}", stat_key)
           update_values(stat_key, value)
         end
         true
       end
 
       def stats(period, resolution)
-        period = normalize_period(period, resolution)
-        keys = smembers("stat:value:#{key}:keys:#{resolution}")
-        dates = keys.map { |k| extract_date_from_key(k, resolution) }
-        values = mget(*keys).map { |v| JSON.parse(v) }
-        pairs = dates.zip(values)
-        filtered_pairs = pairs.find_all { |p| period.cover?(p[0]) }
-        filtered_pairs = fill_missing_dates(period, filtered_pairs, resolution, default_value(0))
-        filtered_pairs.map { |p| Hash[[p]] }
+        timestamps = timestamp_range period, resolution
+        keys = timestamps.map do |ts|
+          "stat:value:#{key}:data:#{Tabs::Resolution.serialize(resolution, ts)}"
+        end
+
+        values = mget(*keys).map do |v|
+          value = v.nil? ? default_value(0) : JSON.parse(v)
+          value["timestamp"] = timestamps.shift
+          value.with_indifferent_access
+        end
+
+        Stats.new(period, resolution, values)
       end
 
       def drop!

data/lib/tabs/metrics/value/stats.rb

@@ -0,0 +1,54 @@
+module Tabs
+  module Metrics
+    class Value
+      class Stats
+
+        include Enumerable
+        include Helpers
+
+        attr_reader :period, :resolution, :values
+
+        def initialize(period, resolution, values)
+          @period, @resolution, @values = period, resolution, values
+        end
+
+        def first
+          values.first
+        end
+
+        def last
+          values.last
+        end
+
+        def count
+          @count ||= values.map { |v| v["count"] }.sum
+        end
+
+        def sum
+          @sum ||= values.map { |v| v["sum"] }.sum
+        end
+
+        def min
+          @min ||= values.min_by { |v| v["min"] }["min"]
+        end
+
+        def max
+          @max ||= values.max_by { |v| v["max"] }["max"]
+        end
+
+        def avg
+          round_float(self.sum.to_f / self.count.to_f)
+        end
+
+        def each(&block)
+          values.each(&block)
+        end
+
+        def to_a
+          values
+        end
+
+      end
+    end
+  end
+end

data/lib/tabs/tabs.rb

@@ -59,7 +59,7 @@ module Tabs
     metric_klass(type).new(key)
   end
 
-  def counter_total(key, period=nil)
+  def counter_total(key)
     raise UnknownMetricError.new("Unknown metric: #{key}") unless metric_exists?(key)
     raise MetricTypeMismatchError.new("Only counter metrics can be incremented") unless metric_type(key) == "counter"
     get_metric(key).total
@@ -84,13 +84,18 @@ module Tabs
     list_metrics.include? key
   end
 
-  def drop_metric(key)
+  def drop_metric!(key)
     raise UnknownMetricError.new("Unknown metric: #{key}") unless metric_exists?(key)
     metric = get_metric(key)
     metric.drop!
     hdel "metrics", key
   end
 
+  def drop_all_metrics!
+    metrics = self.list_metrics
+    metrics.each { |key| self.drop_metric! key }
+  end
+
   private
 
   def metric_klass(type)

data/lib/tabs/version.rb

@@ -1,3 +1,3 @@
 module Tabs
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

data/spec/lib/tabs/metrics/counter/stats_spec.rb

@@ -0,0 +1,37 @@
+require "spec_helper"
+
+describe Tabs::Metrics::Counter::Stats do
+
+  let(:period) { (Time.now - 2.days..Time.now) }
+  let(:resolution) { :hour }
+  let(:values) do
+    [
+      { "timestamp" => Time.now - 30.hours, "count" => 44 },
+      { "timestamp" => Time.now - 20.hours, "count" => 123 },
+      { "timestamp" => Time.now - 10.hours, "count" => 92 }
+    ]
+  end
+  let(:stats) { Tabs::Metrics::Counter::Stats.new(period, resolution, values) }
+
+  it "is enumerable" do
+    expect(stats).to respond_to :each
+    expect(Tabs::Metrics::Counter::Stats.ancestors).to include Enumerable
+  end
+
+  it "#total returns the total count for the entire set" do
+    expect(stats.total).to eq 259
+  end
+
+  it "min returns the min for the entire set" do
+    expect(stats.min).to eq 44
+  end
+
+  it "max returns the max for the entire set" do
+    expect(stats.max).to eq 123
+  end
+
+  it "avg returns the average for the entire set" do
+    expect(stats.avg).to eq 86.33
+  end
+
+end

data/spec/lib/tabs/metrics/counter_spec.rb

@@ -15,14 +15,14 @@ describe Tabs::Metrics::Counter do
       metric.increment
       time = Time.utc(now.year, now.month, now.day, now.hour)
       stats = metric.stats(((now - 2.hours)..(now + 4.hours)), :hour)
-      expect(stats).to include({ time => 1 })
+      expect(stats).to include({ "timestamp" => time, "count" => 1 })
     end
 
     it "applys the increment to the specified timestamp if one is supplied" do
       time = Time.utc(now.year, now.month, now.day, now.hour) - 2.hours
       metric.increment(time)
       stats = metric.stats(((now - 3.hours)..now), :hour)
-      expect(stats).to include({ time => 1 })
+      expect(stats).to include({ "timestamp" => time, "count" => 1 })
     end
 
   end
@@ -59,42 +59,42 @@ describe Tabs::Metrics::Counter do
     it "returns the expected results for an minutely metric" do
       create_span(:minute)
       stats = metric.stats(now..(now + 7.minutes), :minute)
-      expect(stats).to include({ (now + 3.minutes) => 1 })
-      expect(stats).to include({ (now + 6.minutes) => 2 })
+      expect(stats).to include({ "timestamp" => (now + 3.minutes), "count" => 1 })
+      expect(stats).to include({ "timestamp" => (now + 6.minutes), "count" => 2 })
     end
 
     it "returns the expected results for an hourly metric" do
       create_span(:hours)
       stats = metric.stats(now..(now + 7.hours), :hour)
-      expect(stats).to include({ (now + 3.hours) => 1 })
-      expect(stats).to include({ (now + 6.hours) => 2 })
+      expect(stats).to include({ "timestamp" => (now + 3.hours), "count" => 1 })
+      expect(stats).to include({ "timestamp" => (now + 6.hours), "count" => 2 })
     end
 
     it "returns the expected results for a daily metric" do
       create_span(:days)
       stats = metric.stats(now..(now + 7.days), :day)
-      expect(stats).to include({ (now + 3.days) => 1 })
-      expect(stats).to include({ (now + 6.days) => 2 })
+      expect(stats).to include({ "timestamp" => (now + 3.days), "count" => 1 })
+      expect(stats).to include({ "timestamp" => (now + 6.days), "count" => 2 })
     end
 
     it "returns the expected results for a monthly metric" do
       create_span(:months)
       stats = metric.stats(now..(now + 7.months), :month)
-      expect(stats).to include({ (now + 3.months) => 1 })
-      expect(stats).to include({ (now + 6.months) => 2 })
+      expect(stats).to include({ "timestamp" => (now + 3.months), "count" => 1 })
+      expect(stats).to include({ "timestamp" => (now + 6.months), "count" => 2 })
     end
 
     it "returns the expected results for a yearly metric" do
       create_span(:years)
       stats = metric.stats(now..(now + 7.years), :year)
-      expect(stats).to include({ (now + 3.years) => 1 })
-      expect(stats).to include({ (now + 6.years) => 2 })
+      expect(stats).to include({ "timestamp" => (now + 3.years), "count" => 1 })
+      expect(stats).to include({ "timestamp" => (now + 6.years), "count" => 2 })
     end
 
     it "returns zeros for time periods which do not have any events" do
       create_span(:days)
       stats = metric.stats(now..(now + 7.days), :day)
-      expect(stats).to include({ (now + 1.day) => 0 })
+      expect(stats).to include({ "timestamp" => (now + 1.day), "count" => 0 })
     end
 
     context "for weekly metrics" do
@@ -106,15 +106,15 @@ describe Tabs::Metrics::Counter do
       it "returns the expected results for a weekly metric" do
         create_span(:weeks)
         stats = metric.stats(period, :week)
-        expect(stats).to include({ (now + 3.weeks).beginning_of_week => 1 })
-        expect(stats).to include({ (now + 6.weeks).beginning_of_week => 2 })
+        expect(stats).to include({ "timestamp" => (now + 3.weeks).beginning_of_week, "count" => 1 })
+        expect(stats).to include({ "timestamp" => (now + 6.weeks).beginning_of_week, "count" => 2 })
       end
 
       it "normalizes the period to the first day of the week" do
         create_span(:weeks)
         stats = metric.stats(period, :week)
-        expect(stats.first.keys[0]).to eq(period.first.beginning_of_week)
-        expect(stats.last.keys[0]).to eq(period.last.beginning_of_week)
+        expect(stats.first["timestamp"]).to eq(period.first.beginning_of_week)
+        expect(stats.last["timestamp"]).to eq(period.last.beginning_of_week)
       end
 
     end

data/spec/lib/tabs/metrics/value/stats_spec.rb

@@ -0,0 +1,41 @@
+require "spec_helper"
+
+describe Tabs::Metrics::Value::Stats do
+
+  let(:period) { (Time.now - 2.days..Time.now) }
+  let(:resolution) { :hour }
+  let(:values) do
+    [
+      { "timestamp" => Time.now - 30.hours, "count" => 10, "sum" => 145, "min" => 11, "max" => 204, "avg" => 14.5 },
+      { "timestamp" => Time.now - 20.hours, "count" => 15, "sum" => 288, "min" => 10, "max" => 199, "avg" => 19.2 },
+      { "timestamp" => Time.now - 10.hours, "count" => 25, "sum" => 405, "min" => 12, "max" => 210, "avg" => 16.2 }
+    ]
+  end
+  let(:stats) { Tabs::Metrics::Value::Stats.new(period, resolution, values) }
+
+  it "is enumerable" do
+    expect(stats).to respond_to :each
+    expect(Tabs::Metrics::Value::Stats.ancestors).to include Enumerable
+  end
+
+  it "#count returns the total count for the entire set" do
+    expect(stats.count).to eq 50
+  end
+
+  it "sum returns the sum for the entire set" do
+    expect(stats.sum).to eq 838
+  end
+
+  it "min returns the min for the entire set" do
+    expect(stats.min).to eq 10
+  end
+
+  it "max returns the max for the entire set" do
+    expect(stats.max).to eq 210
+  end
+
+  it "avg returns the average for the entire set" do
+    expect(stats.avg).to eq 16.76
+  end
+
+end

data/spec/lib/tabs/metrics/value_spec.rb

@@ -16,14 +16,14 @@ describe Tabs::Metrics::Value do
       metric.record(42)
       time = Time.utc(now.year, now.month, now.day, now.hour)
       stats = metric.stats(((now - 2.hours)..(now + 4.hours)), :hour)
-      expect(stats).to include({ time => {"count"=>2, "min"=>17, "max"=>42, "sum"=>59, "avg"=>29} })
+      expect(stats).to include({ "timestamp"=>time, "count"=>2, "min"=>17, "max"=>42, "sum"=>59, "avg"=>29})
     end
 
     it "applys the value to the specified timestamp if one is supplied" do
       time = Time.utc(now.year, now.month, now.day, now.hour) - 2.hours
       metric.record(42, time)
       stats = metric.stats(((now - 3.hours)..now), :hour)
-      expect(stats).to include({ time => {"count"=>1, "min"=>42, "max"=>42, "sum"=>42, "avg"=>42} })
+      expect(stats).to include({ "timestamp"=>time, "count"=>1, "min"=>42, "max"=>42, "sum"=>42, "avg"=>42})
     end
 
   end
@@ -48,46 +48,52 @@ describe Tabs::Metrics::Value do
       Timecop.freeze(now)
     end
 
+    it "returns an instance of Tabs::Metrics::Value::Stats" do
+      create_span(:minutes)
+      stats = metric.stats(now..(now + 7.minutes), :minute)
+      expect(stats).to be_a_kind_of Tabs::Metrics::Value::Stats
+    end
+
     it "returns the expected results for an minutely metric" do
       create_span(:minutes)
       stats = metric.stats(now..(now + 7.minutes), :minute)
-      expect(stats).to include({ (now + 3.minutes) => {"count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10} })
-      expect(stats).to include({ (now + 6.minutes) => {"count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17} })
+      expect(stats).to include({ "timestamp" => (now + 3.minutes), "count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10})
+      expect(stats).to include({ "timestamp" => (now + 6.minutes), "count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17})
     end
 
     it "returns the expected results for an hourly metric" do
       create_span(:hours)
       stats = metric.stats(now..(now + 7.hours), :hour)
-      expect(stats).to include({ (now + 3.hours) => {"count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10} })
-      expect(stats).to include({ (now + 6.hours) => {"count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17} })
+      expect(stats).to include({ "timestamp" => (now + 3.hours), "count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10})
+      expect(stats).to include({ "timestamp" => (now + 6.hours), "count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17})
     end
 
     it "returns the expected results for a daily metric" do
       create_span(:days)
       stats = metric.stats(now..(now + 7.days), :day)
-      expect(stats).to include({ (now + 3.days) => {"count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10} })
-      expect(stats).to include({ (now + 6.days) => {"count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17} })
+      expect(stats).to include({ "timestamp" => (now + 3.days), "count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10})
+      expect(stats).to include({ "timestamp" => (now + 6.days), "count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17})
     end
 
     it "returns the expected results for a weekly metric" do
       create_span(:weeks)
       stats = metric.stats(now..(now + 7.weeks), :week)
-      expect(stats).to include({ (now + 3.weeks).beginning_of_week => {"count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10} })
-      expect(stats).to include({ (now + 6.weeks).beginning_of_week => {"count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17} })
+      expect(stats).to include({ "timestamp" => (now + 3.weeks).beginning_of_week, "count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10})
+      expect(stats).to include({ "timestamp" => (now + 6.weeks).beginning_of_week, "count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17})
     end
 
     it "returns the expected results for a monthly metric" do
       create_span(:months)
       stats = metric.stats(now..(now + 7.months), :month)
-      expect(stats).to include({ (now + 3.months) => {"count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10} })
-      expect(stats).to include({ (now + 6.months) => {"count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17} })
+      expect(stats).to include({ "timestamp" => (now + 3.months), "count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10})
+      expect(stats).to include({ "timestamp" => (now + 6.months), "count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17})
     end
 
     it "returns the expected results for a yearly metric" do
       create_span(:years)
       stats = metric.stats(now..(now + 7.years), :year)
-      expect(stats).to include({ (now + 3.years) => {"count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10} })
-      expect(stats).to include({ (now + 6.years) => {"count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17} })
+      expect(stats).to include({ "timestamp" => (now + 3.years), "count"=>1, "min"=>10, "max"=>10, "sum"=>10, "avg"=>10})
+      expect(stats).to include({ "timestamp" => (now + 6.years), "count"=>2, "min"=>15, "max"=>20, "sum"=>35, "avg"=>17})
     end
 
   end

data/spec/lib/tabs/task_spec.rb

@@ -63,15 +63,11 @@ describe Tabs::Metrics::Task do
       Timecop.freeze(now + 3.minutes)
       metric.complete(token_3)
       stats = metric.stats((now - 5.minutes)..(now + 5.minutes), :minute)
-      expect(stats).to eq(
-        {
-          started: 3,
-          completed: 2,
-          completed_within_period: 2,
-          completion_rate: 0.18,
-          average_completion_time: 1.5
-        }
-      )
+      expect(stats.started_within_period).to eq 3
+      expect(stats.completed_within_period).to eq 2
+      expect(stats.started_and_completed_within_period).to eq 2
+      expect(stats.completion_rate).to eq 0.18
+      expect(stats.average_completion_time).to eq 1.5
     end
 
   end

data/spec/lib/tabs_spec.rb

@@ -3,7 +3,7 @@ require "spec_helper"
 describe Tabs do
   include Tabs::Storage
 
-  describe "#create_metric" do
+  describe ".create_metric" do
 
     it "raises an error if the type is invalid" do
       lambda { Tabs.create_metric("foo", "foobar") }.should raise_error(Tabs::UnknownTypeError)
@@ -33,7 +33,7 @@ describe Tabs do
 
   end
 
-  describe "#get_metric" do
+  describe ".get_metric" do
 
     it "returns the expected metric object" do
       Tabs.create_metric("foo", "counter")
@@ -42,7 +42,7 @@ describe Tabs do
 
   end
 
-  describe "#list_metrics" do
+  describe ".list_metrics" do
 
     it "returns the list_metrics of metric names" do
       Tabs.create_metric("foo", "counter")
@@ -52,7 +52,7 @@ describe Tabs do
 
   end
 
-  describe "#metric_exists?" do
+  describe ".metric_exists?" do
 
     it "returns true if the metric exists" do
       Tabs.create_metric("foo", "counter")
@@ -65,19 +65,19 @@ describe Tabs do
 
   end
 
-  describe "#drop_metric" do
+  describe ".drop_metric" do
 
     before do
       Tabs.create_metric("foo", "counter")
     end
 
     it "removes the metric from the list_metrics" do
-      Tabs.drop_metric("foo")
+      Tabs.drop_metric!("foo")
       expect(Tabs.list_metrics).to_not include("foo")
     end
 
     it "results in metric_exists? returning false" do
-      Tabs.drop_metric("foo")
+      Tabs.drop_metric!("foo")
       expect(Tabs.metric_exists?("foo")).to be_false
     end
 
@@ -85,12 +85,24 @@ describe Tabs do
       metric = stub(:metric)
       Tabs.stub(get_metric: metric)
       metric.should_receive(:drop!)
-      Tabs.drop_metric("foo")
+      Tabs.drop_metric!("foo")
     end
 
   end
 
-  describe "#increment_counter" do
+  describe ".drop_all_metrics" do
+
+    it "drops all metrics" do
+      Tabs.create_metric("foo", "counter")
+      Tabs.create_metric("bar", "value")
+      Tabs.drop_all_metrics!
+      expect(Tabs.metric_exists?("foo")).to be_false
+      expect(Tabs.metric_exists?("bar")).to be_false
+    end
+
+  end
+
+  describe ".increment_counter" do
 
     it "raises a Tabs::MetricTypeMismatchError if the metric is the wrong type" do
       Tabs.create_metric("foo", "value")
@@ -112,7 +124,7 @@ describe Tabs do
 
   end
 
-  describe "#record_value" do
+  describe ".record_value" do
 
     it "creates the metric if it doesn't exist" do
       expect(Tabs.metric_exists?("foo")).to be_false
@@ -134,7 +146,7 @@ describe Tabs do
 
   end
 
-  describe "#list_metrics" do
+  describe ".list_metrics" do
 
     it "lists all metrics that are defined" do
       Tabs.create_metric("foo", "counter")
@@ -145,7 +157,7 @@ describe Tabs do
 
   end
 
-  describe "#metric_type" do
+  describe ".metric_type" do
 
     it "returns the type of a counter metric" do
       Tabs.create_metric("foo", "counter")

data/tabs.gemspec

@@ -18,12 +18,14 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.post_install_message = <<TXT
-**** NOTICE ****
-Please note there are breaking changes in this version of tabs!
-Existing data cannot be read because of changes to the redis key patterns.
-Please continue to use version 0.5.6 if you need to access existing metric data."
-TXT
+  gem.post_install_message = <<EOS
+Tabs v0.8.0 - BREAKING CHANGES:
+The get_stats method now returns a more robust object instead of just
+an array of hashes.  Existing data will continue to work (no changes were
+made to the underlying Redis keys).  However, application code using
+tabs may need to be changed.  Please review the README after installing
+v0.8.0 or higher.
+EOS
 
   gem.add_dependency "activesupport", ">= 3.2"
   gem.add_dependency "json", ">= 1.7"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tabs
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-17 00:00:00.000000000 Z
+date: 2013-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -158,9 +158,11 @@ files:
 - lib/tabs/config.rb
 - lib/tabs/helpers.rb
 - lib/tabs/metrics/counter.rb
+- lib/tabs/metrics/counter/stats.rb
 - lib/tabs/metrics/task.rb
 - lib/tabs/metrics/task/token.rb
 - lib/tabs/metrics/value.rb
+- lib/tabs/metrics/value/stats.rb
 - lib/tabs/resolution.rb
 - lib/tabs/resolutions/day.rb
 - lib/tabs/resolutions/hour.rb
@@ -171,8 +173,10 @@ files:
 - lib/tabs/storage.rb
 - lib/tabs/tabs.rb
 - lib/tabs/version.rb
+- spec/lib/tabs/metrics/counter/stats_spec.rb
 - spec/lib/tabs/metrics/counter_spec.rb
 - spec/lib/tabs/metrics/task/token_spec.rb
+- spec/lib/tabs/metrics/value/stats_spec.rb
 - spec/lib/tabs/metrics/value_spec.rb
 - spec/lib/tabs/task_spec.rb
 - spec/lib/tabs_spec.rb
@@ -180,13 +184,17 @@ files:
 - tabs.gemspec
 homepage: https://github.com/thegrubbsian/tabs
 licenses: []
-post_install_message: ! '**** NOTICE ****
+post_install_message: ! 'Tabs v0.8.0 - BREAKING CHANGES:
 
-  Please note there are breaking changes in this version of tabs!
+  The get_stats method now returns a more robust object instead of just
 
-  Existing data cannot be read because of changes to the redis key patterns.
+  an array of hashes.  Existing data will continue to work (no changes were
 
-  Please continue to use version 0.5.6 if you need to access existing metric data."
+  made to the underlying Redis keys).  However, application code using
+
+  tabs may need to be changed.  Please review the README after installing
+
+  v0.8.0 or higher.
 
 '
 rdoc_options: []
@@ -211,8 +219,10 @@ signing_key:
 specification_version: 3
 summary: A redis-backed metrics tracker for keeping tabs on pretty much anything ;)
 test_files:
+- spec/lib/tabs/metrics/counter/stats_spec.rb
 - spec/lib/tabs/metrics/counter_spec.rb
 - spec/lib/tabs/metrics/task/token_spec.rb
+- spec/lib/tabs/metrics/value/stats_spec.rb
 - spec/lib/tabs/metrics/value_spec.rb
 - spec/lib/tabs/task_spec.rb
 - spec/lib/tabs_spec.rb