btrack 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b730fa2c3a34a3116f0b94591f528443855121f1
+  data.tar.gz: 6ce8856176cd93b9c372e07f61a5380ee0a6e67a
+SHA512:
+  metadata.gz: da1feb3673a195c82b6e8a0cde1006688462b8866fee09587da5dc061c8ac7661a4f99bd753230f103103d309785c45c1e8aadff34a527baa83800ce2e136ad8
+  data.tar.gz: 4b86399ba364d3224f51189a88ec09473e88f4633785c017383f6424ad6325427fe20176a760b66ceb170ba4fc8c21cbed6c5aa8495021f0012f586328b22c27

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/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.ruby-version

@@ -0,0 +1 @@
+2.1.1

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Chen Fisher
+
+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,323 @@
+# Btrack
+
+**Btrack** is an activity tracker with extensive query mechanism, minimum memory footprint and maximum performance (thanks to redis)
+
+With **Btrack** you can track any activity of any entity in your website or process
+
+#### Tracking user logins (user 123 has just logged in):
+```ruby
+Btrack.track :logged_in, 123
+```
+
+#### Query for total logins:
+```ruby
+Btrack.where(logged_in: :today).count
+```
+
+#### Query if a specific user visited your website last month:
+```ruby
+Btrack.where(visited: :last_month).exists? 123
+
+# use a cool shortcut
+Btrack::Query.visited? 123, :today
+```
+
+#### You can also plot a graph!
+``` ruby
+Btrack.where(clicked_a_button: 1.week.ago..Time.now).plot
+#=> {2014-07-14 00:00:00 +0300=>10, 2014-07-14 00:00:00 +0300=>5, 2014-07-14 00:00:00 +0300=>30...
+```
+
+#### Cohort analysis (for example, all users that signed in last week and visited this week )
+```ruby
+Btrack.where([{signed_in: :last_week}, {visited: :this_week}]).plot
+```
+
+# Background
+**Btrack** uses Redis bitmaps to track activities over entities; you can track millions of users with a very small memory footprint and use bitwise operators to determine complex queries in realtime.
+
+See relevant Redis commands for bitmaps here:
+[http://redis.io/commands/SETBIT]
+
+Read this to better understand how bitmaps work in redis and how you can use it for fast, realtime analytics: [http://blog.getspool.com/2011/11/29/fast-easy-realtime-metrics-using-redis-bitmaps/]
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'btrack'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install btrack
+
+## Usage
+
+## Tracking
+Basic tracking is done by specifying the event to track (can be a string or a symbol) and the id of the entity you are tracking (**must** be an interger)
+
+User with id 123 purchased something:
+```ruby
+Btrack.track "user:purchased", 123
+```
+Item with id 1001 was just purchased:
+```ruby
+Btrack.track "item:purchased", 1001
+```
+
+### Granularity
+When tracking an event a default granularity is used (see **configuration** section for more details on default values);  the default granularity is :hourly..:monthly, which means :hourly, :daily, :weekly and :monthly
+
+To track with a different granualrity:
+```ruby
+# track with a weekly granularity
+Btrack.track :logged_in, 123, :weekly
+
+# track with both daily and weekly granularity:
+Btrack.track :logged_in, 123, [:daily, :weekly]
+
+# track with a range of granularities:
+Btrack.track :logged_in, 123, :hourly..:monthly
+#=> will track with: hourly, daily, weekly and monthly
+```
+
+Available granularities: [:minute, :hourly, :daily, :weekly, :monthly, :yearly]
+
+
+#### CAVEATS with granularities
+You should be aware that there is a close relation between tracking and querying in regards to granularities. see **querying/granularity** section for more details.
+
+
+```ruby
+# track with daily granularity
+Btrack.track :logged_in, 123, :daily
+
+# query with weekly granualrity:
+Btrack.where [{logged_in: :today, granularity: :weekly}]
+#=> returns 0
+
+# tracking with a range of granularities:
+Btrack.track :logged_in, 123, :daily..:monthly
+
+# now querying with weekly granularity is OK because it is included in the range:
+Btrack.where [{logged_in: :today, granularity: :weekly}]
+#=> returns 1
+```
+### Tracking with a block
+You can track with a block for convenience and for specifying other tracking options:
+
+```ruby
+Btrack::Tracker.track do |b|
+  b.key = "logged_in"
+  b.id = 123
+  b.granularity = :daily..:monthly
+  b.when = 3.days.ago # when was this event occured
+  b.expiration_for = { daily:6.days } # specify expiration for this event
+end
+```
+
+### Tracking in the past tense
+When tracking an event, the default time is ```Time.now``` which means: the event just happend.
+
+You can specify a different time when tracking an event:
+```ruby
+Btrack::Tracker.track do |b|
+  b.key = :logged_in
+  b.id = 123
+  b.when = 3.days.ago # this event happened 3 days ago
+end
+```
+
+### Expiration time
+You can specity retention for events per granularity. Use this to get rid of granularities you don't need any more and save memory (in redis)
+
+```ruby
+Btrack::Tracker.track do |b|
+  b.key = :logged_in
+  b.id = 123
+  b.expiration_for = { minute: 3.days, daily: 3.months } 
+  # after 3 days all "minute" granularities for this event will be deleted 
+  # and 3 months later all the relevant "daily" granularities will be deleted
+end
+```
+
+## Querying
+
+```ruby
+# Simple querying
+Btrack.where(logged_in: :today).count
+Btrack.where(logged_in: :yesteday).count
+Btrack.where(logged_in: :last_week).count
+
+# Query with a time range
+Btrack.where(logged_in: 3.days.ago..Time.now).count
+```
+
+`Btrack.where` has the following form: `where(criteria, options={})`
+
+**criteria** is an array of hashes, where each hash is the event to query and relevant optional options of that event (don't worry, there are plentty of examples in this section; just make sure to wrap the criteria with array and proper hashes when querying for more than one event or when specifying a granularity for an event)
+
+**options={}** is preserved for feature use and is meant for specifying options that are not event specific
+
+### Querying for a specific user/entity
+```ruby
+Btrack.where(logged_in: :today).exists? 123
+#=> returns true if user 123 logged in today
+
+Btrack.where(visited: 7.days.ago..Time.now)exists? 123
+#=> returns true if user 123 visited the website in the past 7 days
+
+# You can use a cool shortcut to query for a specific user:
+Btrack::Query.visited? 123, 7.days.ago..Time.now
+#=> same as above, but with a cool shortcut
+
+Btrack::Query.logged_in? 123, :today
+#=> true/false
+```
+### Lazyness
+Queries are not "realized" until you perform an action:
+```ruby
+a_query = Btrack.where [logged_in: 1.week.ago..Time.now, granularity: :daily]
+#=> <Btrack::Query::Criteria:0x007fceb248e120 @criteria=[{:logged_in=>:today}], @options={}>
+
+a_query.count
+#=> 3
+
+a_query.exists? 123
+#=> true
+
+a_query.plot
+#=> {2014-07-01 00:00:00 +0300=>10, 2014-07-01 00:00:00 +0300=>5...
+
+# You can use the "realize!" action to see what's under the hood
+a_query.realize!
+#=> [["btrack:logged_in:2014-07-11", "btrack:logged_in:2014-07-12", "btrack:logged_in:2014-07-13"...
+```
+
+### Intersection (querying for multiple events)
+You can query for multiple events
+```ruby
+# signed in AND purchased something this month
+q = Btrack.where([{signed_in: :this_month}, {purchased: :this_month}])
+
+q.count
+q.exists? 123
+q.plot
+
+# logged last week AND logged in today
+Btrack.where([{logged_in: :last_week}, {logged_in: :today}])
+
+# signed in the last 30 days, logged in this week and purchased something
+Btrack.where([{signed_in: 30.days.ago..Time.now}, {logged_in: :last_week}, {purchased_something: :this_month}])
+```
+
+#### The & operator
+You can use `&` for intersection
+```ruby
+signed_in = Btrack.where signed_in: 30.days.ago..Time.now
+visited = Btrack.where visited: 7.days.ago..Time.now
+
+signed_in_AND_visited = signed_in & visited
+signed_in_visited_and_whatever = signed_in_AND_visited & Btrack.where(whatever: :today)
+```
+
+### Granularity
+When querying, you should make sure you are tracking in the same granularity. If you are tracking in the range of :daily..:monthly then you can only query in that range (or you will get wrong results)
+
+To specify the granualrity when querying, add a :granualrity key to the hash (per event):
+
+```ruby
+Btrack.where([{clicked_a_button: 3.hours.ago..Time.now, granularity: :hourly}])
+
+# granularity is per event:
+Btrack.where([{logged_in: 1.hour.ago..Time.now, granularity: :minute}, {did_something: :today, granularity: :daily}])
+
+# see the next section (plotting) about granularity when plotting a graph
+```
+
+Another possible error you should be aware of is when querying for a timeframe that is not correlated with the granularity:
+
+```ruby
+# timeframe is :today, while granularity is :weekly
+Btrack.where([{logged_in: :today, granularity: :weekly}])
+# this will result in wrong results because :weekly granularity will refer
+# to the whole week, while you probably meant to query only :today
+```
+
+
+> Default granularity when querying is the highest resolution set in configuration.default_granularity (:hourly..:monthly => :hourly is the default when querying)
+
+## Plotting
+Use `plot` to plot a graph
+```ruby
+# plot a graph with a daily resolution (granularity)
+Btrack.where([{logged_in: 30.days.ago..Time.now, granularity: :daily}]).plot
+
+# plot a graph with an hourly resolution
+Btrack.where([{logged_in: 30.days.ago..Time.now, granularity: :hourly}]).plot
+```
+
+### Cohort
+You can use what you've learned so far to create a cohort analysis
+```ruby
+visits = Btrack.where [visited: 30.days.ago..Time.now, granularity: :daily]
+purchases = Btrack.where [purchased_something: 30.days.ago..Tome, granularity: :daily]
+
+visits_and_purchases = visits & purchases
+
+# now plot a cohort
+visits_and_purchases.plot
+#=> {2014-07-01 00:00:00 +0300=>10, 2014-07-01 00:00:00 +0300=>20, ...
+
+# NOTE that when plotting multiple events (cohort), the returned keys for the plot are named after the first event
+```
+
+## Configuration
+Put this in an `initializer` to configure **Btrack**
+```ruby
+Btrack.config do |config|
+  config.namespace = 'btrack' # default namespace for redis keys
+  config.redis_url = nil # redis url to use; defaults to nil meaning localhost and default redis port
+  config.expiration_for = {minute: 1.day, hourly: 1.week, daily: 3.months, weekly: 1.year, monthly: 1.year, yearly: 1.year}
+  config.default_granularity: :daily..:monthly # default granularities when tracking
+  config.silent = false # to break or not to break on redis errors
+end
+```
+
+### namespace
+Sets the namespace to use for the keys in redis; defaults to **btrack**
+
+> keys in redis look like this: `btrack:logged_in:2014-07-15`
+> 
+>and in a general form: `namespace:event:datetime`
+
+### expiration_for
+Use expiration_for to set the expiration for a specific granularity
+```ruby
+Btrack.config.expiration_for = { daily: 7.months }
+# will merge :daily expiration with the whole expirations hash
+# {minute: 1.day, hourly: 1.week, daily: 7.months, weekly: 1.year, monthly: 1.year, yearly: 1.year}
+```
+### redis_url
+Sets the connection url to the redis server; defaults to nil which means localhost and default redis port
+
+## Alternatives
+[Minuteman](https://github.com/elcuervo/minuteman) is a nice alternative to **Btrack** but with the following caveats (and more):
+
+1. It does not support time frames (you cannot query for 30.days.ago..Time.now)
+2. It eagerly creates a redis key on every bitwise operator, while **Btrack** is lazy
+3. It uses redis `multi` while **Btrack** uses `lua` for better performance
+4. No plot option in Minuteman
+
+## 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

data/Rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')

data/btrack.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'btrack/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "btrack"
+  spec.version       = Btrack::VERSION
+  spec.authors       = ["Chen Fisher"]
+  spec.email         = ["chen.fisher@gmail.com"]
+  spec.description   = %q{Enables tracking and querying of any activity in a website or process with minimum memory signature and maximum performance (thanks to redis)}
+  spec.summary       = %q{Activity tracker with minimum memory footprint and maximum performance (thanks to redis)}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport"
+  spec.add_dependency "redis"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "wrong"
+end

data/lib/btrack.rb

@@ -0,0 +1,24 @@
+require 'active_support/all'
+require "btrack/version"
+require "btrack/helper"
+require "btrack/config"
+require "btrack/time_frame"
+require "btrack/redis"
+require "btrack/tracker"
+require "btrack/query"
+
+module Btrack
+  extend self
+
+  delegate :where, to: Query
+  delegate :track, to: Tracker 
+
+  def redis
+    @redis ||= Btrack::Redis.create
+  end
+
+  def config
+    yield Btrack::Config if block_given?
+    Btrack::Config
+  end
+end

data/lib/btrack/config.rb

@@ -0,0 +1,28 @@
+module Btrack
+  class Config
+
+    @config = OpenStruct.new ({
+          namespace: "btrack",
+          redis_url: nil, # nil means localhost with defailt redis port
+          expirations: {minute: 1.day, hourly: 1.week, daily: 3.months, weekly: 1.year, monthly: 1.year, yearly: 1.year},
+          default_granularity: :hourly..:monthly,
+          silent: false # to break or not to break (on redis errors); that is the question
+        })
+
+    class << self
+
+      def expiration_for(g)
+        @config[:expirations][g]
+      end
+
+      def expiration_for=(g)
+        @config[:expirations].merge!(g)
+      end
+
+      def method_missing(method, *args, &block)
+        @config.send(method, *args, &block)
+      end
+
+    end
+  end
+end

data/lib/btrack/helper.rb

@@ -0,0 +1,25 @@
+module Btrack
+  class Helper
+
+    class << self
+      def key(k, g=Config.default_granularity, w=Time.now)
+        "#{Config.namespace}:#{k}:#{granularity g, w || Time.now}"
+      end
+
+      def keys(k, timeframe)
+        tf = timeframe.is_a?(TimeFrame) ? timeframe : (TimeFrame.new timeframe)
+        tf.splat { |t| key k, tf.granularity, t}
+      end
+
+      def granularity(g=:daily, w=Time.now)
+        return g unless [:minute, :hourly, :daily, :weekly, :monthly, :yearly].include? g
+        w.strftime(format(g))
+      end
+
+      def format(g)
+        { minute: "%Y-%m-%d-%H-%M", hourly: "%Y-%m-%d-%H", daily: "%Y-%m-%d", weekly: "%G-W%V", monthly: "%Y-%m", yearly: "%Y"}[g] || "%Y-%m-%d"
+      end
+    end
+
+  end
+end

data/lib/btrack/query.rb

@@ -0,0 +1,45 @@
+require 'btrack/query/criteria'
+require 'btrack/query/lua'
+
+module Btrack
+  class Query
+    attr_reader :criteria
+
+    delegate :with_sha, :with_silent, to: Btrack::Redis
+
+    class << self
+      delegate :where, to: Criteria
+    end
+
+    def initialize(criteria = nil)
+      @criteria = criteria.freeze
+    end
+
+    def count
+      with_silent { with_sha { [lua(:count), *@criteria.realize!] } }
+    end
+
+    def exists?(id = nil)
+      c = id ? @criteria.where([], id: id) : @criteria
+      with_silent { with_sha { [lua(:exists), *c.realize!] }  == 1 }
+    end
+
+    def plot
+      JSON.parse(with_silent { with_sha { [plot_lua, *@criteria.realize!] } }).inject({}) do |n, (k, v)|
+        g = @criteria.criteria.first[:granularity] || Criteria.default_granularity
+        key = Time.strptime(k.rpartition(":").last, Helper.format(g))
+        n[key] = v
+        n
+      end
+    rescue
+      nil
+    end
+
+    class << self
+      def method_missing(method, *args, &block)
+        return unless method.to_s.end_with? '?'
+        Criteria.where({method.to_s.chomp('?') => args[1]}.merge(args.extract_options!), id: args[0]).exists?
+      end
+    end
+  end
+end

data/lib/btrack/query/criteria.rb

@@ -0,0 +1,62 @@
+require 'btrack/helper'
+require 'btrack/time_frame'
+
+module Btrack
+  class Query
+    class Criteria
+      attr_reader :options, :criteria
+      delegate :count, :exists?, :plot, to: :query
+
+      # initializes a new crieteria
+      def initialize(criteria, options={})
+        @criteria = parse(criteria).freeze
+        @options = options.freeze
+      end
+
+      # returns a new criteria object with the union of both criterias
+      def where(*args)
+        self & Criteria.new(*args)
+      end
+
+      # returns a new criteria object with the union of both criterias
+      def &(criteria)
+        Criteria.new self.criteria + criteria.criteria, self.options.merge(criteria.options)
+      end
+
+      # make this criteria 'real' by extracting keys and args to be passed to redis lua script
+      def realize!
+        prefix = "#{@options[:prefix]}:" if @options[:prefix]
+
+        keys = @criteria.map do |c|
+          cvalue = c.values.first
+          (Helper.keys "#{prefix}#{c.keys.first}", TimeFrame.new(cvalue, c[:granularity] || (cvalue.granularity if cvalue.is_a? TimeFrame) || self.class.default_granularity)).flatten
+        end
+
+        [keys.flatten << @options[:id], keys.map(&:count)]
+      end
+
+      # access methods from class instance
+      # returns a new criteria instance
+      class << self
+        def where(*args)
+          Criteria.new *args
+        end
+
+        def default_granularity
+          Config.default_granularity.is_a?(Range) ? Config.default_granularity.first : Array.wrap(Config.default_granularity).first
+        end
+      end
+
+      # delegate method
+      def query
+        Query.new self
+      end
+
+      private
+
+        def parse(criteria)
+          criteria.is_a?(Array) ? criteria : criteria.map { |k, v| {k => v} }
+        end
+    end
+  end
+end

data/lib/btrack/query/lua.rb

@@ -0,0 +1,74 @@
+module Btrack
+  class Query
+	  def lua(f)
+	    %Q{
+	      local index = 1
+
+	      for i, count in ipairs(ARGV) do
+	        if count == '0' then
+	          break
+	        end
+
+	        local bitop = {}
+
+	        for c = index, index * count do
+	          table.insert(bitop, KEYS[c])
+	          index = index + 1
+	        end
+
+	        if i == 1 then
+	          redis.call('bitop', 'or', 'tmp', unpack(bitop))
+	        else
+	          redis.call('bitop', 'or', 'tmp:or', unpack(bitop))
+	          redis.call('bitop', 'and', 'tmp', 'tmp', 'tmp:or')
+	          redis.call('del', 'tmp:or')
+	        end
+	      end
+
+	      #{send('lua_' + f.to_s)}
+
+	      redis.call('del', 'tmp')
+	      return results
+	    }          
+	  end
+
+	  def lua_count
+	    "local results = redis.call('bitcount', 'tmp')"
+	  end
+
+	  def lua_exists
+	    "local results = redis.call('getbit', 'tmp', KEYS[#KEYS])"
+	  end
+
+	  # lua script for plotting
+	  # please note - it cannot be used with the prefixed 'lua' like count and exists
+	  # this is a standalone script ment for plotting and allowing for cohort analysis
+	  # all series must be of the same size
+	  def plot_lua
+	    %Q{
+	      local series_count = #ARGV
+	      local length = ARGV[1]
+
+	      -- run over the first series
+	      -- all series must be of the same size
+	      local plot = {}
+	      for i = 1, length do
+	        local bitop = {}
+	        for j = 1, series_count do
+	          table.insert(bitop, KEYS[i*j])
+	        end
+
+	        -- make sure 'tmp' is populated with the first key (so the 'and' op would work as expected)
+	        redis.call('bitop', 'or', 'tmp', 'tmp', bitop[1])
+
+	        redis.call('bitop', 'and', 'tmp', unpack(bitop))
+	        -- table.insert(plot, redis.call('bitcount', 'tmp'))
+	        plot[KEYS[i]] = redis.call('bitcount', 'tmp')
+	        redis.call('del', 'tmp')
+	      end
+
+	      return cjson.encode(plot)
+	    }          
+	  end
+	end
+end

data/lib/btrack/redis.rb

@@ -0,0 +1,30 @@
+require 'redis'
+require 'btrack/config'
+
+module Btrack
+  class Redis
+    class << self
+      def create
+        (::Redis.new url: Config.redis_url if Config.redis_url) || ::Redis.new
+      end
+
+	    def with_silent(&block)
+	      yield if block
+	    rescue ::Redis::BaseError => e
+	      raise e unless Config.silent
+	    end
+
+	    def with_sha(&block)
+	    	params = yield; script = params.shift
+	    	Btrack.redis.evalsha sha(script), *params
+	    rescue ::Redis::CommandError => e
+	      raise unless e.message.start_with?("NOSCRIPT")
+	      Btrack.redis.eval script, *params
+	    end
+
+	    def sha(script)
+	    	Digest::SHA1.hexdigest(script)
+	    end
+    end
+  end
+end

data/lib/btrack/time_frame.rb

@@ -0,0 +1,63 @@
+module Btrack
+  class TimeFrame
+    attr_reader :from, :to, :granularity
+
+    def initialize(timeframe, granularity=nil)
+      raise ArgumentError, "TimeFrame should be initialized with Symbol, Hash, Range or Btrack::TimeFrame" unless [Symbol, Hash, Range, TimeFrame, Time].include? timeframe.class
+
+      @from, @to = self.send("init_with_#{timeframe.class.name.demodulize.underscore}", timeframe)
+      @granularity = granularity || (timeframe.granularity if timeframe.is_a?(TimeFrame)) || Config.default_granularity
+    end
+
+    def splat(granularity=self.granularity)
+      [].tap do |keys|
+        (from.to_i .. to.to_i).step(step(granularity)) do |t|
+          keys << (block_given? ? (yield Time.at(t)) : Time.at(t))
+        end
+      end
+    end
+
+    private
+      def init_with_time_frame(timeframe)
+        [timeframe.from, timeframe.to]
+      end
+
+      def init_with_time(time)
+        [time.beginning_of_day, time.end_of_day]
+      end
+
+      def init_with_symbol(timeframe)
+        case timeframe
+        when :hour, :day, :week, :month, :year
+          return 1.send(timeframe).ago, Time.now
+        when :today
+          return Time.now.beginning_of_day, Time.now
+        when :yesterday
+          return 1.day.ago.beginning_of_day, 1.day.ago.end_of_day
+        when :this_week
+          return Time.now.beginning_of_week, Time.now
+        when :last_week
+          return 1.week.ago.beginning_of_week, 1.week.ago.end_of_week
+        when :this_month
+          return Time.now.beginning_of_month, Time.now
+        when :last_month
+          return 1.month.ago.beginning_of_month, 1.month.ago.end_of_month
+        else
+          return 1.day.ago, Time.now
+        end
+      end
+
+      def init_with_hash(timeframe)
+        [timeframe[:from] && timeframe[:from].is_a?(String) && Time.parse(timeframe[:from]) || timeframe[:from] || 1.month.ago,
+        timeframe[:to] && timeframe[:to].is_a?(String) && Time.parse(timeframe[:to]) || timeframe[:to] || Time.now]
+      end
+
+      def init_with_range(timeframe)
+        init_with_hash(from: timeframe.first, to: timeframe.last)
+      end
+
+      def step(g)
+        {minute: 1.minute, hourly: 1.hour, daily: 1.day, weekly: 1.week, monthly: 1.month, yearly: 1.year}[g] || 1.day
+      end
+  end
+end

data/lib/btrack/tracker.rb

@@ -0,0 +1,68 @@
+module Btrack
+  class Tracker
+    class << self
+      #
+      # Tracks an activity of an entity
+      # 
+      # For example: User 123 has just logged in
+      # Btrack::Tracker.track :logged_in, 123
+      #
+      # Can be called in 3 different ways (for convenience): with args, hash or a block
+      #
+      # Example Using a block
+      #   Btrack::Tracker.track do |b|
+      #     b.key = "logged_in"
+      #     b.id = 123
+      #     b.granularity = :daily..:monthly
+      #     b.when = 3.days.ago
+      #     b.expiration_for = { daily:6.days }
+      #   end
+      #
+      # See documentation for full details on args and options
+      def track(*args, &block)
+        return track_with_block(&block) if block_given?
+        return track_with_hash if args.first === Hash
+
+        track_with_args(*args)
+      end
+
+      private
+
+        def track_with_hash(options)
+          granularity_range(options[:granularity] || Config.default_granularity).each do |g|
+            key = Helper.key options[:key], g, options[:when]
+
+            Btrack::Redis.with_silent do
+              Btrack.redis.pipelined do |r|
+                r.setbit key, options[:id].to_i, 1
+                r.expire key, options[:expiration_for] && options[:expiration_for][g] || Config.expiration_for(g)
+              end
+            end
+          end
+        end
+
+        def track_with_block
+          yield options = OpenStruct.new
+
+          track_with_hash options
+        end
+
+        def track_with_args(*args)
+          options = args.extract_options!.merge ({
+            key: args[0],
+            id: args[1],
+            granularity: args[2]
+          })
+
+          track_with_hash options
+        end
+
+        def granularity_range(granularities)
+          return [granularities].flatten unless granularities.is_a? Range
+          predefined[predefined.index(granularities.first)..predefined.index(granularities.last)]
+        end
+
+        def predefined; [:minute, :hourly, :daily, :weekly, :monthly, :yearly]; end
+    end
+  end
+end

data/lib/btrack/version.rb

@@ -0,0 +1,3 @@
+module Btrack
+  VERSION = "1.0.1"
+end

data/spec/btrack_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe Btrack do
+
+end

data/spec/config_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe Btrack::Config do
+
+	Btrack.config do |config|
+		config.namespace = "test"
+	end
+
+	it "sets a namespace" do
+		assert { Btrack::Helper.key(:logged_in).starts_with? "test" }
+	end
+
+	it "sets expiration time" do
+		expected = Btrack.config.expirations.dup
+		Btrack.config.expiration_for = {weekly: 2.days}
+
+		assert { Btrack.config.expirations == expected.merge(weekly: 2.days) }
+	end
+end

data/spec/query_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+describe Btrack::Query do
+
+	before :each do
+	  10.times do |i|
+	    Btrack.track :logged_in, i, :hourly..:monthly # [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+	    Btrack.track :logged_in, i*2, when: 1.days.ago # [0, 2, 4, 6, 8, 10, 12, 14, 16, 18]
+
+	    Btrack.track :visited, i if i%3 == 0 # [0, 3, 6, 9]
+	  end
+	end
+
+
+  it "returns count of unique logins for today" do
+    assert { Btrack.where(logged_in: :today).count == 10 }
+  end
+
+  it "returns count of unique logins yesterday" do
+    assert { Btrack.where(logged_in: :yesterday).count == 10 }
+  end
+
+  it "returns count of unique logins in a range of time" do
+    assert { Btrack.where(logged_in: 1.days.ago..Time.now).count == 15 }
+  end
+
+  it "returns count with weekly granularity" do
+  	assert { Btrack.where([{logged_in: :this_week, granularity: :weekly}]).count == 15 }
+	end
+
+	it "returns the intersection of two different time frames" do
+  	assert { Btrack.where([{logged_in: :today}, {logged_in: :yesterday}]).count == 5 }
+	end
+
+	it "returns the intersection of two different activities" do
+  	assert { Btrack.where([{logged_in: :yesterday}, {visited: :today}]).count == 2 }
+	end
+
+  it "check if id exists in activity" do
+    assert { Btrack.where(logged_in: :today).exists? 5 }
+  end
+
+  it "checks if id did two activities (intersection)" do
+  	assert { Btrack.where([{logged_in: :yesterday}, {visited: :today}], id: 6).exists? }
+  end
+
+  it "should return false for id that does not satisfies an intersection" do
+  	assert { Btrack.where([{logged_in: :yesterday}, {visited: :today}], id: 3).exists? == false }
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+require 'rubygems'
+require 'bundler/setup'
+require "wrong/adapters/rspec"
+require 'btrack'
+
+RSpec.configure do |config|
+  config.before :each do
+    Btrack.redis.select 15
+    Btrack.redis.flushdb
+  end
+end
+
+def is_set(key, id, granularity = :daily, w = Time.now)
+	Btrack.redis.getbit(Btrack::Helper.key(key, granularity, w), id) == 1
+end
+
+def ttl(key, id, granularity = :daily, w = Time.now)
+	Btrack.redis.ttl(Btrack::Helper.key(key, granularity, w))
+end

data/spec/time_frame_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe Btrack::TimeFrame do
+  it "accepts time as from and to" do
+    tf = Btrack::TimeFrame.new from: 10.days.ago, to: Time.now
+    tf.from.to_i.should eq 10.days.ago.to_i
+    tf.to.to_i.should eq Time.now.to_i
+  end
+
+  it "accepts range as from and to" do
+    tf = Btrack::TimeFrame.new 10.days.ago..Time.now
+    tf.from.to_i.should eq 10.days.ago.to_i
+    tf.to.to_i.should eq Time.now.to_i
+  end
+end

data/spec/tracker_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'btrack/helper'
+
+describe Btrack::Tracker do
+
+  it "tracks with basic args" do
+    Btrack::Tracker.track("logged_in", 123, :weekly)
+    assert { is_set "logged_in", 123, :weekly }
+  end
+
+  it "tracks with default granularity" do
+    Btrack::Tracker.track("logged_in", 123)
+    assert { is_set "logged_in", 123 }
+  end
+
+  it "accepts symbol as key" do
+    Btrack::Tracker.track(:logged_in, 123)
+    assert { is_set :logged_in, 123 }
+  end
+
+  it "accepts different time (past activity)" do
+    Btrack::Tracker.track(:logged_in, 123, :daily, when: 3.days.ago)
+    assert { is_set :logged_in, 123, :daily, 3.days.ago }
+  end
+
+  it "track with expiration time set" do
+    Btrack::Tracker.track(:logged_in, 123, :daily, expiration_for: { daily: 9.days })
+    assert { ttl(:logged_in, 123, :daily) == 9.days }
+  end
+
+  it "tracks with a block" do
+    Btrack::Tracker.track do |t|
+      t.key = :logged_in
+      t.id = 123
+      t.granularity = :weekly
+      t.when = 2.days.ago
+    end
+
+    assert { is_set :logged_in, 123, :weekly, 2.days.ago }
+  end
+
+end

metadata

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: btrack
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Chen Fisher
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: wrong
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Enables tracking and querying of any activity in a website or process
+  with minimum memory signature and maximum performance (thanks to redis)
+email:
+- chen.fisher@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- btrack.gemspec
+- lib/btrack.rb
+- lib/btrack/config.rb
+- lib/btrack/helper.rb
+- lib/btrack/query.rb
+- lib/btrack/query/criteria.rb
+- lib/btrack/query/lua.rb
+- lib/btrack/redis.rb
+- lib/btrack/time_frame.rb
+- lib/btrack/tracker.rb
+- lib/btrack/version.rb
+- spec/btrack_spec.rb
+- spec/config_spec.rb
+- spec/query_spec.rb
+- spec/spec_helper.rb
+- spec/time_frame_spec.rb
+- spec/tracker_spec.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Activity tracker with minimum memory footprint and maximum performance (thanks
+  to redis)
+test_files:
+- spec/btrack_spec.rb
+- spec/config_spec.rb
+- spec/query_spec.rb
+- spec/spec_helper.rb
+- spec/time_frame_spec.rb
+- spec/tracker_spec.rb
+has_rdoc: