Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Scalable, Real-time Metric Tracking for Rails
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
generators
lib
rails
test
.gitignore
MIT-LICENSE
README.markdown
Rakefile
init.rb

README.markdown

Clarify

A Scalable, Real-time Event Tracking Framework for Rails

Usage

1. Install

sudo gem install clarify

2. Define Metrics

Inside config/metrics.rb do:

Clarify do
  event :publish_stream
  event :stream_referral

  ab_test :publishing_button_color do
    events :publish_stream
    options "a", "b", "c"
  end
end

3. Add to Controller

It defaults to :current_user, but if you call your user something else, change it there.

class ApplicationController < ActionController::Base
  clarify :current_user
end

4. A/B Test

Present the different options to your users:

<h2>Get started for only $<%= ab_test :price_options %> a month!</h2>

5. Track Result

class SignupController < ApplicationController
  def signup
    @account = Account.new(params[:account])
    if @account.save
      track! :signups
      redirect_to @acccount
    else
      render action: :offer
    end
  end
end

How it works

It only uses one table where it stores a key for each metric. Even for A/B tests. Everything is then stored in memory.

puts Clarify.inspect
  #<Clarify
    :events => [
      {
        :name => :publish_stream,
        :ab_tests => [:publishing_button_color]
      },
      {
        :name => :stream_referral
      }
    },
    :ab_tests => [
      {
        :name => :publishing_button_color,
        :options => ["a", "b", "c"]
      }
    ],
    :metrics => [
      "publish_stream",
      "event:publish_stream,ab_test:publishing_button_color,option:a,type:participant",
      "event:publish_stream,ab_test:publishing_button_color,option:a,type:conversion",
      "event:publish_stream,ab_test:publishing_button_color,option:b,type:participant",
      "event:publish_stream,ab_test:publishing_button_color,option:b,type:conversion",
      "event:publish_stream,ab_test:publishing_button_color,option:c,type:participant",
      "event:publish_stream,ab_test:publishing_button_color,option:c,type:conversion",
      "stream_referral"
    ]
  >

Terms

  • Metric: Unique configuration of attributes, associated with a "Conversion". Metrics are the only thing stored in the database.
  • Conversion: Generic key for aggregating metric results. Can be associated with multiple Experiments.
  • Experiment: Collection of Alternatives for a given Conversion, for a Property.
  • Option: Property that is changed between Metrics, for a given Conversion, for an Experiment. Aka "Alternative".

Flow

Here is the method chain:

ab_test(key)
  Clarify.choose!(key, user)
    Clarify::Analytics#choose!(user)
      Clarify::AbTest#choose!(user)
  Clarify.participate!(key, user)
    Clarify::Analytics#participate!(key, user)
      Clarify::Event#participate!(user)
        Clarify::AbTest#participate!(user)
          Clarify::Option#participate!
            Clarify::Metric#increment!
track!(key)
  Clarify.convert!(key, user)
    Clarify::Analytics#convert!(key, user)
      Clarify::Event#convert!(user)
        Clarify::Metric#increment!
        Clarify::AbTest#convert!(user)
          Clarify::Option#convert!
            Clarify::Metric#increment!

Tests

rake test

Goals

  • Fine grained event tracking
  • A/B Testing
  • Memcached integration
  • Heroku compatible
  • Abstracts away Memcache (and CACHE)

Alternatives

  • Vanity:
    • Uses Redis which is basically MySQL and Memcached combined.
    • Very fast
    • Requires file system access (can't use with Heroku)
  • A/Bingo
    • A/B Testing framework
  • MixPanel
    • Paid service with Free option (10,000 data points per month)
    • $1000/month for 8,000,000 data points (large scale apps with fine-grained, real-time event tracking)

Todo

  • Make it so CacheCounter works on instances rather than classes. Otherwise we have to reset the entire in-memory collection whenever a metric is updated.
  • Allow so you can customize the key saved to the DB
  • Clear up how we define CACHE. Should probably be namespaced
  • Override Clarify::Metric.find so we can automatically find by key.
  • Doesn't have complete! functionality, so you have to manually check which one is better at some point and choose that.
  • Refactor out the User, don't really need it. Instead, the find_options_for_user method can be choose!, and we can use meta programming to get a clarify_identifier from the controller.
  • Do we need a count id def track!(name, count = 1)?

Resources

Something went wrong with that request. Please try again.