tabs 0.8.2 → 0.9.0

data/README.md

@@ -201,6 +201,67 @@ When tabs increments a counter or records a value it does so for each of the fol
 
 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.
 
+#### Custom Resolutions
+
+If the built-in resolutions above don't work you can add your own.  All
+that's necessary is a module that conforms to the following protocol:
+
+```ruby
+module SecondResolution
+  extend Tabs::Resolutionable
+  extend self
+
+  PATTERN = "%Y-%m-%d-%H-%M-%S"
+
+  def serialize(timestamp)
+    timestamp.strftime(PATTERN)
+  end
+
+  def deserialize(str)
+    dt = DateTime.strptime(str, PATTERN)
+    self.normalize(dt)
+  end
+
+  def from_seconds(s)
+    s / 1
+  end
+
+  def normalize(ts)
+    Time.utc(ts.year, ts.month, ts.day, ts.hour, ts.min, ts.sec)
+  end
+end
+
+```
+
+A little description on each of the above methods:
+
+*`serialize`*: converts the timestamp to a string.  The return value
+here will be used as part of the Redis key storing values associated
+with a given metric.
+
+*`deserialize`*: converts the string representation of a timestamp back
+into an actual DateTime value.
+
+*`from_seconds`*: should return the number of periods in the given
+number of seconds.  For example, there are 60 seconds in a minute.
+
+*`normalize`*: should simply return the first timestamp for the period.
+For example, the week resolution returns the first hour of the first day
+of the week.
+
+*NOTE: If you're doing a custom resolution you should probably look into
+the code a bit.*
+
+Once you have a module that conforms to the resolution protocol you need
+to register it with Tabs.  You can do this in one of two ways:
+
+```ruby
+# This call can be anywhere before you start using tabs
+Tabs::Resolution.register(:second, SecondResolution)
+
+# or, you can use the config block described below
+```
+
 ### Inspecting Metrics
 
 You can list all metrics using `list_metrics`:
@@ -255,12 +316,15 @@ Tabs.configure do |config|
   # affects stat averages and task completion rate
   config.decimal_precision = 2
 
+  # registers a custom resolution
+  config.register_resolution :second, SecondResolution
+
 end
 ```
 
 ## Breaking Changes
 
-### Breaking Changes in v0.6.0
+### 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
@@ -268,7 +332,7 @@ 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
+### 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
@@ -276,7 +340,7 @@ 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.
 
-### Breaking Changes in v0.8.2
+### v0.8.2
 
 In version 0.8.2 and higher the storage keys for value metrics have been
 changed.  Originally the various pieces (avg, sum, count, etc) were

data/lib/tabs.rb

@@ -7,13 +7,14 @@ require "tabs/config"
 require "tabs/storage"
 require "tabs/helpers"
 
-require "tabs/resolution"
+require "tabs/resolutionable"
 require "tabs/resolutions/minute"
 require "tabs/resolutions/hour"
 require "tabs/resolutions/day"
 require "tabs/resolutions/week"
 require "tabs/resolutions/month"
 require "tabs/resolutions/year"
+require "tabs/resolution"
 
 require "tabs/metrics/counter/stats"
 require "tabs/metrics/counter"

data/lib/tabs/config.rb

@@ -22,5 +22,9 @@ module Tabs
       @redis ||= Redis.new
     end
 
+    def register_resolution(resolution, klass)
+      Tabs::Resolution.register(resolution, klass)
+    end
+
   end
 end

data/lib/tabs/metrics/counter.rb

@@ -12,7 +12,7 @@ module Tabs
 
       def increment(timestamp=Time.now)
         timestamp.utc
-        Tabs::RESOLUTIONS.each do |resolution|
+        Tabs::Resolution.all.each do |resolution|
           increment_resolution(resolution, timestamp)
         end
         increment_total

data/lib/tabs/metrics/task.rb

@@ -34,10 +34,10 @@ module Tabs
         range = timestamp_range(period, resolution)
         started_tokens = tokens_for_period(range, resolution, "started")
         completed_tokens = tokens_for_period(range, resolution, "completed")
-        matching_tokens = started_tokens & completed_tokens
+        matching_tokens = started_tokens.select { |token| completed_tokens.include? token }
         completion_rate = (matching_tokens.size.to_f / range.size).round(Config.decimal_precision)
         elapsed_times = matching_tokens.map { |t| t.time_elapsed(resolution) }
-        average_completion_time = (elapsed_times.inject(&:+)) / matching_tokens.size
+        average_completion_time = (elapsed_times.sum) / matching_tokens.size
         Stats.new(
           started_tokens.size,
           completed_tokens.size,

data/lib/tabs/metrics/task/token.rb

@@ -1,62 +1,71 @@
 module Tabs
   module Metrics
     class Task
-      class Token < String
+      class Token
         include Storage
 
         attr_reader :key
+        attr_reader :token
 
         def initialize(token, key)
           @key = key
-          super(token)
+          @token = token
         end
 
         def start(timestamp=Time.now)
           self.start_time = timestamp.utc
-          sadd("stat:task:#{key}:tokens", self)
-          Tabs::RESOLUTIONS.each { |res| record_start(res, start_time) }
+          sadd("stat:task:#{key}:tokens", token)
+          Tabs::Resolution.all.each { |res| record_start(res, start_time) }
         end
 
         def complete(timestamp=Time.now)
           self.complete_time = timestamp.utc
-          unless sismember("stat:task:#{key}:tokens", self)
-            raise UnstartedTaskMetricError.new("No task for metric '#{key}' was started with token '#{self}'")
+          unless sismember("stat:task:#{key}:tokens", token)
+            raise UnstartedTaskMetricError.new("No task for metric '#{key}' was started with token '#{token}'")
           end
-          Tabs::RESOLUTIONS.each { |res| record_complete(res, complete_time) }
+          Tabs::Resolution.all.each { |res| record_complete(res, complete_time) }
         end
 
         def time_elapsed(resolution)
           Tabs::Resolution.from_seconds(resolution, complete_time - start_time)
         end
 
+        def ==(other_token)
+          self.token == other_token.token
+        end
+
+        def to_s
+          "#{super}:#{token}"
+        end
+
         private
 
         def record_start(resolution, timestamp)
           formatted_time = Tabs::Resolution.serialize(resolution, timestamp)
-          sadd("stat:task:#{key}:started:#{formatted_time}", self)
+          sadd("stat:task:#{key}:started:#{formatted_time}", token)
         end
 
         def record_complete(resolution, timestamp)
           formatted_time = Tabs::Resolution.serialize(resolution, timestamp)
-          sadd("stat:task:#{key}:completed:#{formatted_time}", self)
+          sadd("stat:task:#{key}:completed:#{formatted_time}", token)
         end
 
         def start_time=(timestamp)
-          set("stat:task:#{key}:#{self}:started_time", timestamp)
+          set("stat:task:#{key}:#{token}:started_time", timestamp)
           @start_time = timestamp
         end
 
         def start_time
-          @start_time ||= Time.parse(get("stat:task:#{key}:#{self}:started_time"))
+          Time.parse(get("stat:task:#{key}:#{token}:started_time"))
         end
 
         def complete_time=(timestamp)
-          set("stat:task:#{key}:#{self}:completed_time", timestamp)
+          set("stat:task:#{key}:#{token}:completed_time", timestamp)
           @complete_time = timestamp
         end
 
         def complete_time
-          @complete_time ||= Time.parse(get("stat:task:#{key}:#{self}:completed_time"))
+          Time.parse(get("stat:task:#{key}:#{token}:completed_time"))
         end
 
       end

data/lib/tabs/metrics/value.rb

@@ -12,7 +12,7 @@ module Tabs
 
       def record(value, timestamp=Time.now)
         timestamp.utc
-        Tabs::RESOLUTIONS.each do |resolution|
+        Tabs::Resolution.all.each do |resolution|
           formatted_time = Tabs::Resolution.serialize(resolution, timestamp)
           stat_key = "stat:value:#{key}:data:#{formatted_time}"
           update_values(stat_key, value)

data/lib/tabs/resolution.rb

@@ -2,6 +2,11 @@ module Tabs
   module Resolution
     extend self
 
+    def register(resolution, klass)
+      @@resolution_classes ||= {}
+      @@resolution_classes[resolution] = klass
+    end
+
     def serialize(resolution, timestamp)
       resolution_klass(resolution).serialize(timestamp)
     end
@@ -18,11 +23,22 @@ module Tabs
       resolution_klass(resolution).normalize(timestamp)
     end
 
+    def all
+      @@resolution_classes.keys
+    end
+
     private
 
     def resolution_klass(resolution)
-      "Tabs::Resolutions::#{resolution.to_s.classify}".constantize
+      @@resolution_classes[resolution]
     end
 
   end
 end
+
+Tabs::Resolution.register(:minute, Tabs::Resolutions::Minute)
+Tabs::Resolution.register(:hour, Tabs::Resolutions::Hour)
+Tabs::Resolution.register(:day, Tabs::Resolutions::Day)
+Tabs::Resolution.register(:week, Tabs::Resolutions::Week)
+Tabs::Resolution.register(:month, Tabs::Resolutions::Month)
+Tabs::Resolution.register(:year, Tabs::Resolutions::Year)

data/lib/tabs/resolutionable.rb

@@ -0,0 +1,23 @@
+module Tabs
+  module Resolutionable
+    extend self
+
+    class MethodNotImplementedException < Exception; end
+
+    def serialize
+      raise MethodNotImplementedException
+    end
+
+    def deserialize
+      raise MethodNotImplementedException
+    end
+
+    def from_seconds
+      raise MethodNotImplementedException
+    end
+
+    def normalize
+      raise MethodNotImplementedException
+    end
+  end
+end

data/lib/tabs/resolutions/day.rb

@@ -1,6 +1,7 @@
 module Tabs
   module Resolutions
     module Day
+      extend Resolutionable
       extend self
 
       PATTERN = "%Y-%m-%d"

data/lib/tabs/resolutions/hour.rb

@@ -1,6 +1,7 @@
 module Tabs
   module Resolutions
     module Hour
+      extend Tabs::Resolutionable
       extend self
 
       PATTERN = "%Y-%m-%d-%H"

data/lib/tabs/resolutions/minute.rb

@@ -1,6 +1,7 @@
 module Tabs
   module Resolutions
     module Minute
+      extend Tabs::Resolutionable
       extend self
 
       PATTERN = "%Y-%m-%d-%H-%M"

data/lib/tabs/resolutions/month.rb

@@ -1,6 +1,7 @@
 module Tabs
   module Resolutions
     module Month
+      extend Tabs::Resolutionable
       extend self
 
       PATTERN = "%Y-%m"

data/lib/tabs/resolutions/week.rb

@@ -1,6 +1,7 @@
 module Tabs
   module Resolutions
     module Week
+      extend Tabs::Resolutionable
       extend self
 
       PATTERN = "%Y-%W"

data/lib/tabs/resolutions/year.rb

@@ -1,6 +1,7 @@
 module Tabs
   module Resolutions
     module Year
+      extend Tabs::Resolutionable
       extend self
 
       PATTERN = "%Y"

data/lib/tabs/tabs.rb

@@ -9,8 +9,6 @@ module Tabs
 
   METRIC_TYPES = ["counter", "value", "task"]
 
-  RESOLUTIONS = [:minute, :hour, :day, :week, :month, :year]
-
   def configure
     yield(Config)
   end

data/lib/tabs/version.rb

@@ -1,3 +1,3 @@
 module Tabs
-  VERSION = "0.8.2"
+  VERSION = "0.9.0"
 end

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

@@ -126,7 +126,7 @@ describe Tabs::Metrics::Counter do
     before do
       3.times { metric.increment }
       expect(exists("stat:counter:foo:total")).to be_true
-      @count_keys = (Tabs::RESOLUTIONS.map do |res|
+      @count_keys = (Tabs::Resolution.all.map do |res|
         smembers("stat:counter:foo:keys:#{res}")
       end).flatten
       metric.drop!
@@ -143,7 +143,7 @@ describe Tabs::Metrics::Counter do
     end
 
     it "deletes all resolution key collection keys" do
-      Tabs::RESOLUTIONS.each do |res|
+      Tabs::Resolution.all.each do |res|
         expect(exists("stat:counter:foo:keys:#{res}")).to be_false
       end
     end

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

@@ -101,7 +101,7 @@ describe Tabs::Metrics::Value do
 
     before do
       3.times { metric.record(rand(30)) }
-      @count_keys = (Tabs::RESOLUTIONS.map do |res|
+      @count_keys = (Tabs::Resolution.all.map do |res|
         smembers("stat:value:foo:keys:#{res}")
       end).flatten
       metric.drop!
@@ -114,7 +114,7 @@ describe Tabs::Metrics::Value do
     end
 
     it "deletes all resolution key collection keys" do
-      Tabs::RESOLUTIONS.each do |res|
+      Tabs::Resolution.all.each do |res|
         expect(exists("stat:value:foo:keys:#{res}")).to be_false
       end
     end

data/spec/lib/tabs/resolution_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+require File.expand_path('../../../support/custom_resolutions', __FILE__)
+
+describe Tabs::Resolution do
+  describe '#register' do
+    it 'registers a new resolution' do
+      Tabs::Resolution.register(:test, Tabs::Resolutions::Minute)
+      expect(Tabs::Resolution.all).to include :test
+    end
+
+    context 'with a custom resolution' do
+      it 'does not return nil' do
+        expect(WellFormedResolution.serialize(Time.now)).to_not be_nil
+      end
+
+      it 'gets stats for custom resolution' do
+        Tabs::Resolution.register(:seconds, WellFormedResolution)
+        Timecop.freeze(Time.now)
+
+        Tabs.increment_counter('foo')
+        expect(Tabs.get_stats('foo', (Time.now - 5.seconds..Time.now), :seconds).values.size).to eq(6)
+      end
+
+      it 'raises an error when method not implemented' do
+        expect{BadlyFormedResolution.normalize}.to raise_error Tabs::Resolutionable::MethodNotImplementedException
+      end
+    end
+  end
+end

data/spec/lib/tabs/task_spec.rb

@@ -4,9 +4,9 @@ describe Tabs::Metrics::Task do
 
   let(:metric) { Tabs.create_metric("foo", "task") }
   let(:now) { Time.utc(2000, 1, 1, 0, 0) }
-  let(:token_1) { "2gd7672gjh3" }
-  let(:token_2) { "17985jh34gj" }
-  let(:token_3) { "27f98fhgh1x" }
+  let(:token_1) { "aaaa" }
+  let(:token_2) { "bbbb" }
+  let(:token_3) { "cccc" }
 
   describe ".start" do
 

data/spec/support/custom_resolutions.rb

@@ -0,0 +1,28 @@
+module BadlyFormedResolution
+  extend Tabs::Resolutionable
+  extend self
+end
+
+module WellFormedResolution
+  extend Tabs::Resolutionable
+  extend self
+
+  PATTERN = "%Y-%m-%d-%H-%M-%S"
+
+  def serialize(timestamp)
+    timestamp.strftime(PATTERN)
+  end
+
+  def deserialize(str)
+    dt = DateTime.strptime(str, PATTERN)
+    self.normalize(dt)
+  end
+
+  def from_seconds(s)
+    s / 1
+  end
+
+  def normalize(ts)
+    Time.utc(ts.year, ts.month, ts.day, ts.hour, ts.min, ts.sec)
+  end
+end

data/tabs.gemspec

@@ -42,7 +42,6 @@ continue to use v0.8.1 or lower if that is an issue.
 EOS
 
   gem.add_dependency "activesupport", ">= 3.2"
-  gem.add_dependency "json", ">= 1.7"
   gem.add_dependency "redis", "~> 3.0.0"
 
   gem.add_development_dependency "fakeredis"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tabs
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-02 00:00:00.000000000 Z
+date: 2013-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -27,22 +27,6 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '3.2'
-- !ruby/object:Gem::Dependency
-  name: json
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '1.7'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -164,6 +148,7 @@ files:
 - lib/tabs/metrics/value.rb
 - lib/tabs/metrics/value/stats.rb
 - lib/tabs/resolution.rb
+- lib/tabs/resolutionable.rb
 - lib/tabs/resolutions/day.rb
 - lib/tabs/resolutions/hour.rb
 - lib/tabs/resolutions/minute.rb
@@ -178,9 +163,11 @@ files:
 - 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/resolution_spec.rb
 - spec/lib/tabs/task_spec.rb
 - spec/lib/tabs_spec.rb
 - spec/spec_helper.rb
+- spec/support/custom_resolutions.rb
 - tabs.gemspec
 homepage: https://github.com/thegrubbsian/tabs
 licenses: []
@@ -251,7 +238,9 @@ test_files:
 - 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/resolution_spec.rb
 - spec/lib/tabs/task_spec.rb
 - spec/lib/tabs_spec.rb
 - spec/spec_helper.rb
+- spec/support/custom_resolutions.rb
 has_rdoc: