tabstabs 2.0.0

data/lib/tabs_tabs/tabs_tabs.rb

@@ -0,0 +1,117 @@
+module TabsTabs
+  extend self
+  extend TabsTabs::Storage
+
+  class UnknownTypeError < StandardError; end
+  class DuplicateMetricError < StandardError; end
+  class UnknownMetricError < StandardError; end
+  class MetricTypeMismatchError < StandardError; end
+  class ResolutionMissingError < StandardError; end
+
+  METRIC_TYPES = ["counter", "value", "task"]
+
+  def configure
+    yield(Config)
+  end
+
+  def redis
+    Config.redis
+  end
+
+  def config
+    Config
+  end
+
+  def increment_counter(key, timestamp=Time.now)
+    create_metric(key, "counter") unless metric_exists?(key)
+    raise MetricTypeMismatchError.new("Only counter metrics can be incremented") unless metric_type(key) == "counter"
+    get_metric(key).increment(timestamp)
+  end
+
+  def record_value(key, value, timestamp=Time.now)
+    create_metric(key, "value") unless metric_exists?(key)
+    raise MetricTypeMismatchError.new("Only value metrics can record a value") unless metric_type(key) == "value"
+    get_metric(key).record(value, timestamp)
+  end
+
+  def start_task(key, token, timestamp=Time.now)
+    create_metric(key, "task")
+    raise MetricTypeMismatchError.new("Only task metrics can start a task") unless metric_type(key) == "task"
+    get_metric(key).start(token, timestamp)
+  end
+
+  def complete_task(key, token, timestamp=Time.now)
+    raise MetricTypeMismatchError.new("Only task metrics can complete a task") unless metric_type(key) == "task"
+    get_metric(key).complete(token, timestamp)
+  end
+
+  def create_metric(key, type)
+    raise UnknownTypeError.new("Unknown metric type: #{type}") unless METRIC_TYPES.include?(type)
+    raise DuplicateMetricError.new("Metric already exists: #{key}") if metric_exists?(key)
+    hset "metrics", key, type
+    metric_klass(type).new(key)
+  end
+
+  def get_metric(key)
+    raise UnknownMetricError.new("Unknown metric: #{key}") unless metric_exists?(key)
+    type = hget("metrics", key)
+    metric_klass(type).new(key)
+  end
+
+  def counter_total(key)
+    unless metric_exists?(key)
+      if block_given?
+        return yield
+      else
+        raise UnknownMetricError.new("Unknown metric: #{key}")
+      end
+    end
+    raise MetricTypeMismatchError.new("Only counter metrics can be incremented") unless metric_type(key) == "counter"
+    get_metric(key).total
+  end
+
+  def get_stats(key, period, resolution)
+    raise UnknownMetricError.new("Unknown metric: #{key}") unless metric_exists?(key)
+    metric = get_metric(key)
+    metric.stats(period, resolution)
+  end
+
+  def metric_type(key)
+    raise UnknownMetricError.new("Unknown metric: #{key}") unless metric_exists?(key)
+    hget "metrics", key
+  end
+
+  def list_metrics
+    hkeys "metrics"
+  end
+
+  def metric_exists?(key)
+    list_metrics.include? key
+  end
+
+  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
+
+  def drop_resolution_for_metric!(key, resolution)
+    raise UnknownMetricError.new("Unknown metric: #{key}") unless metric_exists?(key)
+    raise ResolutionMissingError.new(resolution) unless TabsTabs::Resolution.all.include? resolution
+    metric = get_metric(key)
+    metric.drop_by_resolution!(resolution) unless metric_type(key) == "task"
+  end
+
+  private
+
+  def metric_klass(type)
+    "TabsTabs::Metrics::#{type.classify}".constantize
+  end
+
+end

data/lib/tabs_tabs/version.rb

@@ -0,0 +1,3 @@
+module TabsTabs
+  VERSION = "2.0.0"
+end

data/spec/lib/tabs_tabs/config_spec.rb

@@ -0,0 +1,60 @@
+require "spec_helper"
+require File.expand_path("../../../support/custom_resolutions", __FILE__)
+
+describe TabsTabs::Config do
+  context "#decimal_precision" do
+
+  	before do
+  		@precision = TabsTabs::Config.decimal_precision
+  	end
+
+  	after do
+  		TabsTabs::Config.decimal_precision = @precision
+  	end
+
+  	it "should set/get the decimal precision" do
+  	  TabsTabs::Config.decimal_precision = 4
+  	  expect(TabsTabs::Config.decimal_precision).to eq(4)
+  	end
+  end
+
+  context "#register_resolution" do
+  	it "should register a resolution" do
+	  	TabsTabs::Resolution.register(WellFormedResolution)
+	  	expect(TabsTabs::Resolution.all).to include(:seconds)
+  	end
+  end
+
+  context "#unregister_resolution" do
+  	it "should unregister a resolution" do
+  		TabsTabs::Resolution.unregister(:minute)
+  		expect(TabsTabs::Resolution.all).to_not include(:minute)
+  	end
+  end
+
+  context "#set_expirations" do
+
+    after do
+      TabsTabs::Config.reset_expirations
+    end
+
+    it "should allow multiple resolutions to be expired" do
+      TabsTabs::Config.set_expirations({minute: 1.day, hour: 1.week })
+      expect(TabsTabs::Config.expiration_settings[:minute]).to eq(1.day)
+      expect(TabsTabs::Config.expiration_settings[:hour]).to eq(1.week)
+    end
+
+    it "should raise ResolutionMissingError if expiration passed in for invalid resolution" do
+      expect{ TabsTabs::Config.set_expirations({missing_resolution: 1.day }) }
+        .to raise_error(TabsTabs::ResolutionMissingError)
+    end
+
+  end
+
+  context "#prefix" do
+    it "should allow custom prefix for tabstabs keys" do
+      TabsTabs::Config.prefix = "rspec"
+      expect(TabsTabs::Config.prefix).to eq("rspec")
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+require "spec_helper"
+
+describe TabsTabs::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) { TabsTabs::Metrics::Counter::Stats.new(period, resolution, values) }
+
+  it "is enumerable" do
+    expect(stats).to respond_to :each
+    expect(TabsTabs::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.33333
+  end
+
+  it "avg returns 0 if values empty" do
+    stats = TabsTabs::Metrics::Counter::Stats.new(period, resolution, [])
+    expect(stats.avg).to be_zero
+  end
+
+end

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

@@ -0,0 +1,196 @@
+require "spec_helper"
+
+describe TabsTabs::Metrics::Counter do
+
+  include TabsTabs::Storage
+
+  let(:metric) { TabsTabs.create_metric("foo", "counter") }
+  let(:now) { Time.utc(2000, 1, 1, 0, 0) }
+
+  describe "incrementing stats" do
+
+    before { Timecop.freeze(now) }
+
+    it "increments the value for the expected periods" 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({ "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({ "timestamp" => time, "count" => 1 })
+    end
+
+    it "raises ResolutionMissingError if unregistered resolution requested" do
+      time = Time.utc(now.year, now.month, now.day, now.hour) - 2.hours
+      metric.increment(time)
+      TabsTabs::Resolution.unregister(:hour)
+      expect { metric.stats(((now - 3.hours)..now), :hour) }.to raise_error(TabsTabs::ResolutionMissingError)
+    end
+
+  end
+
+  describe "total count" do
+
+    it "is incremented every time regardless of resolution" do
+      30.times { metric.increment }
+      expect(metric.total).to eq(30)
+    end
+
+  end
+
+  describe "retrieving stats" do
+
+    before do
+      Timecop.freeze(now)
+    end
+
+    after do
+      Timecop.return
+    end
+
+    def create_span(time_unit)
+      metric.increment
+      Timecop.freeze(now + 1.send(time_unit))
+      metric.increment
+      Timecop.freeze(now + 3.send(time_unit))
+      metric.increment
+      Timecop.freeze(now + 6.send(time_unit))
+      metric.increment
+      metric.increment
+      Timecop.freeze(now)
+    end
+
+    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({ "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({ "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({ "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({ "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({ "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.detect{|s| s["timestamp"] == (now + 2.day)}["count"]).to eq(0)
+    end
+
+    context "for weekly metrics" do
+
+      let(:period) do
+        (now - 2.days)..((now + 7.weeks) + 2.days)
+      end
+
+      it "returns the expected results for a weekly metric" do
+        create_span(:weeks)
+        stats = metric.stats(period, :week)
+        expect(stats.detect{|s| s["timestamp"] == (now + 1.week).beginning_of_week}["count"]).to eq(1)
+        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["timestamp"]).to eq(period.first.beginning_of_week)
+        expect(stats.last["timestamp"]).to eq(period.last.beginning_of_week)
+      end
+
+    end
+
+  end
+
+  describe ".drop!" do
+
+    before do
+      3.times { metric.increment }
+      expect(exists("stat:counter:foo:total")).to be_truthy
+      @count_keys = (TabsTabs::Resolution.all.map do |res|
+        smembers("stat:counter:foo:keys:#{res}")
+      end).flatten
+      metric.drop!
+    end
+
+    it "deletes the counter total key" do
+      expect(exists("stat:counter:foo:total")).to be_falsey
+    end
+
+    it "deletes all resolution count keys" do
+      @count_keys.each do |key|
+        expect(exists(key)).to be_falsey
+      end
+    end
+
+    it "deletes all resolution key collection keys" do
+      TabsTabs::Resolution.all.each do |res|
+        expect(exists("stat:counter:foo:keys:#{res}")).to be_falsey
+      end
+    end
+
+  end
+
+  describe ".drop_by_resolution!" do
+    before do
+      Timecop.freeze(now)
+      2.times { metric.increment }
+      metric.drop_by_resolution!(:minute)
+    end
+
+    it "deletes all metrics for a resolution" do
+      stats = metric.stats((now - 1.minute)..(now + 1.minute), :minute)
+      expect(stats.total).to eq(0)
+    end
+  end
+
+  describe "expiration of counter metrics" do
+    let(:expires_setting){ 6.hours }
+    let(:now){ Time.utc(2050, 1, 1, 0, 0) }
+
+    before do
+      TabsTabs::Config.set_expirations({minute: expires_setting })
+    end
+
+    after do
+      TabsTabs::Config.reset_expirations
+    end
+
+    it "sets an expiration when recording a value" do
+      metric.increment(now)
+      redis_expire_date = Time.now + TabsTabs::Storage.ttl(metric.storage_key(:minute, now))
+      expire_date = now + expires_setting + TabsTabs::Resolutions::Minute.to_seconds
+      expect(redis_expire_date).to be_within(2.seconds).of(expire_date)
+    end
+  end
+
+end

data/spec/lib/tabs_tabs/metrics/task/token_spec.rb

@@ -0,0 +1,18 @@
+require "spec_helper"
+
+describe TabsTabs::Metrics::Task::Token do
+
+  describe "#time_elapsed" do
+
+    let(:token) { TabsTabs::Metrics::Task::Token.new("foo", "bar") }
+    let(:time) { Time.now }
+
+    it "should return the time between when the task/token started and completed" do
+      token.start(time - 2.days)
+      token.complete(time - 1.day)
+      expect(token.time_elapsed(:hour)).to eq(24)
+    end
+
+  end
+
+end

data/spec/lib/tabs_tabs/metrics/task_spec.rb

@@ -0,0 +1,103 @@
+require "spec_helper"
+
+describe TabsTabs::Metrics::Task do
+
+  let(:metric) { TabsTabs.create_metric("foo", "task") }
+  let(:now) { Time.utc(2000, 1, 1, 0, 0) }
+  let(:token_1) { "aaaa" }
+  let(:token_2) { "bbbb" }
+  let(:token_3) { "cccc" }
+
+  describe ".start" do
+
+    let(:token) { double(:token) }
+    let(:time) { Time.now }
+
+    it "calls start on the given token" do
+      expect(TabsTabs::Metrics::Task::Token).to receive(:new).with(token_1, "foo").and_return(token)
+      expect(token).to receive(:start)
+      metric.start(token_1)
+    end
+
+    it "passes through the specified timestamp" do
+      allow(TabsTabs::Metrics::Task::Token).to receive(:new).and_return(token)
+      expect(token).to receive(:start).with(time)
+      metric.start(token_1, time)
+    end
+
+  end
+
+  describe ".complete" do
+
+    let(:token) { double(:token) }
+    let(:time) { Time.now }
+
+    it "calls complete on the given token" do
+      expect(TabsTabs::Metrics::Task::Token).to receive(:new).with(token_1, "foo").and_return(token)
+      expect(token).to receive(:complete)
+      metric.complete(token_1)
+    end
+
+    it "passes through the specified timestamp" do
+      allow(TabsTabs::Metrics::Task::Token).to receive(:new).and_return(token)
+      expect(token).to receive(:complete).with(time)
+      metric.complete(token_1, time)
+    end
+
+    it "raises an UnstartedTaskMetricError if the metric has not yet been started" do
+      expect { metric.complete("foobar") }.to raise_error(TabsTabs::Metrics::Task::UnstartedTaskMetricError)
+    end
+
+  end
+
+  describe ".stats" do
+
+    it "returns zeroes across the board for no stats" do
+      stats = metric.stats((now - 5.minutes)..(now + 5.minutes), :minute)
+
+      expect(stats.started_within_period).to eq 0
+      expect(stats.completed_within_period).to eq 0
+      expect(stats.started_and_completed_within_period).to eq 0
+      expect(stats.completion_rate).to eq 0.0
+      expect(stats.average_completion_time).to eq 0.0
+    end
+
+    it "returns the expected value" do
+      Timecop.freeze(now)
+      metric.start(token_1)
+      metric.start(token_2)
+      Timecop.freeze(now + 2.minutes)
+      metric.complete(token_1)
+      metric.start(token_3)
+      Timecop.freeze(now + 3.minutes)
+      metric.complete(token_3)
+      stats = metric.stats((now - 5.minutes)..(now + 5.minutes), :minute)
+
+      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.18182
+      expect(stats.average_completion_time).to eq 1.5
+    end
+
+    it "returns the expected value for a week" do
+      Timecop.freeze(now)
+      metric.start(token_1)
+      metric.start(token_2)
+      Timecop.freeze(now + 1.week)
+      metric.complete(token_1)
+      metric.start(token_3)
+      Timecop.freeze(now + 3.weeks)
+      metric.complete(token_3)
+      stats = metric.stats((now - 5.weeks)..(now + 5.weeks), :week)
+
+      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.18182
+      expect(stats.average_completion_time).to eq 1.5
+    end
+
+  end
+
+end