counter 0.0.5

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2010 The New York Times Company
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this library except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.rdoc

@@ -0,0 +1,82 @@
+= counter
+
+Count things and rank them, as a one-off or over time.
+
+Major components:
+* Counter - a simple class to track counts, then sort and rank
+* MovingCount - a base class built atop ActiveRecord to aggregate counts over time (think {rrdtool}[http://oss.oetiker.ch/rrdtool/] for counts)
+
+
+=== Getting started
+
+  gem install counter
+  config.gem 'counter'
+  
+  require 'counter'
+  
+To use MovingCount, you'll also need to
+  require 'counter/moving_count'
+  
+(separate to prevent ActiveRecord dependency pollution)
+
+=== Counter
+
+  c = Counter.new
+  
+  # Counts can be incremented as a key appears
+  c.increment('some-key')
+  c.increment('some-key')
+  
+  # Or set directly
+  c.set('another-key', 42)
+
+  # You can retrieve all
+  c.counts
+  => [['another-key',42],['some-key',2]]
+  
+  # Or just the top-n
+  c.top(1)
+  => [['another-key',42]]
+  
+See Counter docs for detail.
+
+=== MovingCount
+
+  require 'counter/moving_count'
+  class PageView < MovingCount
+  end
+  
+  # In a migration:
+  #  create_table :page_views, :force => true do |t|
+  #    t.string   :category,      :null => false
+  #    t.integer  :count,         :null => false, :default => 0
+  #    t.datetime :sample_time,   :null => false
+  #  end
+  #
+  #  add_index :page_views, :category
+  
+  # First set of samples...
+  PageView.record_counts(Time.now - 5.minutes) do |c|
+    c.increment('a-key')
+    c.increment('a-key')
+  end
+  
+  # Second set...
+  PageView.record_counts(Time.now) do |c|
+    c.increment('a-key')
+    c.increment('another-key')
+  end
+  
+  # Contribute to totals.
+  PageView.totals
+  => [['a-key',3],['another-key',1]]
+  
+See MovingCount docs for detail.
+
+== Author
+
+Ben Koski, bkoski@nytimes.com
+
+== Copyright
+
+Copyright (c) 2010 The New York Times Company. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "counter"
+    gem.summary = %Q{count things, either as a one-off or aggregated over time}
+    gem.description = %Q{count things, either as a one-off or aggregated over time}
+    gem.email = "bkoski@nytimes.com"
+    gem.homepage = "http://github.com/nytimes/counter"
+    gem.authors = ["Ben Koski"]
+    gem.add_development_dependency "thoughtbot-shoulda"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "counter #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.5

data/counter.gemspec

@@ -0,0 +1,59 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{counter}
+  s.version = "0.0.5"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ben Koski"]
+  s.date = %q{2010-07-29}
+  s.description = %q{count things, either as a one-off or aggregated over time}
+  s.email = %q{bkoski@nytimes.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "counter.gemspec",
+     "lib/counter.rb",
+     "lib/counter/counter.rb",
+     "lib/counter/moving_count.rb",
+     "test/schema.rb",
+     "test/test_counter.rb",
+     "test/test_helper.rb",
+     "test/test_moving_count.rb"
+  ]
+  s.homepage = %q{http://github.com/nytimes/counter}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{count things, either as a one-off or aggregated over time}
+  s.test_files = [
+    "test/schema.rb",
+     "test/test_counter.rb",
+     "test/test_helper.rb",
+     "test/test_moving_count.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    else
+      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+  end
+end

data/lib/counter.rb

@@ -0,0 +1 @@
+require 'counter/counter'

data/lib/counter/counter.rb

@@ -0,0 +1,76 @@
+# Basic counting.
+#
+# === To count:
+#
+# Easiest way to count is to increment while iterating over data:
+#
+#  c = Counter.new
+#  c.increment('some-key')
+#  c.saw('some-key')  # alias
+#
+# But you can also set counts directly:
+#  c = Counter.new
+#  c.set('another-key', 42)
+#
+# === To get counts back:
+#
+# You can use Hash-style syntax:
+#  puts c['some-key]
+#  => 2
+#
+# or ask for the top-n keys as an array of [key, count]
+#
+#  puts c.top(2)
+#  => [['key-1',50],['key-2',38]]
+#
+# or just ask for data for all keys:
+#  puts c.counts
+#  => [['key-1',50],['key-2',38],['key-3',22]]
+#
+# === Some notes
+# * 0 is returned, even if key has never been seen
+# * if ties exist in a top-n ranking, they are broken by sort on key
+class Counter
+    
+  def initialize
+    @data = Hash.new(0)
+  end
+  
+  # key++
+  def increment key
+    @data[key] += 1
+    true
+  end
+  alias_method :saw, :increment
+  
+  # sets the key to a specified value
+  def set key, count
+    raise ArgumentError, "count must be numeric" if !count.is_a?(Numeric)
+    @data[key] = count
+  end
+  
+  # Retrieve the count for a particular key
+  def [] key
+    @data[key]
+  end
+  
+  # Returns all elements as [key, count] array
+  def counts
+    sorted_data
+  end
+  
+  # Returns top <tt>n</tt> elements as [key,count] array
+  def top n
+    sorted_data[0,n]
+  end
+    
+  def to_a
+    @data.to_a
+  end
+  
+  private
+  def sorted_data
+    @data.to_a.sort { |a,b| a[1] != b[1] ? a[1] <=> b[1] : b[0] <=> a[0] }.reverse
+  end
+  
+end

data/lib/counter/moving_count.rb

@@ -0,0 +1,105 @@
+require 'active_record'
+
+# Capture counts, then aggregate them across time. Think of this as an rrdtool for counts.
+#
+# === Setup
+# Inherit from this class
+#
+#  class PageView < MovingCount
+#  end
+#
+# Then drop the following into a migration:
+#
+#  create_table :page_views, :force => true do |t|
+#    t.string   :category,      :null => false
+#    t.integer  :count,         :null => false, :default => 0
+#    t.datetime :sample_time,   :null => false
+#  end
+#
+#  add_index :page_views, :category
+#
+# Two optional class-level settings:
+# * *set_history_to_keep*, depth of history to keep in seconds - defaults to 1 hour of history
+# * *set_sample_interval*, minimum distance between samples in seconds (enforced at record time) - defaults to 1 minute
+#
+# === Recording counts
+#
+#  PageView.record_counts(Time.at(1280420630)) do |c|
+#    c.increment('key1')
+#    c.increment('key1')
+#    c.increment('key2')
+#  end
+#
+# records observed counts for Thu Jul 29 12:23:50.  You can omit the param to record counts at Time.now.
+#
+# A runtime error will be raised if the sample is too close to the previous (for example, sample_interval is 60s and you tried to record 
+# a sample at 50s).  This prevents accidental duping of counts on restarts, etc.
+#
+# === Checking totals
+#
+#  PageView.totals
+#
+# returns a [key,count] array of all keys ordered by count.  An optional <tt>limit</tt> param restricts results to the top n.
+class MovingCount < ActiveRecord::Base
+  self.abstract_class = true
+  
+  # Sets the depth of history to keep, in seconds.
+  # Default is 1 hour.
+  def self.set_history_to_keep time_range
+    @history_to_keep = time_range
+  end
+  
+  def self.history_to_keep
+    @history_to_keep || 1.hour
+  end
+  
+  # Sets the minimum distance between recorded samples, in seconds.
+  # Default is 1 minute.
+  def self.set_sample_interval interval
+    @sample_interval = interval
+  end
+  
+  def self.sample_interval
+    @sample_interval || 1.minute
+  end
+  
+  # Records counts at the specified timestamp.  If timestamp omitted, counts are recorded at Time.now.
+  # Yields a Counter instance, all standard methods apply.
+  # Raises an exception if the timestamp would fall too soon under the <tt>sample_interval</tt>.
+  def self.record_counts timestamp=Time.now, &block
+   c = Counter.new
+   yield(c)
+   
+   self.transaction do
+     check_sample_valid(timestamp)
+     
+     q = "INSERT INTO #{self.table_name} (sample_time, category, count) VALUES "
+     c.counts.each { |key, count| q += self.sanitize_sql(['(?, ?, ?),', timestamp, key, count]) }
+     q.chop!
+     
+     self.connection.execute(q)
+     self.delete_all(['sample_time < ?', (timestamp - history_to_keep)])
+   end
+    
+    true
+  end
+  
+  # Returns totals across entire history.  Optional limit param restricts resultset.
+  def self.totals limit=nil
+    values = self.connection.select_rows("SELECT category, SUM(count) AS cnt FROM #{self.table_name} GROUP BY category ORDER BY cnt DESC #{"LIMIT #{limit}" if limit};")
+    values.map { |v| v[1] = v[1].to_i }
+    return values
+  end
+  
+  private
+  def self.check_sample_valid timestamp
+    latest_sample =  self.maximum(:sample_time)
+    return if latest_sample.nil? # sample is of course valid if no data exists
+    
+    distance = (timestamp - latest_sample).abs
+    if distance < sample_interval
+      raise "Data recorded at #{self.maximum(:sample_time)} making #{timestamp} #{'%0.2f' % (sample_interval - distance)}s too soon on a #{sample_interval} interval."
+    end
+  end
+  
+end

data/test/schema.rb

@@ -0,0 +1,18 @@
+ActiveRecord::Schema.define(:version => 1) do
+
+  create_table :page_views, :force => true do |t|
+    t.string   :category,      :null => false
+    t.integer  :count,         :null => false, :default => 0
+    t.datetime :sample_time,   :null => false
+  end
+  
+  add_index :page_views, :category
+
+  create_table :clicks, :force => true do |t|
+    t.string   :category,      :null => false
+    t.integer  :count,         :null => false, :default => 0
+    t.datetime :sample_time,   :null => false
+  end
+
+
+end

data/test/test_counter.rb

@@ -0,0 +1,50 @@
+require 'test_helper'
+
+class CounterTest < Test::Unit::TestCase
+
+  def setup
+    @c = Counter.new
+  end
+
+  should "increment count every time increment is called for a key" do
+    @c.increment('some-key')
+    @c.increment('some-key')
+    assert_equal 2, @c['some-key']
+  end
+  
+  should "return 0 even if key has never been incremented" do
+    assert_equal 0, @c['some-key']
+  end
+  
+  should "return count directly if it was set" do
+    @c.set('some-key', 65)
+    assert_equal 65, @c['some-key']
+  end
+  
+  should "raise an ArgumentError if set called with a non-numeric" do
+    assert_raises(ArgumentError) { @c.set('some-key', Time.now) }
+  end
+  
+  should "return counts as a [[key,cnt]] array" do
+    @c.set('some-key',    32)
+    @c.set('another-key', 45)
+    
+    assert_equal [['another-key',45],['some-key',32]], @c.counts
+  end
+  
+  should "return top(n) as a [[key,cnt]] array of top n objects based on count" do
+    @c.set('some-key',    32)
+    @c.set('another-key', 45)
+    @c.set('some-key-3',  90)
+    
+    assert_equal [['some-key-3',90],['another-key',45]], @c.top(2)
+  end
+  
+  should "break top(n) ties on key name" do
+    @c.set('some-key-1', 34)
+    @c.set('some-key-2', 34)
+    
+    assert_equal [['some-key-1', 34]], @c.top(1)
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+require 'timecop'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'counter'
+
+class Test::Unit::TestCase
+end
+
+require 'counter/moving_count'
+
+require 'active_record'
+ActiveRecord::Base.establish_connection :adapter => 'mysql', :database => 'counter_test'
+silence_stream(STDOUT) do
+  load(File.dirname(__FILE__) + "/schema.rb")
+end
+
+class PageView < MovingCount
+end
+
+class Click < MovingCount
+  set_sample_interval 5.seconds
+  set_history_to_keep 2.minutes
+end

data/test/test_moving_count.rb

@@ -0,0 +1,115 @@
+require 'test_helper'
+
+class MovingCountTest < Test::Unit::TestCase
+  
+  def setup
+    Timecop.return
+    [PageView, Click].each { |m| m.delete_all }
+  end
+  
+  context "record" do
+    
+    should "save counts to the database" do
+      PageView.record_counts do |c|
+        c.saw('http://www.nytimes.com')
+        c.saw('http://www.nytimes.com')
+        c.saw('http://www.nytimes.com/article.html')        
+      end
+      
+      assert_equal 2, PageView.find_by_category('http://www.nytimes.com').count
+      assert_equal 1, PageView.find_by_category('http://www.nytimes.com/article.html').count
+    end
+    
+    context "sample interval" do
+      should "raise a RuntimeError to enforce sample interval" do
+        setup_existing_counts(59)
+        assert_raises(RuntimeError) { PageView.record_counts { |c| c.saw('http://www.nytimes.com') } }
+      end
+    
+      should "default sample interval to 60 seconds" do
+        setup_existing_counts(60)
+        assert_nothing_raised { PageView.record_counts { |c| c.saw('http://www.nytimes.com') } }
+      end
+    
+      should "respect custom sample interval" do
+        setup_existing_counts(5, Click)
+        assert_nothing_raised { Click.record_counts { |c| c.saw('http://www.nytimes.com') } }
+      end
+
+      should "allow samples to be backfilled" do
+        setup_existing_counts(60)
+        assert_nothing_raised { PageView.record_counts(Time.now - 3600) { |c| c.saw('http://www.nytimes.com') } }
+      end
+    end
+    
+    context "sample_time" do
+      should "record provided timestamp as sample time" do
+        stamp = Time.now - 300
+        PageView.record_counts(stamp) do |c|
+          c.saw('http://www.nytimes.com')
+          c.saw('http://www.nytimes.com/article.html')        
+        end
+      
+        assert_equal 2, PageView.count(:conditions => {:sample_time => stamp})
+      end
+    
+      should "use Time.now as the timestamp if none specified" do
+        Timecop.freeze
+      
+        PageView.record_counts do |c|
+          c.saw('http://www.nytimes.com')
+          c.saw('http://www.nytimes.com/article.html')        
+        end
+      
+        assert_equal 2, PageView.count(:conditions => {:sample_time => Time.now})
+      end
+    end
+    
+    context "purge" do
+      should "purge data older than history_to_keep" do
+        setup_existing_counts(2.hours)
+        PageView.record_counts { |c| c.saw('http://www.nytimes.com') }
+        assert_equal 1, PageView.count
+      end
+      
+      should "set default history_to_keep at 1 hour" do
+        setup_existing_counts(59.minutes)
+        PageView.record_counts { |c| c.saw('http://www.nytimes.com') }
+        assert_equal 2, PageView.count
+      end
+      
+      should "respect custom history_to_keep" do
+        setup_existing_counts(5.minutes, Click)
+        Click.record_counts { |c| c.saw('http://www.nytimes.com') }
+        assert_equal 1, Click.count
+      end
+    end
+
+
+    context "totals" do
+      should "returns totals across all samples in the history" do
+        setup_existing_counts(10.minutes)
+        setup_existing_counts(5.minutes)
+        PageView.record_counts { |c| c.saw('http://www.nytimes.com'); c.saw('http://www.nytimes.com/article.html') }
+        
+        assert_equal [['http://www.nytimes.com',3],['http://www.nytimes.com/article.html',1]], PageView.totals
+      end
+      
+      should "respect limit if provided" do
+        setup_existing_counts(10.minutes)
+        setup_existing_counts(5.minutes)
+        PageView.record_counts { |c| c.saw('http://www.nytimes.com'); c.saw('http://www.nytimes.com/article.html') }
+        
+        assert_equal [['http://www.nytimes.com',3]], PageView.totals(1)
+      end
+    end
+    
+  end
+  
+  def setup_existing_counts distance, model=PageView
+    Timecop.freeze(Time.now - distance)
+    model.record_counts { |c| c.saw('http://www.nytimes.com') }
+    Timecop.freeze(Time.now + distance)
+  end
+  
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: counter
+version: !ruby/object:Gem::Version 
+  version: 0.0.5
+platform: ruby
+authors: 
+- Ben Koski
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-29 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: count things, either as a one-off or aggregated over time
+email: bkoski@nytimes.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- counter.gemspec
+- lib/counter.rb
+- lib/counter/counter.rb
+- lib/counter/moving_count.rb
+- test/schema.rb
+- test/test_counter.rb
+- test/test_helper.rb
+- test/test_moving_count.rb
+has_rdoc: true
+homepage: http://github.com/nytimes/counter
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: count things, either as a one-off or aggregated over time
+test_files: 
+- test/schema.rb
+- test/test_counter.rb
+- test/test_helper.rb
+- test/test_moving_count.rb