redis_analytics 0.1.0 → 0.6.0

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## 0.2.0
+
+* refactor of the dashboard sinatra app
+* code revamp and cleanup
+* path filters and proc filters
+* JSON api for reports
+* dashboard and api endpoints no longer mandatory
+* various bug fixes and tests
+
+## 0.1.0
+
+* first version

data/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to redis_analytics
+
+## Contributors List
+
+* Schubert Cardozo
+* Sascha Wessel
+
+## Adding new features
+
+* Create a topic branch for your feature and make your changes there
+* Do not fail the build or compromise on the code coverage too much (adding more test cases would be fantastic a contribution)
+* Send me a pull request
+* You should include tests where possible
+* Make updates to the changelog
+
+## Bugs/Features
+
+* The [issue tracker](https://github.com/saturnine/redis_analytics/issues) is
+  the preferred channel for [bug reports](#bugs), [features requests](#features)
+  and [submitting pull requests](#pull-requests)
+
+* Please **do not** use the issue tracker for personal support requests (use
+  [Stack Overflow](http://stackoverflow.com/questions/tagged/redis_analytics)).
+
+* Please **do not** derail or troll issues. 
+
+* Keep the discussion on topic and respect the opinions of others.
+
+# Translations
+
+* You can help us translate the project. Simply drop me a message here on Github
+
+# Thank you for your contribution

data/Guardfile

@@ -0,0 +1,10 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/README.md

@@ -1,20 +1,20 @@
-# redis_analytics  [![Build Status](https://travis-ci.org/saturnine/redis_analytics.png?branch=master)](https://travis-ci.org/saturnine/redis_analytics)
+## redis_analytics [![Build Status](https://travis-ci.org/saturnine/redis_analytics.png?branch=master)](https://travis-ci.org/saturnine/redis_analytics) [![Coverage Status](https://coveralls.io/repos/saturnine/redis_analytics/badge.png?branch=master)](https://coveralls.io/r/saturnine/redis_analytics) [![Gem Version](https://badge.fury.io/rb/redis_analytics.png)](http://badge.fury.io/rb/redis_analytics)
 
-## What is redis_analytics?
+### What is redis_analytics?
 
 A gem that provides a Redis based web analytics solution for your rack-compliant apps
 
-## Why should I use it?
+### Why should I use it?
 
 It gives you detailed analytics about visitors, unique visitors, browsers, OS, visitor recency, traffic sources and more
 
-## Does it have a cool dashboard?
+### Does it have a cool dashboard?
 
-Yes, It uses the excellent [Morris.js](http://www.oesmith.co.uk/morris.js/) for the main dashboard and [Highcharts](http://www.highcharts.com) for drawing the various detailed graphs
+Yes, It uses the excellent [Morris.js](http://www.oesmith.co.uk/morris.js/) for graphs/charts
 
 ![Screenshot](https://github.com/saturnine/redis_analytics/raw/master/screenshot.png)
 
-## OK, so how do I install it?
+### OK, so how do I install it?
 
 `gem install redis_analytics`
 
@@ -27,9 +27,9 @@ gem 'redis_analytics'
 Make sure your redis server is running! Redis configuration is outside the scope of this README, but
 check out the [Redis documentation](http://redis.io/documentation).
 
-## How do I enable tracking in my rack-compliant app?
+### How do I enable tracking in my rack-compliant app?
 
-### Step 1: Load the redis_analytics library and configure it
+#### Step 1: Load the redis_analytics library and configure it
 
 ```ruby
 # this is not required unless you use :require => false in your Gemfile
@@ -41,7 +41,7 @@ Rack::RedisAnalytics.configure do |configuration|
   configuration.redis_namespace = 'ra'
 end
 ```
-### Step 2: Use the Tracker rack middleware (NOT REQUIRED FOR RAILS)
+#### Step 2: Use the Tracker rack middleware (NOT REQUIRED FOR RAILS)
 
 ```ruby
 # in Sinatra you would do...
@@ -50,9 +50,17 @@ use Rack::RedisAnalytics::Tracker
 
 For rails the middleware is added automatically, so you do not need to add it manually using `config.middleware.use`
 
-## Where do I view the dashboard?
+### Where can I see the dashboard?
 
-### Option 1: Set a dashboard endpoint in your configuration
+Simply navigate to `/redis_analytics` in your rack app
+
+You can also run the standalone dashboard sinatra app like:
+
+`redis_analytics_dashboard --redis-host 127.0.0.1 --redis-port 6379 --redis-namespace ra`
+
+### Where do I change the dashboard URL endpoint?
+
+Set a dashboard endpoint in your configuration:
 
 ```ruby
 Rack::RedisAnalytics.configure do |configuration|
@@ -60,15 +68,7 @@ Rack::RedisAnalytics.configure do |configuration|
 end
 ```
 
-and navigate to [http://localhost:3000/dashboard](http://localhost:3000/dashboard) assuming your rack-compliant app is hosted at [http://localhost:3000](http://localhost:3000)
-
-### Option 2: Simply run the bundled Sinatra application binary
-
-`redis_analytics_dashboard --redis-host 127.0.0.1 --redis-port 6379 --redis-namespace ra`
-
-and navigate to [http://localhost:4567](http://localhost:4567)
-
-## What if I have multiple rails apps that I want to track as one?
+### What if I have multiple rails apps that I want to track as one?
 
 In the configuration, keep the value of redis_namespace the same across all your rails apps
 
@@ -79,7 +79,7 @@ Rack::RedisAnalytics.configure do |configuration|
 end
 ```
 
-## Why is the Geolocation tracking giving me wrong results?
+### Why is the Geolocation tracking giving me wrong results?
 
 IP based Geolocation works using [MaxMind's](http://www.maxmind.com) GeoLite database. The free version is not as accurate as their commercial version. 
 Also it is recommended to regularly get an updated binary of 'GeoLite Country' database from [here](http://dev.maxmind.com/geoip/geolite) and extract the GeoIP.dat file into a local directory.
@@ -93,6 +93,88 @@ Rack::RedisAnalytics.configure do |configuration|
 end
 ```
 
-## Copyright
+## Customizing & Extending
+
+### Tracking custom metrics
+
+You can define and track your own metrics by defining an instance method inside the `Metrics` module
+
+All you need to do, is make sure the method name conforms to the following format:
+
+`[abc]_[x]_per_[y]`
+
+where
+
+* `abc` is a metric name
+* `x` can be any one of `ratio` or `count` and defines how the metric is stored (`zset` or `string` respectively)
+* `y` can be any one of `hit` or `visit` and defines how will be tracked  (once per hit or once per visit)
+
+The return value of the method should be `Fixnum` for `count` and `String` for `ratio`  
+
+If the return value is an `error` or `nil` the metric won't be tracked  
+
+You can access the `Rack::Request` object via `@rack_request` and the `Rack::Response` object via `@rack_response` in your method  
+
+You are free to define other methods that do not have the above format in the `Metrics` module as helper methods  
+
+```ruby
+module Rack::RedisAnalytics::Metrics
+
+  # whenever a product is sold, i want to track it per product_id
+  def product_sales_ratio_per_hit
+    if @request.path == '/product/sale'
+      return @request.params['product_id']
+    end
+  end
+
+  # whenever a product is viewed by a user, i want to track it per product & user
+  def user_product_views_ratio_per_hit
+    if @request.path == '/product/info'
+      return "#{@request.params['product_id']}_#{@request.params['user_id']}"
+    end
+  end
+
+  # how many times did a visitor reach the payment step
+  def payment_step_count_per_hit
+    return 1 if @request.path == '/payment'
+  end
+
+end
+```
+
+### Using filters
+
+```ruby
+Rack::RedisAnalytics.configure do |configuration|
+
+  # simple string path filter
+  configuration.add_path_filter('/robots.txt')
+
+  # regexp path filter
+  configuration.add_path_filter(/^\/favicon.ico$/)
+
+  # generic filters
+  configuration.add_filter do |request, response|
+    request.params['layout'] == 'print'
+  end
+
+  # generic filters
+  configuration.add_filter do |request, response|
+    request.ip =~ /^172.16/ or request.ip =~ /^192.168/
+  end
+
+end
+```
+
+## How does it work?
+
+![Screenshot](https://github.com/saturnine/redis_analytics/raw/master/wsd.png)
+
+## License
+
+Since redis_analytics is licensed under MIT, you can use redis_analytics, provided you leave the attribution as is, in code as well as on the dashboard pages
+
+Copyright (c) 2012-2013 Schubert Cardozo. See [LICENSE!](LICENSE) for further details. 
+
+
 
-Copyright (c) 2012-2013 Schubert Cardozo. See LICENSE for further details.

data/Rakefile

@@ -1,19 +1,11 @@
-# require 'bundler/gem_tasks'
+# encoding: UTF-8
+require 'bundler/gem_tasks'
 require 'rake'
 require 'rspec/core'
 require 'rspec/core/rake_task'
 
-# encoding: UTF-8
-require 'rubygems'
-begin
-  require 'bundler/setup'
-rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-end
-
 RSpec::Core::RakeTask.new(:spec) do |spec|
   spec.pattern = 'spec/**/*_spec.rb'
-  spec.rspec_opts = ['--backtrace']
 end
 
-task :default => :spec
+task :default => [:spec, :build]

data/TODO.md

@@ -0,0 +1,12 @@
+## TODO
+
+* cleanup and refactor analytics.rb
+* cleanup and refactor dashboard.rb
+* dashboard to have custom date selectors
+* need to get more metrics tracked, like landing/exit pages ratio, ratio of page URL's, ratio of http-responses
+* improve 'traffic sources' metric to show - organic vs search-engine vs referral vs campaign
+* js/jquery to refresh dashboard numbers per second (real time mode)
+* advanced filtering options
+* tracker beacon to track from external apps
+* transactions and audits?
+* move to bootstrap 3?

data/bin/redis_analytics_dashboard

@@ -3,7 +3,7 @@
 require 'rubygems'
 path = File.expand_path '../../lib', __FILE__
 $:.unshift(path) if File.directory?(path) && !$:.include?(path)
-require 'redis_analytics/dashboard'
+require 'redis_analytics'
 args = Hash[*ARGV] rescue {}
 if args.key?('--redis-host') and args.key?('--redis-port')
   Rack::RedisAnalytics.configure do |c|

data/config.ru

@@ -0,0 +1,13 @@
+$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), "lib")))
+
+require 'redis_analytics'
+Rack::RedisAnalytics.configure do |c|
+  c.redis_connection = Redis.new
+  c.add_path_filter(/^\/favicon.ico$/)
+end
+
+app = Rack::Builder.app do
+  use Rack::RedisAnalytics::Tracker
+  run Proc.new { |env| [200, {'Content-Type' => 'text/html'}, "You have been tracked!"] }
+end
+run app

data/lib/redis_analytics.rb

@@ -2,14 +2,18 @@ require 'rack'
 require 'redis'
 require 'browser'
 require 'sinatra'
-require 'geoip' 
+require 'geoip'
 
 require 'redis_analytics'
 require 'redis_analytics/version'
+require 'redis_analytics/filter'
 require 'redis_analytics/configuration'
 require 'redis_analytics/analytics'
+require 'redis_analytics/metrics'
+require 'redis_analytics/visit'
 require 'redis_analytics/time_ext'
 require 'redis_analytics/helpers'
+require 'redis_analytics/api'
 require 'redis_analytics/dashboard'
 
 require 'redis_analytics/tracker'

data/lib/redis_analytics/analytics.rb

@@ -2,230 +2,44 @@
 require 'digest/md5'
 module Rack
   module RedisAnalytics
-    
     class Analytics
-      
-      PAGEVIEWS = [['/health', 'o', 'd', 't'], ['/track', 'o', 'd', 't']]
-
-      TRANSACTIONS = {
-        "flights_search" => ["/flights/search", :o, :d],
-        "flights_results" => ["/flights/results", :o, :d],
-        "flights_book_step_1" => ["/flights/itinerary/:itinerary_id/info"],
-        "flights_book_step_2" => ["/flights/itinerary/:itinerary_id/traveller"],
-        "flights_book_step_3" => ["/flights/itinerary/:itinerary_id/pay"],
-        "flights_book_done" => ["/flights/itinerary/:itinerary_id/confirmation"],
-        "products" => ["/products/:id/review", :user_id]
-      }
-
-      REFERRERS = ['google', 'bing', 'yahoo', 'cleartrip', 'github']
 
       def initialize(app)
         @app = app
-        @redis_key_prefix = "#{RedisAnalytics.redis_namespace}:"
       end
-      
-      # def call(env)
-      #   dup.call!(env)
-      # end
 
       def call(env)
+        dup.call!(env)
+      end
+
+      def call!(env)
         @env = env
         @request  = Request.new(env)
         status, headers, body = @app.call(env)
         @response = Rack::Response.new(body, status, headers)
-        record if @response.ok? and @response.content_type =~ /^text\/html/
+        record if should_record?
         @response.finish
       end
 
-      def parse_path(path)
-        keys = []
-        spc = %w{. + ( )}
-        pattern =
-          path.to_str.gsub(/((:\w+)|[\*#{spc.join}])/) do |match|
-          case match
-          # when "*"
-          #   keys << 'splat'
-          #   "(.*?)"
-          when *spc
-            Regexp.escape(match)
-          else
-            keys << $2[1..-1]
-            "([^/?&#]+)"
-          end
+      def should_record?
+        return false unless @response.ok?
+        return false unless @response.content_type =~ /^text\/html/
+        RedisAnalytics.path_filters.each do |filter|
+          return false if filter.matches?(@request.path)
         end
-        [/^#{pattern}$/, keys]
-      end
-
-      def for_each_time_range(t)
-        RedisAnalytics.redis_key_timestamps.map{|x, y| [t.strftime(x), y]}.each do |ts, expire|
-          yield(ts, expire) # returns an array of the redis methods to call 
-          # r.each do |method, args|
-          #   RedisAnalytics.redis_connection.send(method, *args)
-          #   RedisAnalytics.redis_connection.expire(args[1]) if expire # assuming args[1] is always the key that is being operated on.. will this always work?
-          # end
+        RedisAnalytics.filters.each do |filter|
+          return false if filter.matches?(@request, @response)
         end
+        return true
       end
 
       def record
-        t = Time.now 
-
-        # record pageviews
-        path = @request.path
-        params = @request.params
-        if i = PAGEVIEWS.index{|x| x[0] == path}
-          page = PAGEVIEWS[i]
-          params.select{|x, y| page[1..-1].include?(x)}.each do |k, v|
-            for_each_time_range(t) do |ts, expire|
-              h = Digest::MD5.hexdigest(v)
-              RedisAnalytics.redis_connection.hset("#{@redis_key_prefix}page", h, v)
-              RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}page", expire) if expire
-
-              RedisAnalytics.redis_connection.incr("#{@redis_key_prefix}page_#{i}_#{page.index(k)}_#{h}:#{ts}")
-              RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}page_#{i}_#{page.index(k)}_#{h}:#{ts}", expire) if expire
-            end
-          end
-        end
-        
-        returning_visitor = @request.cookies[RedisAnalytics.returning_user_cookie_name]
-        recent_visitor = @request.cookies[RedisAnalytics.visit_cookie_name]
-
-        vcn_seq, rucn_seq = nil
-        visit_start_time =visit_end_time = first_visit_time = t.to_i
-
-        if not returning_visitor and not recent_visitor
-          rucn_seq = RedisAnalytics.redis_connection.incr("#{@redis_key_prefix}unique_visits")
-          vcn_seq = RedisAnalytics.redis_connection.incr("#{@redis_key_prefix}visits")
-          visit(t, :rucn_seq => rucn_seq)
-          new_visit(t)
-          visit_time(t, t.to_i)
-          page_view(t)
-        elsif returning_visitor and not recent_visitor
-          vcn_seq = RedisAnalytics.redis_connection.incr("#{@redis_key_prefix}visits")
-          rucn_seq, first_visit_time, last_visit_time = returning_visitor.split('.')
-          visit(t, :last_visit_time => last_visit_time.to_i, :rucn_seq => rucn_seq)
-          page_view(t)
-        elsif returning_visitor and recent_visitor
-          rucn_seq, vcn_seq, visit_start_time, visit_end_time = recent_visitor.split('.')
-          rucn_seq, first_visit_time = returning_visitor.split('.')
-          visit_time(t, visit_end_time.to_i)
-          page_view(t, visit_start_time.to_i == visit_end_time.to_i)
-        elsif not returning_visitor and recent_visitor
-          rucn_seq, vcn_seq, visit_start_time, visit_end_time = recent_visitor.split('.')
-          visit_time(t, visit_end_time.to_i)
-          page_view(t, visit_start_time.to_i == visit_end_time.to_i)
-        end
-
-        # create the recent visit cookie
-        @response.set_cookie(RedisAnalytics.visit_cookie_name, {:value => "#{rucn_seq}.#{vcn_seq}.#{visit_start_time}.#{t.to_i}", :expires => t + (RedisAnalytics.visit_timeout.to_i * 60 )})
-
-        # create the permanent cookie (2 years)
-        @response.set_cookie(RedisAnalytics.returning_user_cookie_name, {:value => "#{rucn_seq}.#{first_visit_time}.#{t.to_i}", :expires => t + (60 * 60 * 24 * 5)}) # 5 hours temp
-
-        puts "TIME = [#{t}]"
-        puts "VISIT = #{vcn_seq}"
-        puts "UNIQUE VISIT = #{rucn_seq}"
-      end
-      
-      def new_visit(t)
-        for_each_time_range(t) do |ts, expire|
-          RedisAnalytics.redis_connection.incr("#{@redis_key_prefix}new_visits:#{ts}")
-          RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}new_visits:#{ts}",expire) if expire
-        end
+        v = Visit.new(@request, @response)
+        @response = v.record
+        @response.set_cookie(RedisAnalytics.current_visit_cookie_name, v.updated_current_visit_info)
+        @response.set_cookie(RedisAnalytics.first_visit_cookie_name, v.updated_first_visit_info)
       end
 
-      def visit(t, options = {})
-        last_visit_time = options[:last_visit_time] || nil
-        rucn_seq = options[:rucn_seq] || nil
-        geo_country_code = nil
-        referrer = nil
-        ua = nil
-        
-        # Geo IP Country code fetch
-        if defined?(GeoIP)
-          begin
-            g = GeoIP.new(RedisAnalytics.geo_ip_data_path)
-            geo_country_code = g.country(@request.ip).to_hash[:country_code2]
-            puts "Tracking IP #{@request.ip} using #{g.inspect} => GOT #{geo_country_code}"
-          rescue Exception => e
-            puts "Warning: Unable to fetch country info #{e}"
-          end
-        end
-
-        # Referrer regex decode
-        if @request.referrer
-          REFERRERS.each do |referrer|
-            # this will track x.google.mysite.com as google so its buggy, fix the regex
-            if m = @request.referrer.match(/^(https?:\/\/)?([a-zA-Z0-9\.\-]+\.)?(#{referrer})\.([a-zA-Z\.]+)(:[0-9]+)?(\/.*)?$/)
-              "REFERRER => #{m.to_a[3]}"
-              referrer = m.to_a[3]
-            else
-              referrer = 'other'
-            end
-          end
-        else
-          referrer = 'organic'
-        end
-
-        # User agent
-        ua = Browser.new(:ua => @request.user_agent, :accept_language => 'en-us')
-        
-        for_each_time_range(t) do |ts, expire|
-
-          # increment the total visits
-          RedisAnalytics.redis_connection.incr("#{@redis_key_prefix}visits:#{ts}")
-          RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}visits:#{ts}", expire) if expire
-
-          if rucn_seq
-            unique = RedisAnalytics.redis_connection.sadd("#{@redis_key_prefix}unique_visits:#{ts}", rucn_seq)
-            RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}unique_visits:#{ts}", expire) if expire
-            
-            # geo ip tracking
-            if geo_country_code and geo_country_code =~ /^[A-Z]{2}$/
-              RedisAnalytics.redis_connection.zincrby("#{@redis_key_prefix}ratio_country:#{ts}", 1, geo_country_code)
-              RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}ratio_country:#{ts}", expire) if expire
-            end
-            
-            # referrer tracking 
-            RedisAnalytics.redis_connection.zincrby("#{@redis_key_prefix}ratio_referrers:#{ts}", 1, referrer)
-          end
-          
-          # tracking for visitor recency
-          if last_visit_time
-            days_since_last_visit = ((t.to_i - last_visit_time)/(24*3600)).round
-            RedisAnalytics.redis_connection.zincrby("#{@redis_key_prefix}ratio_recency:#{ts}", 1, days_since_last_visit)
-            RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}ratio_recency:#{ts}", expire) if expire
-          end
-          
-          RedisAnalytics.redis_connection.zincrby("#{@redis_key_prefix}ratio_browsers:#{ts}", 1,  ua.name)
-          RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}ratio_browsers:#{ts}", expire) if expire
-
-          RedisAnalytics.redis_connection.zincrby("#{@redis_key_prefix}ratio_platforms:#{ts}", 1, ua.platform.to_s)
-          RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}ratio_platforms:#{ts}", expire) if expire
-          
-          RedisAnalytics.redis_connection.zincrby("#{@redis_key_prefix}ratio_devices:#{ts}", 1, ua.mobile? ? 'M' : 'D')
-          RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}ratio_devices:#{ts}", expire) if expire
-        end        
-      end
-
-      def visit_time(t, visit_end_time = nil)
-        for_each_time_range(t) do |ts, expire|
-          RedisAnalytics.redis_connection.incrby("#{@redis_key_prefix}visit_time:#{ts}", t.to_i - visit_end_time)
-          RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}visit_time:#{ts}", expire) if expire
-        end
-      end
-
-      # 2nd pageview in a visit
-      def page_view(t, second_page_view = false)
-        for_each_time_range(t) do |ts, expire|
-          RedisAnalytics.redis_connection.incr("#{@redis_key_prefix}page_views:#{ts}")
-          RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}page_views:#{ts}", expire) if expire
-
-          RedisAnalytics.redis_connection.incr("#{@redis_key_prefix}second_page_views:#{ts}") if second_page_view
-          RedisAnalytics.redis_connection.expire("#{@redis_key_prefix}second_page_views:#{ts}", expire) if second_page_view and expire
-        end
-      end
-
-
     end
   end
 end