tabs 0.5.0 → 0.5.2

data/README.md

@@ -1,8 +1,6 @@
 # Tabs
 
-Tabs is a redis-backed metrics tracker that supports counts, sums,
-averages, and min/max stats sliceable by the minute, hour, day, week,
-month, and year.
+Tabs is a redis-backed metrics tracker that supports counts, sums, averages, and min/max stats sliceable by the minute, hour, day, week, month, and year.
 
 ## Installation
 
@@ -20,16 +18,94 @@ Or install it yourself as:
 
 ## Usage
 
-To count events, simply call the `increment` or `record` methods to
-write an event to the store.
+Metrics come in two flavors: counters and values.
 
-### Increment a counter
+### Counter Metrics
 
-Tabs.increment(key)
+A counter metric simply records the number of events that occur within a given timeframe.  To create a counter metric called ‘website-visits’, simply call:
 
-### Record a value
+    Tabs.create_metric(“website-visits”, “counter”)
+    
+This will set up the metric in the database.
 
-Tabs.record(key, 37)
+To increment a metric counter, simply call:
+
+    Tabs.increment_counter(“website-visits”)
+
+To retrieve the counts for a given time period just call `Tabs#get_stats` with the name of the metric, a range of times defining the period for which you want stats, and the resolution at which the data should be aggregated.
+
+    Tabs.get_stats(“website-visits”, (Time.now - 10.days)..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.
+
+    [
+      { 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 },
+      ...
+    ]
+    
+Times for the given period in which no events occurred will be “filled in” with a zero value to make visualizations easier.
+
+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.
+
+### 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:
+
+    Tabs.create_metric(“new-user-age”, “value”)
+    
+To record a value, simply call `Tabs#record_value`.
+
+    Tabs.record_value(“new-user-age”, 32)
+    
+Retrieving the stats for a value metric is just like retrieving a counter metric.
+
+    Tabs.get_stats(“new-user-age”, (Time.now - 6.months)..Time.now, :month)
+    
+This will return a familiar value, but with an expanded set of values.
+
+    [
+      { 2000-01-01 00:00:00 UTC => { min: 19, max: 54, sum: 226, avg: 38 } },
+      { 2000-02-01 01:00:00 UTC => { min: 0, max: 0, sum: 0, avg: 0 } },
+      { 2000-03-01 02:00:00 UTC => { min: 22, max: 34, sum: 180, avg: 26 } },
+      ...
+    ]
+
+### Resolutions
+
+When tabs increments a counter or records a value it does so for each of the following “resolutions”.  You may supply any of these as the last argument to the `Tabs#get_stats` method.
+
+    :minute, :hour, :day, :week, :month, :year
+
+It automatically aggregates multiple events for the same period.  For instance when you increment a counter metric, 1 will be added for each of the resolutions for the current time.  Repeating the event 5 minutes later will increment a different minute slot, but the same hour, date, week, etc.  When you retrieve metrics, all timestamps will be in UTC.
+
+### Drop a Metric
+
+To drop a metric, just call `Tabs#drop_metric`
+
+    Tabs.drop_metric(“website-visits”)
+    
+This will drop all recorded values for the metric so it may not be un-done...be careful.
+
+### 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.
+
+    Tabs.configure do |config|
+    
+      # set it to an existing connection
+      config.redis = Redis.current
+      
+      # pass a config hash that will be passed to Redis.new
+      config.redis = { :host => 'localhost', :port => 6379 }
+      
+    end
 
 ## Contributing
 

data/lib/tabs/storage.rb

@@ -23,6 +23,11 @@ module Tabs
       redis.set("tabs:#{key}", value)
     end
 
+    def del(*keys)
+      prefixed_keys = keys.map { |k| "tabs:#{k}" }
+      redis.del(*prefixed_keys)
+    end
+
     def incr(key)
       redis.incr("tabs:#{key}")
     end

data/lib/tabs/tabs.rb

@@ -44,13 +44,23 @@ module Tabs
     metric_klass(type).new(key)
   end
 
+  def get_stats(key, period, resolution)
+    metric = get_metric(key)
+    metric.stats(period, resolution)
+  end
+
   def metric_type(key)
     hget "metrics", key
   end
 
   def drop_metric(key)
     hdel "metrics", key
-    # TODO: Need to finish this
+    Tabs::RESOLUTIONS.each do |resolution|
+      stat_key = "stat:keys:#{key}:#{resolution}"
+      keys = smembers(stat_key)
+      del(keys)
+      del stat_key
+    end
   end
 
   def list_metrics

data/lib/tabs/version.rb

@@ -1,3 +1,3 @@
 module Tabs
-  VERSION = "0.5.0"
+  VERSION = "0.5.2"
 end

data/spec/lib/tabs_spec.rb

@@ -1,6 +1,7 @@
 require "spec_helper"
 
 describe Tabs do
+  include Tabs::Storage
 
   describe "#create_metric" do
 
@@ -74,7 +75,13 @@ describe Tabs do
       expect(Tabs.metric_exists?("foo")).to be_false
     end
 
-    it "removes the metrics values from redis"
+    it "removes the metrics values from redis" do
+      Tabs.increment_counter("foo")
+      keys = smembers("tabs:stat:keys:foo:hour")
+      expect(redis.keys).to include("tabs:stat:keys:foo:hour")
+      Tabs.drop_metric("foo")
+      expect(redis.keys).to_not include(keys[0])
+    end
 
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tabs
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-22 00:00:00.000000000 Z
+date: 2013-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis