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 arbitrary properties of users like A/B variants, IP address 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?

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

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.

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.

Send the id, name of the event to track, and optionally a UNIX timestamp:

{"event": {"id": 1, "name": "Created Account", "timestamp": "1341845456"}}

Send the id and a hash of attributes to set:

{
  "attributes": {
    "id": 1,
    "attributes": {
      "ab_variant": "blue",
      "country": "Australia"
    }
}

The reports measure 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",
      "ab_variant": "blue"
    },
    "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,
      ...
    },
  } 
}

The engagement figure is a percentage of users for a cohort who have performed the engagement event since the initial event. In the example above, a cohort is made up of all the users who are female, live in Australia, and created an account on the same day as each other. The engagement is a calculation of how many of the users in that cohort logged into the site for each day from when they created an account until the end of the reporting period.

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.