bluecap 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) Christopher Wright
+
+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,115 @@
+# Bluecap
+
+Bluecap is a Redis-backed system for measuring user engagement over time. It
+tracks events passed in from external systems, such as when a user creates an
+account, logs in or performs some other key action. Bluecap can also track
+properties of users like their gender or location.
+
+Systems can then query Bluecap for data on how a group of users engages with
+a product over time, e.g.: for users that created an account a month ago, what
+percentage of these users have logged into their account since then? How about
+the same report, but only for users that are living in Australia?
+
+## Installation
+
+Bluecap requires Ruby 1.9.2 or greater, and Redis 2.5.11 or greater for access
+to bitcount and bitop commands. Install the gem by running:
+
+    gem install bluecap
+
+## Usage
+
+Run the server:
+
+    bluecap
+
+By default this will run Bluecap on `0.0.0.0:6088` with Redis on 
+`localhost:6379`. Run `bluecap -h` for options.
+
+The server responds to JSON messages received over TCP, the root level key in
+the JSON indicates the type of message being sent. Valid message types are:
+`identify`, `event`, `attributes` and `report`.
+
+### Identify a user
+
+Send Bluecap a string that uniquely identifies the user in your own system:
+
+    {"identify": "Charlotte"}
+    # => 1
+
+    {"identify": {"brian@example.com"}
+    # => 2
+
+The server responds with an integer id. When tracking events for the user, the
+id is passed along with event data.
+
+### Tracking events
+
+Send the id, name of the event to track, and optionally a UNIX timestamp: 
+
+    {"event": {"id": 1, "name": "Created Account", "timestamp": "1341845456"}}
+
+### Setting user attributes
+
+Send the id and a hash of attributes to set:
+
+    {
+      "attributes": {
+        "id": 1,
+        "attributes": {
+          "gender": "Female",
+          "country": "Australia"
+        }
+    }
+
+### Generating a report
+
+The reports generate retention for users over a date range. The report requires
+an initial event name to identify cohorts, an event name that measures
+engagement, a date range and optional attributes to limit the users contained
+in the report:
+
+    {
+      "report": {
+        "initial_event": "Created Account",
+        "engagement_event": "Logged In",
+        "attributes": {
+          "country": "Australia",
+          "gender": "Female"
+        },
+        "start_date": "20120701",
+        "end_date": "20120731",
+      }
+    }
+
+A report is returned in JSON format showing the engagement over time for each
+cohort, e.g.:
+
+    {
+      "20120701": {
+        "total": 3751,
+        "engagement": {
+          "20120702": 53.97,
+          "20120703": 43.22,
+          ...
+        },
+      },
+      "20120702": {
+        "total": 4099,
+        "engagement": {
+          "20120703": 55.81,
+          "20120704": 46.73,
+          ...
+        },
+      } 
+    }
+
+## Development
+
+Clone the repository and run the tests:
+
+    git clone git://github.com/christopherwright/bluecap.git
+    cd bluecap
+    rspec
+
+The tests will attempt to create a Redis instance by running `redis-server`.

data/bin/bluecap

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.dirname(__FILE__) + '/../lib'
+require 'rubygems'
+require 'bundler/setup'
+require 'optparse'
+require 'bluecap'
+
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: bluecap [options]'
+
+  opts.separator ''
+  opts.separator 'Options:'
+
+  opts.on('-r', '--redis [HOST:PORT]', 'Redis connection string') do |redis|
+    Bluecap.redis = redis
+  end
+
+  opts.on('-b', '--bind [HOST]', 'Hostname to bind to') do |host|
+    Bluecap.host = host
+  end
+
+  opts.on('-p', '--port [PORT]', 'Port to listen on') do |port|
+    Bluecap.port = port
+  end
+
+  opts.on('-h', '--help', 'Show this message') do
+    puts opts
+    exit
+  end
+end
+
+parser.parse!
+Bluecap.log 'Starting server'
+server = Bluecap::Server.run

data/lib/bluecap.rb

@@ -0,0 +1,78 @@
+require 'eventmachine'
+require 'redis'
+require 'multi_json'
+
+require 'bluecap/keys'
+require 'bluecap/message'
+require 'bluecap/cohort'
+require 'bluecap/engagement'
+require 'bluecap/server'
+require 'bluecap/handlers/attributes'
+require 'bluecap/handlers/event'
+require 'bluecap/handlers/identify'
+require 'bluecap/handlers/null_handler'
+require 'bluecap/handlers/report'
+
+module Bluecap
+
+  extend self
+
+  # Connect to Redis and store the resulting client.
+  #
+  # server - A String of conncetion details in host:port format.
+  #
+  # Examples
+  #
+  #   redis = 'localhost:6379'
+  #
+  # Returns nothing.
+  def redis=(server)
+    host, port, database = server.split(':')
+    @redis = Redis.new(host: host, port: port, database: database)
+  end
+
+  # Returns the Redis client, creating a new client if one does not already
+  # exist.
+  def redis
+    return @redis if @redis
+    self.redis = 'localhost:6379'
+    self.redis
+  end
+
+  # Set the host to bind to.
+  #
+  # Returns nothing.
+  def host=(host)
+    @host = host
+  end
+
+  # Returns the String host to bind to.
+  def host
+    return @host if @host
+    self.host = '0.0.0.0'
+    self.host
+  end
+
+  # Set the port to bind to.
+  #
+  # Returns nothing.
+  def port=(port)
+    @port = port
+  end
+
+  # Returns the Integer port to bind to.
+  def port
+    return @port if @port
+    self.port = 6088
+    self.port
+  end
+
+  # Log a message to STDOUT.
+  #
+  # Returns nothing.
+  def log(message)
+    time = Time.now.strftime('%Y-%m-%d %H:%M:%S')
+    puts "#{time} - #{message}"
+  end
+
+end

data/lib/bluecap/cohort.rb

@@ -0,0 +1,92 @@
+module Bluecap
+  class Cohort
+
+    attr_reader :initial_event, :attributes, :date, :report_id
+
+    # Initialize a Cohort.
+    #
+    # options - A Hash containing options to define the cohort:
+    #           :initial_event - The String event that members of the cohort
+    #                            shared.
+    #           :attributes    - The Hash attributes of cohort members.
+    #           :date          - The Date the initial event occurred on.
+    #           :report_id     - The Integer identifier of the report this
+    #                            cohort is being used with.
+    #
+    # Examples
+    #
+    #   Bluecap::Cohort.new :initial_event => 'Created Account',
+    #     :attributes => {:country => 'Australia', :gender => 'Female'},
+    #     :date => Date.parse('20120701'),
+    #     :report_id => 1
+    def initialize(options)
+      @initial_event = options.fetch(:initial_event)
+      @attributes = options.fetch(:attributes, Hash.new)
+      @date = options.fetch(:date)
+      @report_id = options.fetch(:report_id)
+    end
+
+    # Convert the date of the cohort to a string.
+    #
+    # Returns the String date.
+    def date_str
+      @date.strftime("%Y%m%d")
+    end
+
+    # An identifier for the cohort. The date of the initial event is currently
+    # unique for each cohort in a report, but that might change in the future if
+    # cohorts are not limited to the initial event occurring on a single day.
+    #
+    # Returns the String id.
+    def id
+      date_str
+    end
+
+    # A Redis key containing a bitmask of all the properties for this cohort.
+    # The method is memoized since the bitmask is cached in Redis for an hour.
+    #
+    # Returns the String key name in Redis.
+    def key
+      return @key if @key
+
+      key_name = Bluecap::Keys.cohort(@report_id, id)
+      Bluecap.redis.multi do
+        Bluecap.redis.bitop('and', key_name, keys)
+        Bluecap.redis.expire(key_name, 3600)
+      end
+      @key = key_name
+    end
+
+    # Generate an array of Redis keys where the attributes of users in the
+    # cohort can be found.
+    #
+    # Returns the Array of String keys.
+    def keys_for_attributes
+      attributes = Bluecap::Attributes.new :id => 0, :attributes => @attributes
+      attributes.keys
+    end
+
+    # Generate an array of Redis keys for use in creating a bitmask of the
+    # cohort. This consists of the bitset of the users with the initial event
+    # along with all the attributes of the cohort.
+    #
+    # Returns the Array of String keys.
+    def keys
+      keys_for_initial_event = Array.new
+      keys_for_initial_event.push(Bluecap::Keys.event(@initial_event, date_str))
+      keys_for_initial_event += keys_for_attributes
+    end
+
+    # Calculate the total number of users in this cohort by doing a bitcount
+    # on the cohort bitmask. The method is memoized as the calculation is
+    # expensive.
+    #
+    # Returns the Integer total.
+    def total
+      return @total if @total
+
+      @total = Bluecap.redis.bitcount(key) || 0
+    end
+
+  end
+end

data/lib/bluecap/engagement.rb

@@ -0,0 +1,79 @@
+module Bluecap
+  class Engagement
+
+    # Initialize an Engagement class to measure Cohort retention.
+    #
+    # options - A hash containing options that define the engagement.
+    #           :cohort           - The Cohort to measure engagement for.
+    #           :engagement_event - The String event that defines engagement.
+    #           :start_date       - The Date starting period to measure
+    #                               engagement for.
+    #           :end_date         - The Date ending period to measure
+    #                               engagement for.
+    #           :report_id        - The Integer identifier of the report this
+    #                               cohort is being used with.
+    #
+    # Examples
+    #
+    #   engagement = Bluecap::Engagement.new :cohort => cohort,
+    #     :engagement_event => 'Logged In',
+    #     :start_date => Date.parse('20120702'),
+    #     :end_date => Date.parse('20120707'),
+    #     :report_id => 1
+    def initialize(options)
+      @cohort = options.fetch(:cohort)
+      @engagement_event = options.fetch(:engagement_event)
+      @start_date = options.fetch(:start_date)
+      @end_date = options.fetch(:end_date)
+      @report_id = options.fetch(:report_id)
+    end
+
+    # A key name in Redis where the bitcount operation for engagement on a
+    # date should be stored.
+    #
+    # Returns the String key name.
+    def key(date)
+      Bluecap::Keys.engagement(@report_id, @cohort.id, date.strftime('%Y%m%d'))
+    end
+
+    # The keys that comprise the bitmask for the engagement on a date.
+    #
+    # Returns the Array of String keys.
+    def keys(date)
+      [@cohort.key, Bluecap::Keys.event(@engagement_event, date.strftime('%Y%m%d'))]
+    end
+
+    # Measure the engagement of a cohort over a given period.
+    #
+    # Examples
+    #
+    #    measure
+    #    # => {"20120702" =>  100.0, "20120703" => 50.0, ...}
+    #
+    # Returns a Hash with engagement percentages for each day in the period.
+    def measure
+      results = Hash.new
+      (@start_date..@end_date).each do |date|
+        key_name = key(date)
+        Bluecap.redis.multi do
+          Bluecap.redis.bitop('and', key_name, keys(date))
+          Bluecap.redis.expire(key_name, 3600)
+        end
+        sum_for_day = Bluecap.redis.bitcount(key_name) || 0
+
+        if not @cohort.total.zero?
+          engagement_for_day = (sum_for_day.to_f / @cohort.total)
+        else
+          engagement_for_day = 0.to_f
+        end
+        engagement_for_day *= 100.0
+        engagement_for_day.round(2)
+
+        results[date.strftime('%Y%m%d')] = engagement_for_day
+      end
+
+      results
+    end
+
+  end
+end

data/lib/bluecap/handlers/attributes.rb

@@ -0,0 +1,68 @@
+module Bluecap
+  class Attributes
+
+    attr_reader :id, :attributes
+
+    # Initialize an Attributes handler.
+    #
+    # data - A Hash containing attributes to set for a user:
+    #        :attributes - The hash key/value pairs to be set.
+    #        :id - The id of the user to set the attributes for.
+    #
+    # Examples
+    #
+    #   Bluecap::Attributes.new(
+    #     id: 3,
+    #     attributes: {
+    #       gender: 'Female',
+    #       country: 'Australia'
+    #     }
+    #   )
+    def initialize(data)
+      @id = data.fetch(:id)
+      @attributes = data.fetch(:attributes)
+    end
+
+    # Returns keys for each of the attributes.
+    #
+    # Examples
+    #
+    #   attributes = Bluecap::Attributes.new(
+    #     id:3,
+    #     attributes: {
+    #       gender: 'Female',
+    #       country: 'Australia'
+    #     }
+    #   attributes.keys
+    #   # => ["attributes:gender:female", "attributes:country:australia"]
+    #
+    # Returns the Array of keys.
+    def keys
+      @attributes.map { |k, v| key(k.to_s, v) }
+    end
+
+    # Returns a cleaned key for an attribute and value.
+    #
+    # Examples
+    #
+    #   key('gender', 'female')
+    #   # => "attributes:gender:female"
+    def key(attribute, value)
+      "attributes:#{Bluecap::Keys.clean(attribute)}:#{Bluecap::Keys.clean(value)}"
+    end
+
+    # Store attributes for a user. Each attribute/value has its own bitset
+    # so this is best used with data that has a limited number of values
+    # (e.g.: gender, country).
+    #
+    # Returns nil.
+    def handle
+      Bluecap.redis.multi do
+        keys.each { |k| Bluecap.redis.setbit(k, @id, 1) }
+      end
+
+      nil
+    end
+
+  end
+end