success_tracker 0.5

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in success_tracker.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 autohaus24 GmbH
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# SuccessTracker
+
+Allows you to track success and failure of tasks and define thresholds for unexpected failure conditions. When the threshold is met, the failure method returns true (otherwise false). This can be used to define in code what to do when the failure condition is met. The failure method gets the name of a rule as a second parameter. This rule is used to define when a failure should be seen as unexpected. There are some rules defined as default (:percent\_10 which fails when there is at least a 10 percent failure rate with a minimum of 10 records and :sequence\_of\_5 which fails when there are at least 5 failures in a row).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'success_tracker'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install success_tracker
+
+## Usage
+
+```ruby
+$success_tracker = SuccessTracker::Base.new(redis_connection)
+$success_tracker.success('mytask')
+if $success_tracker.failure('mytask', :percent_10)
+  puts "reached the threshold!"
+end
+```
+
+You can define additional rules with your own code blocks or use the sequence_rule or ratio_rule class methods for this task. These code blocks get an array of the recorded notifications as parameters which can have between 0 and 100 elements all having either an empty string (failure) or a "1" (success).
+
+```ruby
+$success_tracker = SuccessTracker::Base.new(redis_connection, :rules => {
+  :percent_50 => SuccessTracker::Base.ratio_rule(0.5)
+})
+$success_tracker.failure('mytask', :percent_50)
+```
+
+You can give a block to the failure method which is always yielded. In case the block raises an exception and the failure condition is not met, the exception is extended with the SuccessTracker::NonSignificantError module. This can then be used in rescue statements to define what should only happen if the handled exception was not triggered with a failure condition met.
+
+```ruby
+$success_tracker = SuccessTracker::Base.new(redis_connection)
+$success_tracker.failure('mytask', :percent_10) do
+  raise ArgumentError
+end
+
+# You can also use it to exclude these errors from Airbrake reporting.
+Airbrake.configure do |config|
+  config.ignore_by_filter do |notice|
+    SuccessTracker::NonSignificantError === notice.exception
+  end
+end
+```
+
+By default all StandardErrors are extended but in the options you can define an array with the exceptions which should be tagged.
+
+```ruby
+$success_tracker = SuccessTracker::Base.new(redis_connection)
+$success_tracker.failure('mytask', :percent_10, :exceptions => [ MySpecialError ]) do
+  raise ArgumentError # will not be tagged because it is the wrong exception type
+end
+```
+
+You can also define on_success and on_failure callbacks which run on success or failure and get the identifier given to the success or failure method as a parameter. Use this for example to track success and failure rates in StatsD.
+
+```ruby
+# assuming you have statsd-client stored in $statsd
+$success_tracker = SuccessTracker::Base.new(redis_connection, {
+    :on_success => lambda { |identifier| $statsd.increment("#{identifier}.success") },
+    :on_failure => lambda { |identifier| $statsd.increment("#{identifier}.failure") }
+  }
+)
+```
+
+## Requirements
+
+* Redis
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+MIT License. Copyright 2013 autohaus24 GmbH

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end

data/lib/success_tracker.rb

@@ -0,0 +1,75 @@
+require "success_tracker/version"
+require 'redis'
+
+module SuccessTracker
+  module NonSignificantError
+  end
+
+  class Base
+    attr_accessor :callbacks, :rules, :redis, :list_length
+
+    def initialize(redis, options={})
+      @redis = redis
+
+      @rules = {
+        :percent_10 => self.class.ratio_rule(0.1),
+        :sequence_of_5 => self.class.sequence_rule(5),
+      }.merge(options.delete(:rules) || {})
+      @callbacks = options.delete(:callbacks) || {}
+      raise ArgumentError unless options.empty?
+
+      @list_length = 100
+    end
+
+    def prefix(identifier); "success_tracker:#{identifier}" end
+
+    def success(identifier)
+      callbacks[:success].call(identifier) if callbacks[:success]
+      store(identifier, "1")
+    end
+
+    # +identifier+ is the key used for grouping success and failure cases together.
+    # +notify_rule+ is a symbol identifying the code block which is evaluated to know if the error is significant or not.
+    # + options+ is a hash which currently can only contain the list of exceptions which should be tagged with the NonSignificantError module
+    # the given block is always evaluated and the resulting errors are tagged with the NonSignificantError and reraised
+    def failure(identifier, notify_rule, options={})
+      callbacks[:failure].call(identifier) if callbacks[:failure]
+      store(identifier, nil)
+
+      redis.del(prefix(identifier)) if notify = rules[notify_rule].call(redis.lrange(prefix(identifier), 0,-1))
+
+      begin
+        yield if block_given?
+      rescue *(options[:exceptions] || [StandardError]) => error
+        error.extend(NonSignificantError) unless notify
+        raise
+      end
+
+      return notify
+    end
+
+    # yields the given code block and then marks success. In case a exception was triggered it marks a failure and reraises the exception (for the arguments see the #failure method)
+    def track(identifier, notify_rule, options={})
+      yield.tap { success(identifier) }
+    rescue => exception
+      failure(identifier, notify_rule, options) { raise exception }
+    end
+
+
+    # returns true if the failure ratio is higher than x (with a minimum of 10 records)
+    def self.ratio_rule(ratio=0.1, minimum=10)
+      lambda { |list| list.length >= minimum and list.select(&:empty?).length.to_f / list.length >= ratio }
+    end
+
+    # returns true if the last x elements have failed
+    def self.sequence_rule(elements=5)
+      lambda { |list| list.length >= elements && list[0..elements-1].reject(&:empty?).length == 0 }
+    end
+
+    protected
+    def store(identifier, value)
+      redis.lpush(prefix(identifier), value)
+      redis.ltrim(prefix(identifier), 0, @list_length - 1)
+    end
+  end
+end

data/lib/success_tracker/version.rb

@@ -0,0 +1,3 @@
+module SuccessTracker
+  VERSION = "0.5"
+end

data/success_tracker.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'success_tracker/version'
+
+Gem::Specification.new do |gem|
+  gem.homepage      = "https://github.com/autohaus24/success_tracker"
+  gem.name          = "success_tracker"
+  gem.version       = SuccessTracker::VERSION
+  gem.authors       = ["Michael Raidel"]
+  gem.email         = ["m.raidel@autohaus24.de"]
+  gem.description   = %q{SuccessTracker allows you to track success and failure of tasks}
+  gem.summary       = %q{SuccessTracker allows you to track success and failure of tasks and define thresholds for unexpected failure conditions.}
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  gem.add_dependency "redis"
+  gem.add_development_dependency "shoulda"
+  gem.add_development_dependency "rake"
+end

data/test/success_tracker_test.rb

@@ -0,0 +1,164 @@
+require 'test/unit'
+require 'shoulda'
+require 'success_tracker'
+
+class SuccessTracker::BaseTest < Test::Unit::TestCase
+  def setup
+    @redis = Redis.new
+    @prefix = "success_tracker"
+    @key = "test_key"
+  end
+
+  def teardown
+    @redis.del("#{@prefix}:#{@key}")
+  end
+
+  should "store a success in the given redis key" do
+    success_tracker = SuccessTracker::Base.new(@redis)
+    success_tracker.success(@key)
+
+    assert_equal ["1"], @redis.lrange("#{@prefix}:#{@key}", 0, -1)
+  end
+
+  should "store an error in the given redis key" do
+    success_tracker = SuccessTracker::Base.new(@redis)
+    success_tracker.failure(@key, :percent_10)
+
+    assert_equal [""], @redis.lrange("#{@prefix}:#{@key}", 0, -1)
+  end
+
+  should "yield the success callback on success" do
+    success_tracker = SuccessTracker::Base.new(@redis, :callbacks => { :success => lambda { |identifier| @identifier = "success: #{identifier}" } })
+    success_tracker.success(@key)
+
+    assert_equal "success: #{@key}", @identifier
+  end
+
+  should "yield the failure callback on failure" do
+    success_tracker = SuccessTracker::Base.new(@redis, :callbacks => { :failure => lambda { |identifier| @identifier = "failure: #{identifier}" } })
+    success_tracker.failure(@key, :percent_10)
+
+    assert_equal "failure: #{@key}", @identifier
+  end
+
+  should "raise an ArgumentError when initializing with unknown options" do
+    assert_raise(ArgumentError) do
+      SuccessTracker::Base.new(@redis, :foo => "bar")
+    end
+  end
+
+  should "allow a maximum number of records" do
+    success_tracker = SuccessTracker::Base.new(@redis)
+    105.times { success_tracker.success(@key) }
+    assert_equal 100, @redis.lrange("#{@prefix}:#{@key}", 0, -1).length
+  end
+
+  should "yield failure block" do
+    success_tracker = SuccessTracker::Base.new(@redis)
+    success_tracker.failure(@key, :percent_10) do
+      @output_from_block = true
+    end
+
+    assert @output_from_block
+  end
+
+  should "track success" do
+    success_tracker = SuccessTracker::Base.new(@redis)
+    success_tracker.track(@key, :percent_10) { "working block" }
+    assert_equal ["1"], @redis.lrange("#{@prefix}:#{@key}", 0, -1)
+  end
+
+  should "return result from block on #track" do
+    success_tracker = SuccessTracker::Base.new(@redis)
+    assert_equal "result", success_tracker.track(@key, :percent_10) { "result" }
+  end
+
+  should "track failure and reraise tagged exception" do
+    success_tracker = SuccessTracker::Base.new(@redis)
+    begin
+      success_tracker.track(@key, :percent_10) { raise ArgumentError }
+      flunk "should have raised an exception before"
+    rescue => exception
+      assert ArgumentError === exception, "exception should be an ArgumentError"
+      assert SuccessTracker::NonSignificantError === exception, "exception should be a NonSignificantError"
+    end
+    assert_equal [""], @redis.lrange("#{@prefix}:#{@key}", 0, -1)
+  end
+
+  context "ratio_rule" do
+    should "return false until threshold of x percent is reached" do
+      rule = SuccessTracker::Base.ratio_rule(0.1)
+      assert !rule.call(["1"] * 10 + [""] * 1), "should return false when threshold is not reached"
+      assert rule.call(["1"] * 9 + [""] * 1), "should return true when threshold is reached"
+    end
+
+    should "always return true before minimum" do
+      rule = SuccessTracker::Base.ratio_rule(0.1, 3)
+      assert !rule.call([""] * 2), "should return false when below minimum"
+      assert rule.call([""] * 3), "should return true when minimum is reached"
+    end
+  end
+
+  context "sequence_rule" do
+    should "return false until threshold of x percent is reached" do
+      rule = SuccessTracker::Base.sequence_rule(5)
+      assert !rule.call([""] * 4 + ["1"] * 5), "should return false before having x failures in a row"
+      assert rule.call([""] * 5 + ["1"] * 5), "should return true when having x failures in a row"
+    end
+  end
+
+  context "over threshold" do
+    setup do
+      @success_tracker = SuccessTracker::Base.new(@redis, :rules => { :never_below_threshold => lambda { |list| true } })
+    end
+
+    should "reraise errors from failure block not extended with module" do
+      begin
+        @success_tracker.failure(@key, :never_below_threshold) do
+          raise NoMethodError
+        end
+        flunk "should raise exception before"
+      rescue NoMethodError => exception
+        assert !(SuccessTracker::NonSignificantError === exception), "should not have the module when meeting the error condition"
+      end
+    end
+
+    should "empty the list" do
+      @success_tracker.failure(@key, :never_below_threshold)
+      assert_equal [], @redis.lrange("#{@prefix}:#{@key}", 0, -1)
+    end
+  end
+
+  context "below threshold" do
+    setup do
+      @success_tracker = SuccessTracker::Base.new(@redis, :rules => { :always_below_threshold => lambda { |list| false } })
+    end
+
+    should "reraise errors from failure block extended with module" do
+      begin
+        @success_tracker.failure(@key, :always_below_threshold) do
+          raise NoMethodError
+        end
+        flunk "should raise exception before"
+      rescue NoMethodError => exception
+        assert SuccessTracker::NonSignificantError === exception, "should have the module before meeting the error condition"
+      end
+    end
+
+    should "not reraise errors from failure block extended with module" do
+      begin
+        @success_tracker.failure(@key, :always_below_threshold, :exceptions => [ ArgumentError ]) do
+          raise NoMethodError
+        end
+        flunk "should raise exception before"
+      rescue NoMethodError => exception
+        assert !(SuccessTracker::NonSignificantError === exception), "should not have the module for an NoMethodError"
+      end
+    end
+
+    should "not empty the list" do
+      @success_tracker.failure(@key, :always_below_threshold)
+      assert_equal [""], @redis.lrange("#{@prefix}:#{@key}", 0, -1)
+    end
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: success_tracker
+version: !ruby/object:Gem::Version
+  version: '0.5'
+  prerelease: 
+platform: ruby
+authors:
+- Michael Raidel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: &86238180 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *86238180
+- !ruby/object:Gem::Dependency
+  name: shoulda
+  requirement: &86237970 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *86237970
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &86237730 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *86237730
+description: SuccessTracker allows you to track success and failure of tasks
+email:
+- m.raidel@autohaus24.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/success_tracker.rb
+- lib/success_tracker/version.rb
+- success_tracker.gemspec
+- test/success_tracker_test.rb
+homepage: https://github.com/autohaus24/success_tracker
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: SuccessTracker allows you to track success and failure of tasks and define
+  thresholds for unexpected failure conditions.
+test_files:
+- test/success_tracker_test.rb
+has_rdoc: