minuteman 0.0.1

data/Gemfile

@@ -0,0 +1,4 @@
+source :rubygems
+
+gemspec
+gem "rake"

data/Gemfile.lock

@@ -0,0 +1,20 @@
+PATH
+  remote: .
+  specs:
+    minuteman (0.0.1)
+      redis (~> 3.0.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    minitest (4.1.0)
+    rake (0.9.2.2)
+    redis (3.0.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  minitest (~> 4.1.0)
+  minuteman!
+  rake

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Bruno Aguirre
+
+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,96 @@
+# Minuteman
+
+_Wikipedia_: Minutemen were members of teams from Massachusetts that were well-prepared
+militia companies of select men from the American colonial partisan militia
+during the American Revolutionary War. _They provided a highly mobile, rapidly
+deployed force that allowed the colonies to respond immediately to war threats,
+hence the name._
+
+![Minuteman](http://upload.wikimedia.org/wikipedia/commons/thumb/4/4b/Minute_Man_Statue_Lexington_Massachusetts_cropped.jpg/220px-Minute_Man_Statue_Lexington_Massachusetts_cropped.jpg)
+
+Fast analytics using Redis bitwise operations
+
+## Origin
+Freenode - #cuba.rb - 2012/10/30 15:20 UYT
+
+**conanbatt:** anyone here knows some good web app metrics tool ?
+
+**conanbatt:** i use google analytics for the page itself, and its good, but for the webapp its really not useful
+
+**tizoc: conanbatt:** [http://amix.dk/blog/post/19714]() you can port this (if an equivalent doesn't exist already)
+
+**conanbatt:** the metrics link is excellent but its python and released 5 days ago lol
+
+**elcuervo: tizoc:** the idea it's awesome
+
+**elcuervo:** interesting...
+
+
+## Inspiration
+
+* [http://blog.getspool.com/2011/11/29/fast-easy-realtime-metrics-using-redis-bitmaps/]()
+* [http://amix.dk/blog/post/19714]()
+* [http://en.wikipedia.org/wiki/Bit_array]()
+
+## Installation
+
+### Important!
+
+Depends on Redis 2.6 for the `bitop` operation. You can install it using:
+
+```bash
+brew install --devel redis
+```
+
+or upgrading your current version:
+
+```bash
+brew upgrade --devel redis
+```
+
+And then install the gem
+
+```bash
+gem install minuteman
+```
+
+## Usage
+
+```ruby
+require "minuteman"
+
+# Accepts an options hash that will be sent as is to Redis.new
+analytics = Minuteman.new
+
+# Mark an event for a given id
+analytics.mark("login:successful", user.id)
+analytics.mark("login:successful", other_user.id)
+
+# Mark in bulk
+analytics.mark("programming:love:ruby", User.where(favorite: "ruby").map(&:id))
+
+# Fetch events for a given time
+today_events = analytics.day("login:successful", Time.now.utc)
+
+# This also exists
+analytics.year("login:successful", Time.now.utc)
+analytics.month("login:successful", Time.now.utc)
+analytics.week("login:successful", Time.now.utc)
+analytics.day("login:successful", Time.now.utc)
+analytics.hour("login:successful", Time.now.utc)
+analytics.minute("login:successful", Time.now.utc)
+
+# Check event length
+today_events.length
+#=> 2
+
+# Check for existance
+today_events.include?(user.id)
+#=> true
+today_events.include?(admin.id)
+#=> false
+
+# Bulk check
+today_events.include?(User.all.map(&:id))
+#=> [true, true, false, false]
+```

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new("spec") do |t|
+  t.pattern = "test/**/*_test.rb"
+end
+
+task :default => [:test]
+task :test => [:spec]

data/lib/minuteman.rb

@@ -0,0 +1,84 @@
+require "redis"
+require "time"
+require "minuteman/time_events"
+
+# Until redis gem gets updated
+class Redis
+  def bitop(operation, destkey, *keys)
+    synchronize do |client|
+      client.call([:bitop, operation, destkey] + keys)
+    end
+  end
+
+  def bitcount(key, start = 0, stop = -1)
+    synchronize do |client|
+      client.call([:bitcount, key, start, stop])
+    end
+  end
+end
+
+class Minuteman
+  attr_reader :redis
+
+  PREFIX = "minuteman"
+
+  # Public: Initializes Minuteman
+  #
+  # options - The hash to be sent to Redis.new
+  #
+  def initialize(options = {})
+    @redis = Redis.new(options)
+  end
+
+  # Public: Generates the methods to fech data
+  #
+  #   event_name - The event name to be searched for
+  #   date       - A Time object used to do the search
+  #
+  %w[year month week day hour minute].each do |method_name|
+    define_method(method_name) do |event_name, date|
+      constructor = self.class.const_get(method_name.capitalize)
+      constructor.new(@redis, event_name, date)
+    end
+  end
+
+  # Public: Marks an id to a given event on a given time
+  #
+  #   event_name - The event name to be searched for
+  #   ids        - The ids to be tracked
+  #
+  # Examples
+  #
+  #   analytics = Minuteman.new
+  #   analytics.mark("login", 1)
+  #   analytics.mark("login", [2, 3, 4])
+  #
+  def mark(event_name, ids, time = Time.now.utc)
+    event_time = time.kind_of?(Time) ? time : Time.parse(time.to_s)
+    time_events = TimeEvents.start(redis, event_name, event_time)
+
+    @redis.multi do
+      time_events.each do |event|
+        Array(ids).each { |id| redis.setbit(event.key, id, 1) }
+      end
+    end
+  end
+
+  # Public: Resets the bit operation cache keys
+  #
+  def reset_operations_cache
+    prefix = [
+      PREFIX, Minuteman::BitOperations::BIT_OPERATION_PREFIX
+    ].join("_")
+
+    keys = @redis.keys([prefix, "*"].join("_"))
+    @redis.del(keys) if keys.any?
+  end
+
+  # Public: Resets all the used keys
+  #
+  def reset_all
+    keys = @redis.keys([PREFIX, "*"].join("_"))
+    @redis.del(keys) if keys.any?
+  end
+end

data/lib/minuteman/bit_operations.rb

@@ -0,0 +1,87 @@
+class Minuteman
+  module BitOperations
+    BIT_OPERATION_PREFIX = "bitop"
+
+    # Public: Checks for the existance of ids on a given set
+    #
+    #   ids - Array of ids
+    #
+    def include?(*ids)
+      result = ids.map { |id| redis.getbit(key, id) == 1 }
+      result.size == 1 ? result.first : result
+    end
+
+    # Public: Resets the current key
+    #
+    def reset
+      redis.rem(key)
+    end
+
+    # Public: Cheks for the amount of ids stored on the current key
+    #
+    def length
+      redis.bitcount(key)
+    end
+
+    # Public: Calculates the NOT of the current key
+    #
+    def -@
+      bit_operation("NOT", key)
+    end
+
+    # Public: Calculates the XOR against another timespan
+    #
+    #   timespan: Another BitOperations enabled class
+    #
+    def ^(timespan)
+      bit_operation("XOR", [key, timespan.key])
+    end
+
+    # Public: Calculates the OR against another timespan
+    #
+    #   timespan: Another BitOperations enabled class
+    #
+    def |(timespan)
+      bit_operation("OR", [key, timespan.key])
+    end
+
+    # Public: Calculates the AND against another timespan
+    #
+    #   timespan: Another BitOperations enabled class
+    #
+    def &(timespan)
+      bit_operation("AND", [key, timespan.key])
+    end
+
+    private
+
+    # Private: The destination key for the operation
+    #
+    #   type   - The bitwise operation
+    #   events - The events to permuted
+    #
+    def destination_key(type, events)
+      [
+        Minuteman::PREFIX,
+        BIT_OPERATION_PREFIX,
+        type,
+        events.join("-")
+      ].join("_")
+    end
+
+    # Private: Executes a bit operation
+    #
+    #   type   - The bitwise operation
+    #   events - The events to permuted
+    #
+    def bit_operation(type, events)
+      key = destination_key(type, Array(events))
+      @redis.bitop(type, key, events)
+      BitOperation.new(@redis, key)
+    end
+  end
+
+  class BitOperation < Struct.new(:redis, :key)
+    include BitOperations
+  end
+end

data/lib/minuteman/time_events.rb

@@ -0,0 +1,17 @@
+require "minuteman/time_spans"
+
+class Minuteman
+  module TimeEvents
+    # Public: Helper to get all the time trakers ready
+    #
+    #   redis      - The Redis connection
+    #   event_name - The event to be tracked
+    #   date       - A given Time object
+    #
+    def self.start(redis, event_name, time)
+      [Year, Month, Week, Day, Hour, Minute].map do |t|
+        t.new(redis, event_name, time)
+      end
+    end
+  end
+end

data/lib/minuteman/time_span.rb

@@ -0,0 +1,34 @@
+require "minuteman/bit_operations"
+
+class Minuteman
+  class TimeSpan
+    include BitOperations
+
+    attr_reader :key, :redis
+
+    DATE_FORMAT = "%s-%02d-%02d"
+    TIME_FORMAT = "%02d:%02d"
+
+    # Public: Initializes the base TimeSpan class
+    #
+    #   redis      - The Redis connection
+    #   event_name - The event to be tracked
+    #   date       - A given Time object
+    #
+    def initialize(redis, event_name, date)
+      @redis = redis
+      @key = build_key(event_name, time_format(date))
+    end
+
+    private
+
+    # Private: The redis key that's going to be used
+    #
+    #   event_name - The event to be tracked
+    #   date       - A given Time object
+    #
+    def build_key(event_name, date)
+      [Minuteman::PREFIX, event_name, date.join("-")].join("_")
+    end
+  end
+end

data/lib/minuteman/time_spans.rb

@@ -0,0 +1,7 @@
+require "minuteman/time_span"
+require "minuteman/time_spans/year"
+require "minuteman/time_spans/month"
+require "minuteman/time_spans/week"
+require "minuteman/time_spans/day"
+require "minuteman/time_spans/hour"
+require "minuteman/time_spans/minute"

data/lib/minuteman/time_spans/day.rb

@@ -0,0 +1,13 @@
+class Minuteman
+  class Day < TimeSpan
+    private
+
+    # Private: The format that's going the be used for the date part of the key
+    #
+    #   date       - A given Time object
+    #
+    def time_format(date)
+      [DATE_FORMAT % [date.year, date.month, date.day]]
+    end
+  end
+end

data/lib/minuteman/time_spans/hour.rb

@@ -0,0 +1,15 @@
+class Minuteman
+  class Hour < TimeSpan
+    private
+
+    # Private: The format that's going the be used for the date part of the key
+    #
+    #   date       - A given Time object
+    #
+    def time_format(date)
+      full_date = DATE_FORMAT % [date.year, date.month, date.day]
+      time = TIME_FORMAT % [date.hour, 0]
+      [full_date + " " + time]
+    end
+  end
+end

data/lib/minuteman/time_spans/minute.rb

@@ -0,0 +1,15 @@
+class Minuteman
+  class Minute < TimeSpan
+    private
+
+    # Private: The format that's going the be used for the date part of the key
+    #
+    #   date       - A given Time object
+    #
+    def time_format(date)
+      full_date = DATE_FORMAT % [date.year, date.month, date.day]
+      time = TIME_FORMAT % [date.hour, date.min]
+      [full_date + " " + time]
+    end
+  end
+end

data/lib/minuteman/time_spans/month.rb

@@ -0,0 +1,13 @@
+class Minuteman
+  class Month < TimeSpan
+    private
+
+    # Private: The format that's going the be used for the date part of the key
+    #
+    #   date       - A given Time object
+    #
+    def time_format(date)
+      [date.year, "%02d" % date.month]
+    end
+  end
+end

data/lib/minuteman/time_spans/week.rb

@@ -0,0 +1,14 @@
+class Minuteman
+  class Week < TimeSpan
+    private
+
+    # Private: The format that's going the be used for the date part of the key
+    #
+    #   date       - A given Time object
+    #
+    def time_format(date)
+      week = date.strftime("%W")
+      [date.year, "W" + week]
+    end
+  end
+end

data/lib/minuteman/time_spans/year.rb

@@ -0,0 +1,13 @@
+class Minuteman
+  class Year < TimeSpan
+    private
+
+    # Private: The format that's going the be used for the date part of the key
+    #
+    #   date       - A given Time object
+    #
+    def time_format(date)
+      [date.year]
+    end
+  end
+end

data/minuteman.gemspec

@@ -0,0 +1,15 @@
+Gem::Specification.new do |s|
+  s.name              = "minuteman"
+  s.version           = "0.0.1"
+  s.summary           = "Bit Analytics"
+  s.description       = "Fast and furious tracking system using Redis bitwise operations"
+  s.authors           = ["elcuervo"]
+  s.email             = ["yo@brunoaguirre.com"]
+  s.homepage          = "http://github.com/elcuervo/minuteman"
+  s.files             = `git ls-files`.split("\n")
+  s.test_files        = `git ls-files test`.split("\n")
+
+  s.add_dependency("redis", "~> 3.0.2")
+
+  s.add_development_dependency("minitest", "~> 4.1.0")
+end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+$:.unshift File.dirname(__FILE__) + '/../lib'
+
+require "bundler/setup"
+require "minitest/spec"
+require "minitest/pride"
+require "minitest/autorun"
+require "minuteman"

data/test/unit/minuteman_test.rb

@@ -0,0 +1,92 @@
+require_relative "../test_helper"
+
+describe Minuteman do
+  before do
+    @analytics = Minuteman.new
+
+    today = Time.now.utc
+    last_month = today - (3600 * 24 * 30)
+    last_week =  today - (3600 * 24 * 7)
+    last_minute = today - 61
+
+    @analytics.mark("login", 12)
+    @analytics.mark("login", [2, 42])
+    @analytics.mark("login", 2, last_week)
+    @analytics.mark("login:successful", 567, last_month)
+
+    @year_events   = @analytics.year("login", today)
+    @week_events   = @analytics.week("login", today)
+    @month_events  = @analytics.month("login", today)
+    @day_events    = @analytics.day("login", today)
+    @hour_events   = @analytics.hour("login", today)
+    @minute_events = @analytics.minute("login", today)
+
+    @last_week_events = @analytics.week("login", last_week)
+    @last_minute_events = @analytics.minute("login", last_minute)
+    @last_month_events = @analytics.month("login:successful", last_month)
+  end
+
+  after { @analytics.reset_all }
+
+  it "should initialize correctly" do
+    assert @analytics.redis
+  end
+
+  it "should track an event on a time" do
+    assert_equal 3, @year_events.length
+    assert_equal 3, @week_events.length
+    assert_equal 1, @last_week_events.length
+    assert_equal 1, @last_month_events.length
+    assert_equal [true, true, false], @week_events.include?(12, 2, 1)
+
+    assert @year_events.include?(12)
+    assert @month_events.include?(12)
+    assert @day_events.include?(12)
+    assert @hour_events.include?(12)
+    assert @minute_events.include?(12)
+
+    assert @last_week_events.include?(2)
+    assert !@month_events.include?(5)
+    assert !@last_minute_events.include?(12)
+    assert @last_month_events.include?(567)
+  end
+
+  it "should accept the AND bitwise operations" do
+    and_operation = @week_events & @last_week_events
+
+    assert @week_events.include?(2)
+    assert @week_events.include?(12)
+
+    assert @last_week_events.include?(2)
+    assert !@last_week_events.include?(12)
+
+    assert_equal 1, and_operation.length
+
+    assert !and_operation.include?(12)
+    assert and_operation.include?(2)
+  end
+
+  it "should accept the OR bitwise operations" do
+    or_operation = @week_events | @last_week_events
+
+    assert @week_events.include?(2)
+    assert @last_week_events.include?(2)
+    assert !@last_week_events.include?(12)
+
+    assert_equal 3, or_operation.length
+
+    assert or_operation.include?(12)
+    assert or_operation.include?(2)
+  end
+
+  it "should accept the NOT bitwise operations" do
+    not_operation = -@week_events
+
+    assert @week_events.include?(2)
+    assert @week_events.include?(12)
+
+    assert !not_operation.include?(12)
+    assert !not_operation.include?(2)
+  end
+
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: minuteman
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- elcuervo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.2
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+description: Fast and furious tracking system using Redis bitwise operations
+email:
+- yo@brunoaguirre.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- lib/minuteman.rb
+- lib/minuteman/bit_operations.rb
+- lib/minuteman/time_events.rb
+- lib/minuteman/time_span.rb
+- lib/minuteman/time_spans.rb
+- lib/minuteman/time_spans/day.rb
+- lib/minuteman/time_spans/hour.rb
+- lib/minuteman/time_spans/minute.rb
+- lib/minuteman/time_spans/month.rb
+- lib/minuteman/time_spans/week.rb
+- lib/minuteman/time_spans/year.rb
+- minuteman.gemspec
+- test/test_helper.rb
+- test/unit/minuteman_test.rb
+homepage: http://github.com/elcuervo/minuteman
+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.23
+signing_key: 
+specification_version: 3
+summary: Bit Analytics
+test_files:
+- test/test_helper.rb
+- test/unit/minuteman_test.rb