vanity 1.8.4 → 1.9.0.beta

data/lib/vanity/helpers.rb

@@ -1,4 +1,4 @@
-module Vanity  
+module Vanity
   # Helper methods available on Object.
   #
   # @example From ERB template
@@ -17,7 +17,7 @@ module Vanity
   #     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
@@ -34,12 +34,14 @@ module Vanity
     #   end
     # @since 1.2.0
     def ab_test(name, &block)
+      # TODO refactor with Vanity::Rails::Helpers#ab_test
+      request = respond_to?(:request) ? self.request : nil
       if Vanity.playground.using_js?
         @_vanity_experiments ||= {}
-        @_vanity_experiments[name] ||= Vanity.playground.experiment(name).choose
+        @_vanity_experiments[name] ||= Vanity.playground.experiment(name).choose(request)
         value = @_vanity_experiments[name].value
       else
-        value = Vanity.playground.experiment(name).choose.value
+        value = Vanity.playground.experiment(name).choose(request).value
       end
 
       if block

data/lib/vanity/metric/active_record.rb

@@ -3,7 +3,7 @@ module Vanity
 
     AGGREGATES = [:average, :minimum, :maximum, :sum]
 
-    # Use an ActiveRecord model to get metric data from database table.  Also
+    # Use an ActiveRecord model to get metric data from database table. Also
     # forwards +after_create+ callbacks to hooks (updating experiments).
     #
     # Supported options:

data/lib/vanity/metric/base.rb

@@ -1,11 +1,11 @@
 module Vanity
 
-  # A metric is an object that implements two methods: +name+ and +values+.  It
+  # 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
+  # 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
@@ -20,7 +20,7 @@ module Vanity
     #     description "Most boring metric ever"
     #   end
     module Definition
-      
+
       attr_reader :playground
 
       # Defines a new metric, using the class Vanity::Metric.
@@ -37,7 +37,7 @@ module Vanity
       end
 
     end
-  
+
     # Startup metrics for pirates. AARRR stands for:
     # * Acquisition
     # * Activation
@@ -45,15 +45,14 @@ module Vanity
     # * 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+
+      # 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)
@@ -63,25 +62,25 @@ module Vanity
       # 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
+      # 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
+      # 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
+      # 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)
+      #   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)
@@ -158,7 +157,7 @@ module Vanity
     end
     protected :track_args
 
-    # Metric definitions use this to introduce tracking hook.  The hook is
+    # Metric definitions use this to introduce tracking hook. The hook is
     # called with metric identifier, timestamp, count and possibly additional
     # arguments.
     #
@@ -171,27 +170,27 @@ module Vanity
     end
 
     # This method returns the acceptable bounds of a metric as an array with
-    # two values: low and high.  Use nil for unbounded.
+    # two values: low and high. Use nil for unbounded.
     #
-    # Alerts are created when metric values exceed their bounds.  For example,
+    # 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
+    # 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
+    # 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.
+
+    # 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.
+    # Human readable description. Use two newlines to break paragraphs.
     attr_accessor :description
 
     # Sets or returns description. For example
@@ -206,7 +205,7 @@ module Vanity
     end
 
     # Given two arguments, a start date and an end date (inclusive), returns an
-    # array of measurements.  All metrics must implement this method.
+    # 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 }

data/lib/vanity/metric/google_analytics.rb

@@ -1,9 +1,9 @@
 module Vanity
   class Metric
-    
-    # Use Google Analytics metric.  Note: you must +require "garb"+ before
+
+    # Use Google Analytics metric. Note: you must +require "garb"+ before
     # vanity.
-    # 
+    #
     # @example Page views
     #   metric "Page views" do
     #     google_analytics "UA-1828623-6"
@@ -40,7 +40,7 @@ module Vanity
         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"
@@ -59,7 +59,7 @@ module Vanity
       end
 
       class Resource
-        # GA profile used for this report.  Populated after calling results. 
+        # GA profile used for this report. Populated after calling results.
         attr_reader :profile
 
         def initialize(web_property_id, metric)

data/lib/vanity/playground.rb

@@ -16,7 +16,7 @@ module Vanity
     # Vanity.playground.
     #
     # First argument is connection specification (see #redis=), last argument is
-    # a set of options, both are optional.  Supported options are:
+    # a set of options, both are optional. Supported options are:
     # - connection -- Connection specification
     # - namespace -- Namespace to use
     # - load_path -- Path to load experiments/metrics from
@@ -26,7 +26,7 @@ module Vanity
       options = Hash === args.last ? args.pop : {}
       # In the case of Rails, use the Rails logger and collect only for
       # production environment by default.
-      defaults = options[:rails] ? DEFAULTS.merge(:collecting => ::Rails.env.production?, :logger => ::Rails.logger) : DEFAULTS
+      defaults = options[:rails] ? DEFAULTS.merge(:collecting => true, :logger => ::Rails.logger) : DEFAULTS
       if config_file_exists?
         env = ENV["RACK_ENV"] || ENV["RAILS_ENV"] || "development"
         config = load_config_file[env]
@@ -52,6 +52,7 @@ module Vanity
 
       @loading = []
       @use_js = false
+      @failover_on_datastore_error = false
       self.add_participant_path = DEFAULT_ADD_PARTICIPANT_PATH
       @collecting = !!@options[:collecting]
     end
@@ -65,9 +66,13 @@ module Vanity
     # Logger.
     attr_accessor :logger
 
-    # Path to the add_participant action, necessary if you have called use_js!
+    # Path to the add_participant action.
     attr_accessor :add_participant_path
 
+    attr_accessor :on_datastore_error
+
+    attr_accessor :request_filter
+
     # Defines a new experiment. Generally, do not call this directly,
     # use one of the definition methods (ab_test, measure, etc).
     #
@@ -87,7 +92,6 @@ module Vanity
     # an exception if it cannot load the experiment's definition.
     #
     # @see Vanity::Experiment
-
     def experiment(name)
       id = name.to_s.downcase.gsub(/\W/, "_").to_sym
       warn "Deprecated: pleae call experiment method with experiment identifier (a Ruby symbol)" unless id == name
@@ -102,33 +106,35 @@ module Vanity
     #  when converted to_s (so could be used for caching, for example)
     def participant_info(participant_id)
       participant_array = []
-      experiments.values.sort_by{|e| e.name}.each do |e|
+      experiments.values.sort_by(&:name).each do |e|
         index = connection.ab_assigned(e.id, participant_id)
         if index
           participant_array << [e, e.alternatives[index.to_i]]
         end
       end
-      return participant_array
+      participant_array
     end
 
+
     # -- Robot Detection --
 
-    # Call to indicate that participants should be added via js
-    # This helps keep robots from participating in the ab test
-    # and skewing results.
+    # Call to indicate that participants should be added via js. This helps
+    # keep robots from participating in the A/B test and skewing results.
     #
-    # If you use this, there are two more steps:
-    # - Set Vanity.playground.add_participant_path = '/path/to/vanity/action',
-    #   this should point to the add_participant path that is added with
-    #   Vanity::Rails::Dashboard, make sure that this action is available
-    #   to all users
+    # If you want to use this:
     # - Add <%= vanity_js %> to any page that needs uses an ab_test. vanity_js
     #   needs to be included after your call to ab_test so that it knows which
-    #   version of the experiment the participant is a member of.  The helper
+    #   version of the experiment the participant is a member of. The helper
     #   will render nothing if the there are no ab_tests running on the current
     #   page, so adding vanity_js to the bottom of your layouts is a good
-    #   option.  Keep in mind that if you call use_js! and don't include
+    #   option. Keep in mind that if you call use_js! and don't include
     #   vanity_js in your view no participants will be recorded.
+    #
+    # Note that a custom JS callback path can be set using:
+    # - Set Vanity.playground.add_participant_path = '/path/to/vanity/action',
+    #   this should point to the add_participant path that is added with
+    #   Vanity::Rails::Dashboard, make sure that this action is available
+    #   to all users.
     def use_js!
       @use_js = true
     end
@@ -138,7 +144,91 @@ module Vanity
     end
 
 
-    # Returns hash of experiments (key is experiment id).
+    # -- Datastore graceful failover --
+
+    # Turns on passing of errors to the Proc returned by #on_datastore_error.
+    # Call Vanity.playground.failover_on_datastore_error! to turn this on.
+    #
+    # @since 1.9.0
+    def failover_on_datastore_error!
+      @failover_on_datastore_error = true
+    end
+
+    # Returns whether to failover on an error raise by the datastore adapter.
+    #
+    # @since 1.9.0
+    def failover_on_datastore_error?
+      @failover_on_datastore_error
+    end
+
+    # Must return a Proc that accepts as parameters: the thrown error, the
+    # calling Class, the calling method, and an array of arguments passed to
+    # the calling method. The return value is ignored.
+    #
+    #    Proc.new do |error, klass, method, arguments|
+    #      ...
+    #    end
+    #
+    # The default implementation logs this information to Playground#logger.
+    #
+    # Set a custom action by calling Vanity.playground.on_datastore_error =
+    # Proc.new { ... }.
+    #
+    # @since 1.9.0
+    def on_datastore_error
+      @on_datastore_error || default_on_datastore_error
+    end
+
+    def default_on_datastore_error # :nodoc:
+      Proc.new do |error, klass, method, arguments|
+        log = "[#{Time.now.iso8601}]"
+        log << " [vanity #{klass} #{method}]"
+        log << " [#{error.message}]"
+        log << " [#{arguments.join(' ')}]"
+        @logger.error(log)
+        nil
+      end
+    end
+    protected :default_on_datastore_error
+
+
+    # -- Blocking or ignoring visitors --
+
+    # Must return a Proc that accepts as a parameter the request object, if
+    # made available by the implement framework. The return value should be a
+    # boolean whether to ignore the request. This is called only for the JS
+    # callback action.
+    #
+    #    Proc.new do |request|
+    #      ...
+    #    end
+    #
+    # The default implementation does a simple test of whether the request's
+    # HTTP_USER_AGENT header contains a URI, since well behaved bots typically
+    # include a reference URI in their user agent strings. (Original idea:
+    # http://stackoverflow.com/a/9285889.)
+    #
+    # Alternatively, one could filter an explicit list of IPs, add additional
+    # user agent strings to filter, or any custom test. Set a custom filter
+    # by calling Vanity.playground.request_filter = Proc.new { ... }.
+    #
+    # @since 1.9.0
+    def request_filter
+      @request_filter || default_request_filter
+    end
+
+    def default_request_filter # :nodoc:
+      Proc.new do |request|
+        request &&
+          request.env &&
+          request.env["HTTP_USER_AGENT"] &&
+          request.env["HTTP_USER_AGENT"].match(/\(.*https?:\/\/.*\)/)
+      end
+    end
+    protected :default_request_filter
+
+    # Returns hash of experiments (key is experiment id). This create the
+    # Experiment and persists it to the datastore.
     #
     # @see Vanity::Experiment
     def experiments
@@ -153,7 +243,11 @@ module Vanity
       @experiments
     end
 
-    # Reloads all metrics and experiments.  Rails calls this for each request in
+    def experiments_persisted?
+      experiments.keys.all? { |id| connection.experiment_persisted?(id) }
+    end
+
+    # Reloads all metrics and experiments. Rails calls this for each request in
     # development mode.
     def reload!
       @experiments = nil
@@ -161,7 +255,7 @@ module Vanity
       load!
     end
 
-    # Loads all metrics and experiments.  Rails calls this during
+    # Loads all metrics and experiments. Rails calls this during
     # initialization.
     def load!
       experiments
@@ -323,9 +417,7 @@ module Vanity
       establish_connection(@spec)
     end
 
-    # Deprecated. Use Vanity.playground.collecting = true/false instead.  Under
-    # Rails, collecting is true in production environment, false in all other
-    # environments, which is exactly what you want.
+    # Deprecated. Use Vanity.playground.collecting = true/false instead.
     def test!
       warn "Deprecated: use collecting = false instead"
       self.collecting = false
@@ -364,6 +456,8 @@ module Vanity
         if connection_spec
           connection_spec = "redis://" + connection_spec unless connection_spec[/^\w+:/]
           establish_connection connection_spec
+        else
+          establish_connection
         end
       end
     end
@@ -384,13 +478,13 @@ module Vanity
       @playground ||= Playground.new(:rails=>defined?(::Rails))
     end
 
-    # Returns the Vanity context.  For example, when using Rails this would be
+    # Returns the Vanity context. For example, when using Rails this would be
     # the current controller, which can be used to get/set the vanity identity.
     def context
       Thread.current[:vanity_context]
     end
 
-    # Sets the Vanity context.  For example, when using Rails this would be
+    # Sets the Vanity context. For example, when using Rails this would be
     # set by the set_vanity_context before filter (via Vanity::Rails#use_vanity).
     def context=(context)
       Thread.current[:vanity_context] = context

data/lib/vanity/templates/_report.erb

@@ -13,14 +13,28 @@
   </head>
   <body>
     <div class="vanity">
-      <% experiments = Vanity.playground.experiments ; unless experiments.empty? %>
-        <h2>Experiments</h2>
-        <%= render :file=>Vanity.template("_experiments"), :locals=>{:experiments=>experiments} %>
+      <% unless Vanity.playground.collecting? %>
+        <div class="alert">
+          Vanity is currently not collecting data or metrics. To turn on data collection, set <span style='font-family: courier'>Vanity.playground.collecting = true;</span> in <span style='font-family: courier'>config/environments/[environment].rb</span>.
+        </div>
       <% end %>
-      <% metrics = Vanity.playground.metrics ; unless metrics.empty? %>
-        <h2>Metrics</h2>
-        <%= render :file=>Vanity.template("_metrics"), :locals=>{:metrics=>metrics, :experiments=>experiments} %>
+
+      <% if @experiments_persisted %>
+        <% if @experiments.present? %>
+          <h2>Experiments</h2>
+          <%= render :file=>Vanity.template("_experiments"), :locals=>{:experiments=>@experiments} %>
+        <% end %>
+
+        <% unless @metrics.empty? %>
+          <h2>Metrics</h2>
+          <%= render :file=>Vanity.template("_metrics"), :locals=>{:metrics=>@metrics, :experiments=>@experiments} %>
+        <% end %>
+      <% else %>
+        <div class="alert">
+          Vanity's cached experiments are out of sync with those on the filesystem and/or those in the datastore. Please restart your server and/or turn on collecting.
+        </div>
       <% end %>
+
       <p class="footer">Generated by <a href="http://vanity.labnotes.org">Vanity</a></p>
     </div>
   </body>