moses-vanity 1.7.1

data/lib/vanity/helpers.rb

@@ -0,0 +1,66 @@
+module Vanity  
+  # Helper methods available on Object.
+  #
+  # @example From ERB template
+  #   <%= ab_test(:greeting) %> <%= current_user.name %>
+  # @example From Rails controller
+  #   class AccountController < ApplicationController
+  #     def create
+  #       track! :signup
+  #       Acccount.create! params[:account]
+  #     end
+  #   end
+  # @example From ActiveRecord
+  #   class Posts < ActiveRecord::Base
+  #     after_create do |post|
+  #       track! :images if post.type == :image
+  #     end
+  #   end
+  module Helpers
+    
+    # This method returns one of the alternative values in the named A/B test.
+    #
+    # @example A/B two alternatives for a page
+    #   def index
+    #     if ab_test(:new_page) # true/false test
+    #       render action: "new_page"
+    #     else
+    #       render action: "index"
+    #     end
+    #   end
+    # @example Similar, alternative value is page name
+    #   def index
+    #     render action: ab_test(:new_page)
+    #   end
+    # @since 1.2.0
+    def ab_test(name, &block)
+      if Vanity.playground.using_js?
+        @_vanity_experiments ||= {}
+        @_vanity_experiments[name] ||= Vanity.playground.experiment(name).choose
+        value = @_vanity_experiments[name].value
+      else
+        value = Vanity.playground.experiment(name).choose.value
+      end
+
+      if block
+        content = capture(value, &block)
+        block_called_from_erb?(block) ? concat(content) : content
+      else
+        value
+      end
+    end
+
+    # Tracks an action associated with a metric.
+    #
+    # @example
+    #   track! :invitation
+    # @since 1.2.0
+    def track!(name, count = 1)
+      Vanity.playground.track! name, count
+    end
+  end
+end
+
+Object.class_eval do
+  include Vanity::Helpers
+end

data/lib/vanity/metric/active_record.rb

@@ -0,0 +1,85 @@
+module Vanity
+  class Metric
+
+    AGGREGATES = [:average, :minimum, :maximum, :sum]
+
+    # Use an ActiveRecord model to get metric data from database table.  Also
+    # forwards +after_create+ callbacks to hooks (updating experiments).
+    #
+    # Supported options:
+    # :conditions -- Only select records that match this condition
+    # :average -- Metric value is average of this column
+    # :minimum -- Metric value is minimum of this column
+    # :maximum -- Metric value is maximum of this column
+    # :sum -- Metric value is sum of this column
+    # :timestamp -- Use this column to filter/group records (defaults to
+    # +created_at+)
+    #
+    # @example Track sign ups using User model
+    #   metric "Signups" do
+    #     model Account
+    #   end
+    # @example Track satisfaction using Survey model
+    #   metric "Satisfaction" do
+    #     model Survey, :average=>:rating
+    #   end
+    # @example Track only high ratings
+    #   metric "High ratings" do
+    #     model Rating, :conditions=>["stars >= 4"]
+    #   end
+    # @example Track only high ratings (using scope)
+    #   metric "High ratings" do
+    #     model Rating.high
+    #   end
+    #
+    # @since 1.2.0
+    # @see Vanity::Metric::ActiveRecord
+    def model(class_or_scope, options = nil)
+      options = options || {}
+      conditions = options.delete(:conditions)
+      @ar_scoped = conditions ? class_or_scope.scoped(:conditions=>conditions) : class_or_scope
+      @ar_aggregate = AGGREGATES.find { |key| options.has_key?(key) }
+      @ar_column = options.delete(@ar_aggregate)
+      fail "Cannot use multiple aggregates in a single metric" if AGGREGATES.find { |key| options.has_key?(key) }
+      @ar_timestamp = options.delete(:timestamp) || :created_at
+      @ar_timestamp, @ar_timestamp_table = @ar_timestamp.to_s.split('.').reverse
+      @ar_timestamp_table ||= @ar_scoped.table_name
+      fail "Unrecognized options: #{options.keys * ", "}" unless options.empty?
+      @ar_scoped.after_create self
+      extend ActiveRecord
+    end
+
+    # Calling model method on a metric extends it with these modules, redefining
+    # the values and track! methods.
+    #
+    # @since 1.3.0
+    module ActiveRecord
+
+      # This values method queries the database.
+      def values(sdate, edate)
+        query = { :conditions=> { @ar_timestamp_table => { @ar_timestamp => (sdate.to_time...(edate + 1).to_time) } },
+                  :group=>"date(#{@ar_scoped.quoted_table_name}.#{@ar_scoped.connection.quote_column_name @ar_timestamp})" }
+        grouped = @ar_column ? @ar_scoped.send(@ar_aggregate, @ar_column, query) : @ar_scoped.count(query)
+        (sdate..edate).inject([]) { |ordered, date| ordered << (grouped[date.to_s] || 0) }
+      end
+
+      # This track! method stores nothing, but calls the hooks.
+      def track!(args = nil)
+        return unless @playground.collecting?
+        call_hooks *track_args(args)
+      end
+
+      def last_update_at
+        record = @ar_scoped.find(:first, :order=>"#@ar_timestamp DESC", :limit=>1, :select=>@ar_timestamp)
+        record && record.send(@ar_timestamp)
+      end
+
+      # AR model after_create callback notifies all the hooks.
+      def after_create(record)
+        return unless @playground.collecting?
+        count = @ar_column ? (record.send(@ar_column) || 0) : 1
+        call_hooks record.send(@ar_timestamp), nil, [count] if count > 0 && @ar_scoped.exists?(record)
+      end
+    end
+  end
+end

data/lib/vanity/metric/base.rb

@@ -0,0 +1,244 @@
+module Vanity
+
+  # A metric is an object that implements two methods: +name+ and +values+.  It
+  # can also respond to addition methods (+track!+, +bounds+, etc), these are
+  # optional.
+  #
+  # This class implements a basic metric that tracks data and stores it in the
+  # database.  You can use this as the basis for your metric, or as reference
+  # for the methods your metric must and can implement.
+  #
+  # @since 1.1.0
+  class Metric
+
+    # These methods are available when defining a metric in a file loaded
+    # from the +experiments/metrics+ directory.
+    #
+    # For example:
+    #   $ cat experiments/metrics/yawn_sec
+    #   metric "Yawns/sec" do
+    #     description "Most boring metric ever"
+    #   end
+    module Definition
+      
+      attr_reader :playground
+
+      # Defines a new metric, using the class Vanity::Metric.
+      def metric(name, &block)
+        fail "Metric #{@metric_id} already defined in playground" if playground.metrics[@metric_id]
+        metric = Metric.new(playground, name.to_s, @metric_id)
+        metric.instance_eval &block
+        playground.metrics[@metric_id] = metric
+      end
+
+      def new_binding(playground, id)
+        @playground, @metric_id = playground, id
+        binding
+      end
+
+    end
+  
+    # Startup metrics for pirates. AARRR stands for:
+    # * Acquisition
+    # * Activation
+    # * Retention
+    # * Referral
+    # * Revenue
+    # Read more: http://500hats.typepad.com/500blogs/2007/09/startup-metrics.html
+
+    class << self
+
+      # Helper method to return description for a metric.
+      #
+      # A metric object may have a +description+ method that returns a detailed
+      # description.  It may also have no description, or no +description+
+      # method, in which case return +nil+.
+      # 
+      # @example
+      #   puts Vanity::Metric.description(metric)
+      def description(metric)
+        metric.description if metric.respond_to?(:description)
+      end
+
+      # Helper method to return bounds for a metric.
+      #
+      # A metric object may have a +bounds+ method that returns lower and upper
+      # bounds.  It may also have no bounds, or no +bounds+ # method, in which
+      # case we return +[nil, nil]+.
+      # 
+      # @example
+      #   upper = Vanity::Metric.bounds(metric).last
+      def bounds(metric)
+        metric.respond_to?(:bounds) && metric.bounds || [nil, nil]
+      end
+
+      # Returns data set for a given date range.  The data set is an array of
+      # date, value pairs.
+      #
+      # First argument is the metric.  Second argument is the start date, or
+      # number of days to go back in history, defaults to 90 days.  Third
+      # argument is end date, defaults to today.
+      #
+      # @example These are all equivalent:
+      #   Vanity::Metric.data(my_metric) 
+      #   Vanity::Metric.data(my_metric, 90) 
+      #   Vanity::Metric.data(my_metric, Date.today - 89)
+      #   Vanity::Metric.data(my_metric, Date.today - 89, Date.today)
+      def data(metric, *args)
+        first = args.shift || 90
+        to = args.shift || Date.today
+        from = first.respond_to?(:to_date) ? first.to_date : to - (first - 1)
+        (from..to).zip(metric.values(from, to))
+      end
+
+      # Playground uses this to load metric definitions.
+      def load(playground, stack, file)
+        fail "Circular dependency detected: #{stack.join('=>')}=>#{file}" if stack.include?(file)
+        source = File.read(file)
+        stack.push file
+        id = File.basename(file, ".rb").downcase.gsub(/\W/, "_").to_sym
+        context = Object.new
+        context.instance_eval do
+          extend Definition
+          metric = eval(source, context.new_binding(playground, id), file)
+          fail NameError.new("Expected #{file} to define metric #{id}", id) unless playground.metrics[id]
+          metric
+        end
+      rescue
+        error = NameError.exception($!.message, id)
+        error.set_backtrace $!.backtrace
+        raise error
+      ensure
+        stack.pop
+      end
+
+    end
+
+
+    # Takes playground (need this to access Redis), friendly name and optional
+    # id (can infer from name).
+    def initialize(playground, name, id = nil)
+      @playground, @name = playground, name.to_s
+      @id = (id || name.to_s.downcase.gsub(/\W+/, '_')).to_sym
+      @hooks = []
+    end
+
+
+    # -- Tracking --
+
+    # Called to track an action associated with this metric. Most common is not
+    # passing an argument, and it tracks a count of 1. You can pass a different
+    # value as the argument, or array of value (for multi-series metrics), or
+    # hash with the optional keys timestamp, identity and values.
+    #
+    # Example:
+    #   hits.track!
+    #   foo_and_bar.track! [5,11]
+    def track!(args = nil)
+      return unless @playground.collecting?
+      timestamp, identity, values = track_args(args)
+      connection.metric_track @id, timestamp, identity, values
+      @playground.logger.info "vanity: #{@id} with value #{values.join(", ")}"
+      call_hooks timestamp, identity, values
+    end
+
+    # Parses arguments to track! method and return array with timestamp,
+    # identity and array of values.
+    def track_args(args)
+      case args
+      when Hash
+        timestamp, identity, values = args.values_at(:timestamp, :identity, :values)
+      when Array
+        values = args
+      when Numeric
+        values = [args]
+      end
+        identity = Vanity.context.vanity_identity rescue nil
+      [timestamp || Time.now, identity, values || [1]]
+    end
+    protected :track_args
+
+    # Metric definitions use this to introduce tracking hook.  The hook is
+    # called with metric identifier, timestamp, count and possibly additional
+    # arguments.
+    #
+    # For example:
+    #   hook do |metric_id, timestamp, count|
+    #     syslog.info metric_id
+    #   end
+    def hook(&block)
+      @hooks << block
+    end
+
+    # This method returns the acceptable bounds of a metric as an array with
+    # two values: low and high.  Use nil for unbounded.
+    #
+    # Alerts are created when metric values exceed their bounds.  For example,
+    # a metric of user registration can use historical data to calculate
+    # expected range of new registration for the next day.  If actual metric
+    # falls below the expected range, it could indicate registration process is
+    # broken.  Going above higher bound could trigger opening a Champagne
+    # bottle.
+    #
+    # The default implementation returns +nil+.
+    def bounds
+    end
+    
+
+    #  -- Reporting --
+    
+    # Human readable metric name.  All metrics must implement this method.
+    attr_reader :name
+    alias :to_s :name
+
+    # Human readable description.  Use two newlines to break paragraphs.
+    attr_accessor :description
+
+    # Sets or returns description. For example
+    #   metric "Yawns/sec" do
+    #     description "Most boring metric ever"
+    #   end
+    #
+    #   puts "Just defined: " + metric(:boring).description
+    def description(text = nil)
+      @description = text if text
+      @description
+    end
+
+    # Given two arguments, a start date and an end date (inclusive), returns an
+    # array of measurements.  All metrics must implement this method.
+    def values(from, to)
+      values = connection.metric_values(@id, from, to)
+      values.map { |row| row.first.to_i }
+    end
+
+    # Returns date/time of the last update to this metric.
+    #
+    # @since 1.4.0
+    def last_update_at
+      connection.get_metric_last_update_at(@id)
+    end
+
+
+    # -- Storage --
+
+    def destroy!
+      connection.destroy_metric @id
+    end
+
+    def connection
+      @playground.connection
+    end
+
+    def key(*args)
+      "metrics:#{@id}:#{args.join(':')}"
+    end
+
+    def call_hooks(timestamp, identity, values)
+      @hooks.each do |hook|
+        hook.call @id, timestamp, values.first || 1
+      end
+    end
+
+  end
+end

data/lib/vanity/metric/google_analytics.rb

@@ -0,0 +1,83 @@
+module Vanity
+  class Metric
+    
+    # Use Google Analytics metric.  Note: you must +require "garb"+ before
+    # vanity.
+    # 
+    # @example Page views
+    #   metric "Page views" do
+    #     google_analytics "UA-1828623-6"
+    #   end
+    # @example Visits
+    #   metric "Visits" do
+    #     google_analytics "UA-1828623-6", :visits
+    #   end
+    #
+    # @since 1.3.0
+    # @see Vanity::Metric::GoogleAnalytics
+    def google_analytics(web_property_id, *args)
+      require "garb"
+      options = Hash === args.last ? args.pop : {}
+      metric = args.shift || :pageviews
+      @ga_resource = Vanity::Metric::GoogleAnalytics::Resource.new(web_property_id, metric)
+      @ga_mapper = options[:mapper] ||= lambda { |entry| entry.send(@ga_resource.metrics.elements.first).to_i }
+      extend GoogleAnalytics
+    rescue LoadError
+      fail LoadError, "Google Analytics metrics require Garb, please gem install garb first"
+    end
+
+    # Calling google_analytics method on a metric extends it with these modules,
+    # redefining the values and hook methods.
+    #
+    # @since 1.3.0
+    module GoogleAnalytics
+
+      # Returns values from GA using parameters specified by prior call to
+      # google_analytics.
+      def values(from, to)
+        data = @ga_resource.results(from, to).inject({}) do |hash,entry|
+          hash.merge(entry.date=>@ga_mapper.call(entry))
+        end
+        (from..to).map { |day| data[day.strftime('%Y%m%d')] || 0 }
+      end
+      
+      # Hooks not supported for GA metrics.
+      def hook
+        fail "Cannot use hooks with Google Analytics methods"
+      end
+
+      # Garb report.
+      def report
+        @ga_resource
+      end
+
+      # Unkown (for now).
+      def last_update_at
+      end
+
+      def track!(args = nil)
+      end
+
+      class Resource
+        # GA profile used for this report.  Populated after calling results. 
+        attr_reader :profile
+
+        def initialize(web_property_id, metric)
+          self.class.send :include, Garb::Resource
+          @web_property_id = web_property_id
+          metrics metric
+          dimensions :date
+          sort :date
+        end
+
+        def results(start_date, end_date)
+          @profile = Garb::Profile.all.find { |p| p.web_property_id == @web_property_id }
+          @start_date = start_date
+          @end_date = end_date
+          Garb::ReportResponse.new(send_request_for_body).results
+        end
+      end
+
+    end
+  end
+end