performance_promise 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0fa56d47d2c2db583f926cd79f5094485853dff9
+  data.tar.gz: 3508721f4c377fe470c1a615d3c84a8e0eeaaaa9
+SHA512:
+  metadata.gz: df5209a3ee5fd6236ed95e65d8b11030376d91ce905c08c081bb4b4bbd4afe405d35b979d69b99279d5f778fb425245d20e1f41c00221f95564b08da89e906f0
+  data.tar.gz: 7865ac4b28c63efc00c279420d6a988eb34b2da69204def8fc36b9ce8cfbd77728449efbe7723d23e3fd8f151f526a34c8d673751362dd92dcb984b1743e49c1

data/.gitignore

@@ -0,0 +1,41 @@
+*.swp
+*.rbc
+capybara-*.html
+.rspec
+/log
+/tmp
+/db/*.sqlite3
+/db/*.sqlite3-journal
+/public/system
+/coverage/
+/spec/tmp
+**.orig
+rerun.txt
+pickle-email-*.html
+
+# TODO Comment out these rules if you are OK with secrets being uploaded to the repo
+config/initializers/secret_token.rb
+config/secrets.yml
+
+## Environment normalisation:
+/.bundle
+/vendor/bundle
+
+Gemfile.lock
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# if using bower-rails ignore default bower_components path bower.json files
+/vendor/assets/bower_components
+*.bowerrc
+bower.json
+
+# Ignore pow environment settings
+.powenv
+
+# Ignore rbenv
+.ruby-version
+
+# Ignore any created gem files
+*.gem

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rspec'
+end

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Bipin Suresh
+
+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,202 @@
+# Performance Promise
+The `performance_promise` gem enables you to annotate and validate the performance of your Rails actions.
+
+You can declare the performance characteristics of your Rails actions in code (right next to the action definition itself), and `performance_promise` will monitor and validate the promise. If the action breaks the promise, the `performance_promise` gem will alert you and provide a helpful suggestion with a passing performance annotation.
+
+Example syntax:
+```ruby
+class ArticlesController < ApplicationController
+
+  Performance :makes => 1.query,
+              :full_table_scans => [Article]
+  def index
+    # ...
+  end
+
+  Performance :makes => 1.query + Article.N.queries,
+              :full_table_scans => [Article, Comment]
+  def expensive_action
+    # ...
+  end
+end
+```
+
+You may also choose to enable a default/minimum performance promise for _all_ actions by turning on the `untagged_methods_are_speedy` config parameter ([see here](https://github.com/bipsandbytes/performance_promise#untagged_methods_are_speedy-bool)). **You can reap all the benefits of performance validation without having to make any changes to code except tagging expensive actions**.
+
+
+## Installation
+You can install it as a gem:
+```sh
+gem install performance_promise
+```
+
+or add it to a Gemfile (Bundler):
+```ruby
+group :development, :test do
+  gem 'performance_promise'
+end
+```
+
+## Building
+You can build the gem yourself:
+```sh
+gem build performance_promise.gemspec
+```
+
+## Configuration
+For safety, `performance_promise` is disabled by default. To enable it, create a new file `config/initializers/performance_promise.rb` with the following code:
+```ruby
+require 'performance_promise/performance.rb'
+
+PerformancePromise.configure do |config|
+  config.enable = true
+  # config.validations = [
+  #   :makes,  # validate the number of DB queries made
+  # ]
+  # config.untagged_methods_are_speedy = true
+  # config.speedy_promise = {
+  #   :makes => 2,
+  # }
+  # config.allowed_environments = [
+  #   'development',
+  #   'test',
+  # ]
+  # config.logger = Rails.logger
+  # config.throw_exception = true
+end
+PerformancePromise.start
+```
+
+## Usage
+To understand how to use `performance_promise`, let's use a simple [Blog App][rails-getting-started]. A `Blog` has `Article`s, each of which may have one or more `Comment`s.
+
+Here is a simple controller:
+```ruby
+class ArticlesController < ApplicationController
+  def index
+    @articles = Article.all
+  end
+end
+```
+Assuming your routes and views are setup, you should be able to succesfully visit `/articles`.
+
+You can annotate this action with a promise of how many database queries the action will make so:
+```ruby
+class ArticlesController < ApplicationController
+
+  Performance :makes => 1.query
+  def index
+    @articles = Article.all
+  end
+
+end
+```
+Visit `/articles` to confirm that the view is rendered successfully again.
+
+Now suppose, you make the view more complex, causing it to execute more database queries
+```ruby
+  Performance :makes => 1.query
+  def index
+    @articles = Article.all
+    @total_comments = 0
+    @articles.each do |article|
+      @total_comments += article.comments.length
+    end
+    puts @total_comments
+  end
+```
+Since the performance annotation has not been updated, visiting `/articles` now will throw an exception. The exception tells you that the performance of your view does not respect the annotation promise.
+
+![alt tag](http://i.imgur.com/S5unAoJ.png)
+
+Let's update the annotation:
+```ruby
+  Performance :makes => 1.query + Article.N.queries
+  def index
+    @articles = Article.all
+    @total_comments = 0
+    @articles.each do |article|
+      @total_comments += article.comments.length
+    end
+    puts @total_comments
+  end
+```
+Now that you have annotated the action correctly, visiting `/articles` renders successfully.
+
+The experienced code-reviewer however might ask the author to get rid of the `N + 1` query here, and use `.includes` instead:
+```ruby
+  Performance :makes => 2.queries
+  def index
+    @articles = Article.all.includes(:comments)
+    @total_comments = 0
+    @articles.each do |article|
+      @total_comments += article.comments.length
+    end
+    puts @total_comments
+  end
+```
+And now, we've successfully caught and averted a bad code commit!
+
+## Advanced configuration
+`performance_promise` opens up more functionality through configuration variables:
+
+#### `allowed_environments: array`
+By default, `performance_promise` runs only in `development` and `testing`. This ensures that you can identify issues when developing or running your test-suite. Be very careful about enabling this in `production` – you almost certainly don't want to.
+
+#### `throw_exception: bool`
+Tells `performance_promise` whether to throw an exception. Set to `true` by default, but can be overriden if you simply want to ignore failing cases (they will still be written to the log).
+
+#### `speedy_promise: hash`
+If you do not care to determine the _exact_ performance of your action, you can still simply mark it as `Speedy`:
+```ruby
+  Speedy()
+  def index
+    ...
+  end
+```
+A `Speedy` action is supposed to be well behaved, making lesser than `x` database queries, and taking less than `y` to complete. You can set these defaults using this configuration parameter.
+
+#### `untagged_methods_are_speedy: bool`
+By default, actions that are not annotated aren't validated by `performance_promise`. If you'd like to force all actions to be validated, one option is to simply default them all to be `Speedy`. This allows developers to make _no_ change to their code, while still reaping the benefits of performance validation. Iff a view fails to be `Speedy`, then the developer is forced to acknowledge it in code.
+
+
+## FAQ
+> **What is the strange syntax? Is it a function call? Is it a method?**
+
+We borrow the coding style from Python's `decorators`. This style allows for a function to be wrapped by another. This is a great use case for that style since it allows for us to express the annotation right above the function definition.
+
+Credit goes to [Yehuda Katz][yehuda-katz] for the [port of decortators][ruby-decorators] into Ruby.
+
+> **Will this affect my production service?**
+
+By default, `performace_promise` is applied only in `development` and `test` environments. You can choose to override this, but is strongly discouraged.
+
+
+> **What are some other kinds of performance guarantees that I can make with `performance_promise`?**
+
+In addition to promises about the number of database queries, you can also make promises on how long the entire view will take to render, and whether it performs any table scans.
+```ruby
+  Performance :makes => 1.query + Article.N.queries,
+              :takes => 1.second,
+              :full_tables_scans => [Article]
+  def index
+    ...
+  end
+```
+
+If you come up with other validations that you think will be useful, please consider sharing it with the community by [writing your own plugin here](https://github.com/bipsandbytes/performance_promise/tree/master/lib/performance_promise/validations), and raising a Pull Request.
+
+> **Is this the same as [Bullet][bullet] gem?**
+
+[Bullet][bullet] is a great piece of software that allows developers to help identify N + 1 queries and unused eager loading. It does this by watching your application in development mode, and alerting you when it does either of those things.
+
+`performance_promise` can be tuned to not only identify N + 1 queries, but can also alert whenever there's _any_ change in performance.  It allows you to identify expensive actions irrespective of their database query profile.
+
+`performance_promise` also has access to the entire database query object. In the future, `performance_promise` can be tuned to perform additonal checks like how long the most expensive query took, whether the action performed any table scans (available through an `EXPLAIN`) etc.
+
+Finally, the difference between `bullet` and `performance_promise` is akin to testing by refreshing your browser and testing by writing specs. `performance_promise` encourages you to specify your action's performance by declaring it in code itself. This allows both  code-reviewers as well as automated tests to verify your code's performance.
+
+[rails-getting-started]: <http://guides.rubyonrails.org/getting_started.html>
+[bullet]: <https://github.com/flyerhzm/bullet>
+[yehuda-katz]: <http://yehudakatz.com/>
+[ruby-decorators]: <http://yehudakatz.com/2009/07/11/python-decorators-in-ruby/>

data/lib/performance_promise/decorators.rb

@@ -0,0 +1,86 @@
+# An implementation of pythonish decorators in Ruby
+# Credits: Yehuda Katz (http://yehudakatz.com/)
+# https://github.com/wycats/ruby_decorators
+
+
+module MethodDecorators
+  def self.extended(klass)
+    class << klass
+      attr_accessor :decorated_methods
+    end
+  end
+
+  def method_missing(name, *args, &blk)
+    if Object.const_defined?(name)
+      const = Object.const_get(name)
+    elsif Decorator.decorators.key?(name)
+      const = Decorator.decorators[name]
+    else
+      return super
+    end
+
+    instance_eval <<-ruby_eval, __FILE__, __LINE__ + 1
+      def #{name}(*args, &blk)
+        decorate(#{const.name}, *args, &blk)
+      end
+    ruby_eval
+
+    send(name, *args, &blk)
+  end
+
+  def method_added(name)
+    return unless @decorators
+
+    decorators = @decorators.dup
+    @decorators = nil
+    @decorated_methods ||= Hash.new {|h,k| h[k] = []}
+
+    class << self; attr_accessor :decorated_methods; end
+
+    decorators.each do |klass, args|
+      decorator = klass.respond_to?(:new) ? klass.new(self, instance_method(name), *args) : klass
+      @decorated_methods[name] << decorator
+    end
+
+    class_eval <<-ruby_eval, __FILE__, __LINE__ + 1
+      def #{name}(*args, &blk)
+        ret = nil
+        self.class.decorated_methods[#{name.inspect}].each do |decorator|
+          ret = decorator.call(self, *args, &blk)
+        end
+        ret
+      end
+    ruby_eval
+  end
+
+  def decorate(klass, *args)
+    @decorators ||= []
+    @decorators << [klass, args]
+  end
+end
+
+class Decorator
+  class << self
+    attr_accessor :decorators
+    def decorator_name(name)
+      Decorator.decorators ||= {}
+      Decorator.decorators[name] = self
+    end
+  end
+
+  def self.inherited(klass)
+    name = klass.name.gsub(/^./) {|m| m.downcase}
+
+    return if name =~ /^[^A-Za-z_]/ || name =~ /[^0-9A-Za-z_]/
+
+    MethodDecorators.module_eval <<-ruby_eval, __FILE__, __LINE__ + 1
+      def #{klass}(*args, &blk)
+        decorate(#{klass}, *args, &blk)
+      end
+    ruby_eval
+  end
+
+  def initialize(klass, method)
+    @method = method
+  end
+end

data/lib/performance_promise/lazily_evaluated.rb

@@ -0,0 +1,78 @@
+require 'performance_promise.rb'
+
+
+class LazilyEvaluated
+  def initialize(c)
+    if c.is_a?(Fixnum)
+      @operand1 = c
+      @operator = 'constant'
+    elsif c.is_a?(Class)
+      @operand1 = c
+      @operator = 'model'
+    elsif c.is_a?(Array)
+      @operand1, @operand2, @operator = c
+    else
+      raise
+    end
+  end
+
+  def +(other)
+    return LazilyEvaluated.new([self, other, '+'])
+  end
+
+  def -(other)
+    return LazilyEvaluated.new([self, other, '-'])
+  end
+
+  def *(other)
+    return LazilyEvaluated.new([self, other, '*'])
+  end
+
+  def /(other)
+    return LazilyEvaluated.new([self, other, '/'])
+  end
+
+  def evaluate
+    # don't do anything in prod-like environments
+    return 0 unless PerformancePromise.configuration.allowed_environments.include?(Rails.env)
+
+    case @operator
+    when 'constant'
+      return @operand1
+    when 'model'
+      return @operand1.count
+    when '+'
+      return @operand1.evaluate + @operand2.evaluate
+    when '-'
+      return @operand1.evaluate - @operand2.evaluate
+    when '*'
+      return @operand1.evaluate * @operand2.evaluate
+    when '/'
+      return @operand1.evaluate / @operand2.evaluate
+    else
+      raise
+    end
+  end
+
+  def queries
+    # syntactic sugar
+    self
+  end
+end
+
+
+class Fixnum
+  def queries
+    LazilyEvaluated.new(self)
+  end
+  alias query queries
+end
+
+
+module ActiveRecord
+  class Base
+    def self.N
+      LazilyEvaluated.new(self)
+    end
+  end
+end

data/lib/performance_promise/performance.rb

@@ -0,0 +1,13 @@
+require 'performance_promise.rb'
+
+
+class Performance < Decorator
+  def initialize(klass, method, options)
+    @klass, @method = klass, method
+    PerformancePromise.promises["#{klass}\##{method.name.to_s}"] = options
+  end
+
+  def call(this, *args)
+    @method.bind(this).call(*args)
+  end
+end

data/lib/performance_promise/performance_validations.rb

@@ -0,0 +1,16 @@
+require 'performance_promise/validations/number_of_db_queries.rb'
+require 'performance_promise/validations/time_taken_for_render.rb'
+require 'performance_promise/validations/full_table_scans.rb'
+
+
+module PerformanceValidations
+  extend ValidateNumberOfQueries
+  extend ValidateTimeTakenForRender
+  extend ValidateFullTableScans
+
+  def self.report_promise_passed(method, db_queries, options)
+    PerformancePromise.configuration.logger.warn '-' * 80
+    PerformancePromise.configuration.logger.warn Utils.colored(:green, "Passed promise on #{method}")
+    PerformancePromise.configuration.logger.warn '-' * 80
+  end
+end

data/lib/performance_promise/speedy.rb

@@ -0,0 +1,8 @@
+require 'performance_promise.rb'
+
+
+class Speedy < Performance
+  def initialize(klass, method)
+    super(klass, method, PerformancePromise.configuration.speedy_promise)
+  end
+end

data/lib/performance_promise/sql_recorder.rb

@@ -0,0 +1,41 @@
+require 'singleton'
+
+
+class SQLRecorder
+  include Singleton
+
+  @db_queries = []
+  def flush
+    captured_queries = @db_queries
+    @db_queries = []
+    return captured_queries
+  end
+
+  def record(payload, duration)
+    return if invalid_payload?(payload)
+    sql = payload[:sql]
+    cleaned_trace = clean_trace(caller)
+    explained = ActiveRecord::Base.connection.execute("EXPLAIN QUERY PLAN #{sql}", 'SQLR-EXPLAIN')
+    @db_queries << {
+      :sql => sql,
+      :duration => duration,
+      :trace => cleaned_trace,
+      :explained => explained,
+    }
+  end
+
+  def invalid_payload?(payload)
+    ignore_query_names = [
+      'SCHEMA',
+      'SQLR-EXPLAIN',
+    ]
+    payload[:name] && ignore_query_names.any? { |name| payload[:name].in?(name) }
+  end
+
+  def clean_trace(trace)
+    Rails.backtrace_cleaner.remove_silencers!
+    Rails.backtrace_cleaner.add_silencer { |line| not line =~ /^(app)\// }
+    Rails.backtrace_cleaner.clean(trace)
+  end
+end
+SQLRecorder.instance.flush

data/lib/performance_promise/utils.rb

@@ -0,0 +1,42 @@
+module Utils
+  def self.summarize_queries(db_queries)
+    summary = Hash.new(0)
+    db_queries.each do |query|
+      summary[query.except(:duration)] += 1
+    end
+    summary
+  end
+
+  def self.guess_order(db_queries)
+    order = []
+    queries_with_count = summarize_queries(db_queries)
+    queries_with_count.each do |query, count|
+      if count == 1
+        order << "1.query"
+      else
+        if (lookup_field = /WHERE .*"(.*?_id)" = \?/.match(query[:sql]))
+          klass = lookup_field[1].humanize
+          order << "#{klass}.N.queries"
+        else
+          order << "n(???)"
+        end
+      end
+    end
+
+    order.join(" + ")
+  end
+
+  def self.colored(color, string)
+    color =
+      case color
+      when :red
+        "\e[31m"
+      when :green
+        "\e[32m"
+      when :cyan
+        "\e[36m"
+      end
+    end_color = "\e[0m"
+    "#{color}#{string}#{end_color}"
+  end
+end

data/lib/performance_promise/validations/README.md

@@ -0,0 +1,56 @@
+# Creating your own validations
+
+You can easily extend `performance_promise` by writing your own validations. You do it in 3 steps:
+
+1. Write your validation
+2. Register your validation
+3. Enable your validation in configuration
+
+## Write your validation
+Create a new file in this directory, with a single function:
+
+```ruby
+module MODULE_NAME
+  def validate_NAME(db_queries, render_time, promised)
+    ...
+  end
+end
+```
+
+* `MODULE_NAME`: A name for the module.
+* `NAME`: The symbol that will be used in the `Performance` promise. For example, if the `NAME` is `makes`, then the function function name will be `validates_makes`, and the `Promise` will take an option `:makes`.
+* `validates_NAME`: A function that is called if the a function makes a promise with that `NAME`.
+
+The function takes 3 parameters:
+  * `db_queries`: An `array` of database queries which can be inspected.
+  * `render_time`: Time it took to render the view.
+  * `promised`: The performance guarantee made by the author.
+
+And returns 3 parameters:
+  * `passes`: Whether the promised made by the author in `promised` is upheld.
+  * `error_message`: An error message to show to the user explaining why the promise failed, and a best guess of how to fix it, if possible.
+  * `backtrace`: If possible, an `array` showing the codepath that caused the promise to be broken.
+
+See [time_taken_for_render](https://github.com/bipsandbytes/performance_promise/blob/master/lib/performance_promise/validations/time_taken_for_render.rb) for a simple example.
+
+## Register your validation
+You are now ready to register this plugin. Simply add this plugin to the list of validations in [performace_validations](https://github.com/bipsandbytes/performance_promise/blob/master/lib/performance_promise/performance_validations.rb):
+```ruby
+module PerformanceValidations
+  ...
+  extend MODULE_NAME
+  ...
+end
+```
+
+## Enable your validation in configuration
+You are now ready to include this validation in your configuration file:
+```ruby
+PerformancePromise.configure do |config|
+  config.enable = true
+  config.validations = [
+    ...
+    :NAME,
+  ]
+end
+```

data/lib/performance_promise/validations/full_table_scans.rb

@@ -0,0 +1,33 @@
+module ValidateFullTableScans
+  def validate_full_table_scans(db_queries, render_time, promised)
+    full_table_scans = []
+
+    # check the explained queries to see if there were any
+    # SCAN TABLEs
+    db_queries.each do |db_query|
+      detail = db_query[:explained][0]['detail']
+      makes_full_table_scan = detail.match(/SCAN TABLE (.*)/)
+      if makes_full_table_scan
+        table_name = makes_full_table_scan[1]
+        full_table_scans << table_name
+      end
+    end
+
+    # we do not care about duplicates
+    full_table_scans = full_table_scans.uniq
+
+    # map the models in the promise to their corresponding table names
+    promised_full_table_scans = promised.map { |model| model.table_name }
+
+    # check that the performed FTSs are a subset of the promised FTSs
+    passes = (full_table_scans & promised_full_table_scans == full_table_scans)
+    error_message = ''
+    backtrace = []
+
+    unless passes
+        error_message = "Promised table scans on #{promised_full_table_scans}, made: #{full_table_scans}"
+    end
+
+    return passes, error_message, backtrace
+  end
+end