retained 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f5d6bcae30957db9c68732ac86d8ecaab0b87b8
-  data.tar.gz: 7f9cd05317be943e80db30d0400f2e846c3953c9
+  metadata.gz: c5889b1f2f5d17776a5955402abf0bb72a628c1b
+  data.tar.gz: d0e5963b0989d0bdf257b4f6b1be551538dec580
 SHA512:
-  metadata.gz: 5d4b7f865769cf26c8cf23f6863d9fc297319d02a95e2fba2e9012b4189e73a7440ea7b259da38f30f3d42348735b4f8880f6ad5dab2a9fee9fcc03e3de0518c
-  data.tar.gz: da5f936e390f57a603f216c38dac7fb488b5cb81ecb46056b20b8500aea8a85edc90f0869ac8bd13693187184c2c9938360afa631a11a26c3102269eb4e6bba2
+  metadata.gz: 62d5f2c52a6286581a4924a3f23df5918450345e40088e3c0d012b24a9a53d3c505cd0199d0c93fb4a590237ad6e80f42b64a3821844defed9f81d83cb59d703
+  data.tar.gz: 9279624e9cc42bf400675110ddecddf97cba3c8436880abe5e17e571a7a6b0a9f728b02bd2611cd632ce55184cbdf983320a94c72063d03e1920a41ed7f50819

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.2.2
+
+  * Fixed default group.  Was erroneously using an empty string
+  instead of the string 'default'.
+  * Added unique_active method
+
 # 0.2.1
 
   * Fixed ActiveSupport require declaration

data/Gemfile

@@ -1,7 +1,7 @@
 source 'http://rubygems.org'
 
 gem 'redis', '~> 3.1.0'
-gem 'redis-bitops', '~> 0.2.1'
+gem 'redis-bitops', github: 'msaffitz/redis-bitops', branch: 'watch_keys_fix'
 gem 'activesupport'
 
 group :development do

data/Gemfile.lock

@@ -1,3 +1,11 @@
+GIT
+  remote: git://github.com/msaffitz/redis-bitops.git
+  revision: a82f1bdc809e843ff297bcaf4c7664d3fc461772
+  branch: watch_keys_fix
+  specs:
+    redis-bitops (0.2.1)
+      redis
+
 GEM
   remote: http://rubygems.org/
   specs:
@@ -55,8 +63,6 @@ GEM
     rdoc (3.12.2)
       json (~> 1.4)
     redis (3.1.0)
-    redis-bitops (0.2.1)
-      redis
     simplecov (0.9.0)
       docile (~> 1.1.0)
       multi_json
@@ -78,7 +84,7 @@ DEPENDENCIES
   minitest
   rdoc (~> 3.12)
   redis (~> 3.1.0)
-  redis-bitops (~> 0.2.1)
+  redis-bitops!
   simplecov
   timecop (~> 0.7.1)
   yard (~> 0.7)

data/README.md

@@ -12,15 +12,15 @@ Retained makes it easy to track activity and retention at scale in daily, hourly
 
 Use RubyGems to install Retained:
 
-	$ gem install retained
-	
+    $ gem install retained
+
 If you are using Bundler, you can also install it by adding it to your Gemfile:
 
-	gem 'retained'
-	
+    gem 'retained'
+
 Run `bundle install` to install.
 
-## Basic Usage 
+## Basic Usage
 
 Retained works by tracking whether an **entity** was active within a reporting interval for a specific **group**. Entities can be anything you wish to track activity for, and are identified by a unique identifier that you provide to Retained.  Groups provide a scope for the entities activity.  For example, groups allow you to track activity by a User (entity) for a specific feature of your product.  Like entities, groups are identified by a unique identifier that you provide to Retained.
 
@@ -32,19 +32,23 @@ Retained's default settings are to connect to Redis at `redis://localhost:6379`,
 
 To track an entity with an id of `entity_id` as active for the current day:
 
-	Retained.retain('entity_id')
+    Retained.retain('entity_id')
 
 To track an entity with an id of `entity_id` as active on another day:
 
-	Retained.retain('entity_id', period: Time.new(2013,10,1))
-	
+    Retained.retain('entity_id', period: Time.new(2013,10,1))
+
 To query whether an entity was active on a given day:
 
-	Retained.active?('entity_id', period: Time.new(2014,3,21))
+    Retained.active?('entity_id', period: Time.new(2014,3,21))
 
 To determine the total number of active entities on a given day:
 
-	Retained.total_active(period: Time.new(2014,2,10))
+    Retained.total_active(period: Time.new(2014,2,10))
+
+To determine the total number of unique entities over a range:
+
+    Retained.unique_active(start: Time.new(2014,2,10), stop: Time.new(2014,2,13)
 
 ## Advanced Usage
 
@@ -52,38 +56,38 @@ To determine the total number of active entities on a given day:
 
 Retained can be configured with an alternate Redis connection string as well as an alternate prefix for keys:
 
-	Retained.configure do |config|
-	  config.redis = 'redis://example.org:6379'
-	  config.prefix = 'my_prefix',
-	end
-	
+    Retained.configure do |config|
+      config.redis = 'redis://example.org:6379'
+      config.prefix = 'my_prefix',
+    end
+
 You can also configure groups to use an alternate reporting interval-- either daily, hourly, or by minute.
 
 **Important!** Once set, a group's reporting interval **cannot** be changed. 
 
 For example, to configure a 'generated_report' group to use an hourly interval:
 
-	Retained.configure do |config|
-	  config.group('generated_report).do |group|
-	    group.reporting_interval = :hour
-	  end
-	end
-	
+    Retained.configure do |config|
+      config.group('generated_report).do |group|
+        group.reporting_interval = :hour
+      end
+    end
+
 If you need to have more control over the Redis connection (i.e. to use Sentinel), you can directly provide an already established connection:
 
-	Retained.configure do |config|
-	  config.redis_connection = Redis.new
-	end
+    Retained.configure do |config|
+      config.redis_connection = Redis.new
+    end
 
 ### Non-Singleton Use
 
 You can connect to multiple backends for Retained by instantiating a Retained tracker directly:
 
-	tracker = Retained::Tracker.new
-	tracker.configure do |config|
-	  config.redis = 'redis://other.example.org:6379'
-	end
-	tracker.retain('entity_id)
+    tracker = Retained::Tracker.new
+    tracker.configure do |config|
+      config.redis = 'redis://other.example.org:6379'
+    end
+    tracker.retain('entity_id)
 
 ## Contributing to retained
 

data/lib/retained/tracker.rb

@@ -16,21 +16,34 @@ module Retained
 
     # Tracks the entity as active at the period, or now if no period
     # is provided.
-    def retain(entity, group: group, period: Time.now)
+    def retain(entity, group: 'default', period: Time.now)
       index = entity_index(entity, group)
       bitmap = config.redis_connection.sparse_bitmap(key_period(group, period))
       bitmap[index] = true
     end
 
-    # Total active entities in the period, or now if now period,
+    # Total active entities in the period, or now if no period,
     # is provided.
-    def total_active(group: group, period: Time.now)
+    def total_active(group: 'default', period: Time.now)
       bitmap = config.redis_connection.sparse_bitmap(key_period(group, period))
       bitmap.bitcount
     end
 
+    # Returns the total number of unique active entities between
+    # the start and end periods (inclusive), or now if no stop
+    # period is provided.
+    def unique_active(group: 'default', start:, stop: Time.now)
+      bitmaps = []
+      while ( start <= stop)
+        bitmaps << config.redis_connection.sparse_bitmap(key_period(group, start))
+        start += seconds_in_reporting_interval(config.group(group).reporting_interval)
+      end
+      return 0  if bitmaps.length == 0
+      bitmaps.inject { |uniques,bitmap| uniques | bitmap }.bitcount
+    end
+
     # Returns true if the entity was active in the given period,
-    # or now if now period is provided.  If a group or an array of groups
+    # or now if no period is provided.  If a group or an array of groups
     # is provided activity will only be considered based on those groups.
     def active?(entity, group: nil, period: Time.now)
       group = [group] if group.is_a?(String)
@@ -73,5 +86,15 @@ LUA
       period = period.utc.send("beginning_of_#{config.group(group).reporting_interval}")
       "#{config.prefix}:#{group}:#{period.to_i}"
     end
+
+    private
+    def seconds_in_reporting_interval(interval)
+      case(interval.to_sym)
+        when :day    then 60*60*24
+        when :hour   then 60*60
+        when :minute then 60
+        else fail "Unknown reporting interval: #{interval}"
+      end
+    end
   end
 end

data/lib/retained/version.rb

@@ -2,7 +2,7 @@ module Retained
   module Version
     MAJOR = 0
     MINOR = 2
-    PATCH = 1
+    PATCH = 2
     BUILD = nil
 
     STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')

data/retained.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: retained 0.2.1 ruby lib
+# stub: retained 0.2.2 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "retained"
-  s.version = "0.2.1"
+  s.version = "0.2.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Mike Saffitz"]
-  s.date = "2014-10-13"
+  s.date = "2014-11-07"
   s.description = "\n    Easy tracking of activity and retention at scale in daily, hourly, or minute intervals\n    using sparse Redis bitmaps.\n  "
   s.email = "m@saffitz.com"
   s.extra_rdoc_files = [
@@ -48,7 +48,7 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<redis>, ["~> 3.1.0"])
-      s.add_runtime_dependency(%q<redis-bitops>, ["~> 0.2.1"])
+      s.add_runtime_dependency(%q<redis-bitops>, [">= 0"])
       s.add_runtime_dependency(%q<activesupport>, [">= 0"])
       s.add_development_dependency(%q<minitest>, [">= 0"])
       s.add_development_dependency(%q<yard>, ["~> 0.7"])
@@ -59,7 +59,7 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<timecop>, ["~> 0.7.1"])
     else
       s.add_dependency(%q<redis>, ["~> 3.1.0"])
-      s.add_dependency(%q<redis-bitops>, ["~> 0.2.1"])
+      s.add_dependency(%q<redis-bitops>, [">= 0"])
       s.add_dependency(%q<activesupport>, [">= 0"])
       s.add_dependency(%q<minitest>, [">= 0"])
       s.add_dependency(%q<yard>, ["~> 0.7"])
@@ -71,7 +71,7 @@ Gem::Specification.new do |s|
     end
   else
     s.add_dependency(%q<redis>, ["~> 3.1.0"])
-    s.add_dependency(%q<redis-bitops>, ["~> 0.2.1"])
+    s.add_dependency(%q<redis-bitops>, [">= 0"])
     s.add_dependency(%q<activesupport>, [">= 0"])
     s.add_dependency(%q<minitest>, [">= 0"])
     s.add_dependency(%q<yard>, ["~> 0.7"])

data/test/tracker_spec.rb

@@ -3,6 +3,8 @@ require 'securerandom'
 require 'timecop'
 Timecop.safe_mode = true
 
+SECONDS_PER_HOUR = 60*60
+SECONDS_PER_DAY  = 24*SECONDS_PER_HOUR
 
 describe Retained::Tracker do
   let(:tracker) { Retained::Tracker.new }
@@ -28,6 +30,11 @@ describe Retained::Tracker do
     tracker.config.redis_connection.sparse_bitmap("#{prefix}:group_a:1409356800")[0]
   end
 
+  it 'retains using the "default" group' do
+    tracker.retain('entity_a')
+    tracker.groups.must_equal ['default']
+  end
+
   it 'retain without a period tracks the entity for the current period' do
     Timecop.freeze(Time.new(2014, 8, 29, 9, 03, 35)) do
       tracker.retain('entity_a', group: 'group_a')
@@ -37,12 +44,13 @@ describe Retained::Tracker do
     end
   end
 
-  it 'total_active returns the number of active entities in the default group in the period' do
+  it 'total_active returns the number of active entities in the "default" group in the period' do
     period = Time.new(2014, 8, 30, 10, 47, 35)
     (count = rand(100)).times do |i|
       tracker.retain("entity_#{i}", period: period)
     end
     tracker.total_active(period: period).must_equal count
+    tracker.total_active(group: "default", period: period).must_equal count
   end
 
   it 'total_active returns the number of active entities in the period' do
@@ -60,6 +68,57 @@ describe Retained::Tracker do
     tracker.total_active(group: 'group_a').must_equal count
   end
 
+  describe "unique_active" do
+    before(:each) do
+      tracker.configure do |config|
+        config.group('hour') { |g| g.reporting_interval = :hour }
+        config.group('minute') { |g| g.reporting_interval = :minute }
+        config.group('day') { |g| g.reporting_interval = :day}
+      end
+    end
+
+    it 'properly tracks uniques when the reporting_interval is day' do
+      Timecop.freeze do
+        (1..4).each { |e| tracker.retain(e, group: 'day', period: Time.now)}
+        (2..4).each { |e| tracker.retain(e, group: 'day', period: Time.now - SECONDS_PER_DAY)}
+        (2..5).each { |e| tracker.retain(e, group: 'day', period: Time.now - 2*SECONDS_PER_DAY)}
+        (1..2).each { |e| tracker.retain(e, group: 'day', period: Time.now - 3*SECONDS_PER_DAY)}
+
+        tracker.unique_active(group: 'day', start: Time.now - 2*SECONDS_PER_DAY).must_equal 5
+        tracker.unique_active(group: 'day', start: Time.now - 2*SECONDS_PER_DAY, stop: Time.now - SECONDS_PER_DAY).must_equal 4
+        tracker.unique_active(group: 'day', start: Time.now - 4*SECONDS_PER_DAY, stop: Time.now - 5*SECONDS_PER_DAY).must_equal 0
+        tracker.unique_active(group: 'day', start: Time.now - 3*SECONDS_PER_DAY, stop: Time.now - 3*SECONDS_PER_DAY).must_equal 2
+      end
+    end
+
+    it 'properly tracks uniques when the reporting_interval is hour' do
+      Timecop.freeze do
+        (1..2).each { |e| tracker.retain(e, group: 'hour', period: Time.now)}
+        (3..4).each { |e| tracker.retain(e, group: 'hour', period: Time.now - 3*SECONDS_PER_HOUR)}
+        (5..6).each { |e| tracker.retain(e, group: 'hour', period: Time.now - 4*SECONDS_PER_HOUR)}
+        (6..8).each { |e| tracker.retain(e, group: 'hour', period: Time.now - 6*SECONDS_PER_HOUR)}
+
+        tracker.unique_active(group: 'hour', start: Time.now - 4*SECONDS_PER_HOUR).must_equal 6
+        tracker.unique_active(group: 'hour', start: Time.now - 2*SECONDS_PER_HOUR, stop: Time.now - SECONDS_PER_HOUR).must_equal 0
+        # tracker.unique_active(group: 'hour', start: Time.now - 6*SECONDS_PER_HOUR, stop: Time.now - 4*SECONDS_PER_HOUR).must_equal 4
+        # tracker.unique_active(group: 'hour', start: Time.now - 6*SECONDS_PER_HOUR, stop: Time.now - 3*SECONDS_PER_HOUR).must_equal 7
+      end
+    end
+
+    it 'properly tracks uniques when the reporting_interval is minute' do
+      Timecop.freeze do
+        (1..2).each { |e| tracker.retain(e, group: 'minute', period: Time.now)}
+        (3..5).each { |e| tracker.retain(e, group: 'minute', period: Time.now - 2*60)}
+        (2..3).each { |e| tracker.retain(e, group: 'minute', period: Time.now - 4*60)}
+        (6..7).each { |e| tracker.retain(e, group: 'minute', period: Time.now - 5*60)}
+
+        tracker.unique_active(group: 'minute', start: Time.now - 5*60).must_equal 7
+        tracker.unique_active(group: 'minute', start: Time.now - 2*60, stop: Time.now).must_equal 5
+        tracker.unique_active(group: 'minute', start: Time.now - 5*60, stop: Time.now - 4*60).must_equal 4
+      end
+    end
+  end
+
   describe 'active?' do
     it 'returns true when the entity is active' do
       Timecop.freeze do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: retained
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Mike Saffitz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-13 00:00:00.000000000 Z
+date: 2014-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -28,16 +28,16 @@ dependencies:
   name: redis-bitops
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement