bullet 4.0.0 → 4.13.1

data/README.md

@@ -0,0 +1,432 @@
+# Bullet
+
+[![Gem Version](https://badge.fury.io/rb/bullet.png)](http://badge.fury.io/rb/bullet)
+[![Build Status](https://secure.travis-ci.org/flyerhzm/bullet.png)](http://travis-ci.org/flyerhzm/bullet)
+[![Coverage Status](https://coveralls.io/repos/flyerhzm/bullet/badge.png?branch=master)](https://coveralls.io/r/flyerhzm/bullet)
+<a href="https://codeclimate.com/github/flyerhzm/bullet"><img src="https://codeclimate.com/github/flyerhzm/bullet.png" /></a>
+[![Coderwall Endorse](http://api.coderwall.com/flyerhzm/endorsecount.png)](http://coderwall.com/flyerhzm)
+
+The Bullet gem is designed to help you increase your application's performance by reducing the number of queries it makes. It will watch your queries while you develop your application and notify you when you should add eager loading (N+1 queries), when you're using eager loading that isn't necessary and when you should use counter cache.
+
+Best practice is to use Bullet in development mode or custom mode (staging, profile, etc.). The last thing you want is your clients getting alerts about how lazy you are.
+
+Bullet gem now supports **activerecord** >= 3.0 and **mongoid** >= 2.4.1.
+
+If you use activerecord 2.x, please use bullet <= 4.5.0
+
+## External Introduction
+
+* [http://railscasts.com/episodes/372-bullet](http://railscasts.com/episodes/372-bullet)
+* [http://ruby5.envylabs.com/episodes/9-episode-8-september-8-2009](http://ruby5.envylabs.com/episodes/9-episode-8-september-8-2009)
+* [http://railslab.newrelic.com/2009/10/23/episode-19-on-the-edge-part-1](http://railslab.newrelic.com/2009/10/23/episode-19-on-the-edge-part-1)
+* [http://weblog.rubyonrails.org/2009/10/22/community-highlights](http://weblog.rubyonrails.org/2009/10/22/community-highlights)
+
+## Install
+
+You can install it as a gem:
+
+```
+gem install bullet
+```
+
+or add it into a Gemfile (Bundler):
+
+
+```ruby
+gem "bullet", :group => "development"
+```
+
+## Configuration
+
+Bullet won't do ANYTHING unless you tell it to explicitly. Append to
+`config/environments/development.rb` initializer with the following code:
+
+```ruby
+config.after_initialize do
+  Bullet.enable = true
+  Bullet.alert = true
+  Bullet.bullet_logger = true
+  Bullet.console = true
+  Bullet.growl = true
+  Bullet.xmpp = { :account  => 'bullets_account@jabber.org',
+                  :password => 'bullets_password_for_jabber',
+                  :receiver => 'your_account@jabber.org',
+                  :show_online_status => true }
+  Bullet.rails_logger = true
+  Bullet.bugsnag = true
+  Bullet.airbrake = true
+  Bullet.add_footer = true
+  Bullet.stacktrace_includes = [ 'your_gem', 'your_middleware' ]
+end
+```
+
+The notifier of Bullet is a wrap of [uniform_notifier](https://github.com/flyerhzm/uniform_notifier)
+
+The code above will enable all seven of the Bullet notification systems:
+* `Bullet.enable`: enable Bullet gem, otherwise do nothing
+* `Bullet.alert`: pop up a JavaScript alert in the browser
+* `Bullet.bullet_logger`: log to the Bullet log file (Rails.root/log/bullet.log)
+* `Bullet.rails_logger`: add warnings directly to the Rails log
+* `Bullet.airbrake`: add notifications to airbrake
+* `Bullet.console`: log warnings to your browser's console.log (Safari/Webkit browsers or Firefox w/Firebug installed)
+* `Bullet.growl`: pop up Growl warnings if your system has Growl installed. Requires a little bit of configuration
+* `Bullet.xmpp`: send XMPP/Jabber notifications to the receiver indicated. Note that the code will currently not handle the adding of contacts, so you will need to make both accounts indicated know each other manually before you will receive any notifications. If you restart the development server frequently, the 'coming online' sound for the Bullet account may start to annoy - in this case set :show_online_status to false; you will still get notifications, but the Bullet account won't announce it's online status anymore.
+* `Bullet.raise`: raise errors, useful for making your specs fail unless they have optimized queries
+* `Bullet.add_footer`: adds the details in the bottom left corner of the page
+* `Bullet.stacktrace_includes`: include paths with any of these substrings in the stack trace, even if they are not in your main app
+
+Bullet also allows you to disable any of its detectors.
+
+```ruby
+# Each of these settings defaults to true
+
+# Detect N+1 queries
+Bullet.n_plus_one_query_enable     = false
+
+# Detect eager-loaded associations which are not used
+Bullet.unused_eager_loading_enable = false
+
+# Detect unnecessary COUNT queries which could be avoided
+# with a counter_cache
+Bullet.counter_cache_enable        = false
+```
+
+## Whitelist
+
+Sometimes Bullet may notify you of query problems you don't care to fix, or
+which come from outside your code. You can whitelist these to ignore them:
+
+```ruby
+Bullet.add_whitelist :type => :n_plus_one_query, :class_name => "Post", :association => :comments
+Bullet.add_whitelist :type => :unused_eager_loading, :class_name => "Post", :association => :comments
+Bullet.add_whitelist :type => :counter_cache, :class_name => "Country", :association => :cities
+```
+
+## Log
+
+The Bullet log `log/bullet.log` will look something like this:
+
+* N+1 Query:
+
+```
+2009-08-25 20:40:17[INFO] N+1 Query: PATH_INFO: /posts;    model: Post => associations: [comments]·
+Add to your finder: :include => [:comments]
+2009-08-25 20:40:17[INFO] N+1 Query: method call stack:·
+/Users/richard/Downloads/test/app/views/posts/index.html.erb:11:in `_run_erb_app47views47posts47index46html46erb'
+/Users/richard/Downloads/test/app/views/posts/index.html.erb:8:in `each'
+/Users/richard/Downloads/test/app/views/posts/index.html.erb:8:in `_run_erb_app47views47posts47index46html46erb'
+/Users/richard/Downloads/test/app/controllers/posts_controller.rb:7:in `index'
+```
+
+The first two lines are notifications that N+1 queries have been encountered. The remaining lines are stack traces so you can find exactly where the queries were invoked in your code, and fix them.
+
+* Unused eager loading:
+
+```
+2009-08-25 20:53:56[INFO] Unused eager loadings: PATH_INFO: /posts;    model: Post => associations: [comments]·
+Remove from your finder: :include => [:comments]
+```
+
+These two lines are notifications that unused eager loadings have been encountered.
+
+* Need counter cache:
+
+```
+2009-09-11 09:46:50[INFO] Need Counter Cache
+  Post => [:comments]
+```
+
+## Growl, XMPP/Jabber and Airbrake Support
+
+see [https://github.com/flyerhzm/uniform_notifier](https://github.com/flyerhzm/uniform_notifier)
+
+## Important
+
+If you find Bullet does not work for you, *please disable your browser's cache*.
+
+## Advanced
+
+### Profile a job
+
+The Bullet gem uses rack middleware to profile requests. If you want to use Bullet without an http server, like to profile a job, you can use use profile method and fetch warnings
+
+```ruby
+Bullet.profile do
+  # do anything
+end
+warnings = Bullet.warnings
+```
+
+### Work with sinatra
+
+Configure and use `Bullet::Rack`
+
+```ruby
+configure :development do
+  Bullet.enable = true
+  Bullet.bullet_logger = true
+  use Bullet::Rack
+end
+```
+
+### Run in tests
+
+First you need to enable Bullet in test environment.
+
+```ruby
+# config/environments/test.rb
+config.after_initialize do
+  Bullet.enable = true
+  Bullet.bullet_logger = true
+  Bullet.raise = true # raise an error if n+1 query occurs
+end
+```
+
+Then wrap each test in Bullet api.
+
+```ruby
+# spec/spec_helper.rb
+if Bullet.enable?
+  config.before(:each) do
+    Bullet.start_request
+  end
+
+  config.after(:each) do
+    Bullet.perform_out_of_channel_notifications if Bullet.notification?
+    Bullet.end_request
+  end
+end
+```
+
+## Debug Mode
+
+Bullet outputs some details info, to enable debug mode, set
+`BULLET_DEBUG=true` env.
+
+## Contributors
+
+[https://github.com/flyerhzm/bullet/contributors](https://github.com/flyerhzm/bullet/contributors)
+
+## Demo
+
+Bullet is designed to function as you browse through your application in development. To see it in action, follow these steps to create, detect, and fix example query problems.
+
+1\. Create an example application
+
+```
+$ rails new test_bullet
+$ cd test_bullet
+$ rails g scaffold post name:string
+$ rails g scaffold comment name:string post_id:integer
+$ bundle exec rake db:migrate
+```
+
+2\. Change `app/model/post.rb` and `app/model/comment.rb`
+
+```ruby
+class Post < ActiveRecord::Base
+  has_many :comments
+end
+
+class Comment < ActiveRecord::Base
+  belongs_to :post
+end
+```
+
+3\. Go to `rails c` and execute
+
+```ruby
+post1 = Post.create(:name => 'first')
+post2 = Post.create(:name => 'second')
+post1.comments.create(:name => 'first')
+post1.comments.create(:name => 'second')
+post2.comments.create(:name => 'third')
+post2.comments.create(:name => 'fourth')
+```
+
+4\. Change the `app/views/posts/index.html.erb` to produce a N+1 query
+
+```
+<% @posts.each do |post| %>
+  <tr>
+    <td><%= post.name %></td>
+    <td><%= post.comments.map(&:name) %></td>
+    <td><%= link_to 'Show', post %></td>
+    <td><%= link_to 'Edit', edit_post_path(post) %></td>
+    <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', :method => :delete %></td>
+  </tr>
+<% end %>
+```
+
+5\. Add the `bullet` gem to the `Gemfile`
+
+```ruby
+gem "bullet"
+```
+
+And run
+
+```
+bundle install
+```
+
+6\. enable the Bullet gem in development, add a line to
+`config/environments/development.rb`
+
+```ruby
+config.after_initialize do
+  Bullet.enable = true
+  Bullet.alert = true
+  Bullet.bullet_logger = true
+  Bullet.console = true
+#  Bullet.growl = true
+  Bullet.rails_logger = true
+  Bullet.add_footer = true
+end
+```
+
+7\. Start the server
+
+```
+$ rails s
+```
+
+8\. Visit `http://localhost:3000/posts` in browser, and you will see a popup alert box that says
+
+```
+The request has unused preload associations as follows:
+None
+The request has N+1 queries as follows:
+model: Post => associations: [comment]
+```
+
+which means there is a N+1 query from the Post object to its Comment association.
+
+In the meanwhile, there's a log appended into `log/bullet.log` file
+
+```
+2010-03-07 14:12:18[INFO] N+1 Query in /posts
+  Post => [:comments]
+  Add to your finder: :include => [:comments]
+2010-03-07 14:12:18[INFO] N+1 Query method call stack
+  /home/flyerhzm/Downloads/test_bullet/app/views/posts/index.html.erb:14:in `_render_template__600522146_80203160_0'
+  /home/flyerhzm/Downloads/test_bullet/app/views/posts/index.html.erb:11:in `each'
+  /home/flyerhzm/Downloads/test_bullet/app/views/posts/index.html.erb:11:in `_render_template__600522146_80203160_0'
+  /home/flyerhzm/Downloads/test_bullet/app/controllers/posts_controller.rb:7:in `index'
+```
+
+The generated SQL is:
+
+```
+Post Load (1.0ms)   SELECT * FROM "posts"
+Comment Load (0.4ms)   SELECT * FROM "comments" WHERE ("comments".post_id = 1)
+Comment Load (0.3ms)   SELECT * FROM "comments" WHERE ("comments".post_id = 2)
+```
+
+9\. To fix the N+1 query, change `app/controllers/posts_controller.rb` file
+
+```ruby
+def index
+  @posts = Post.includes(:comments)
+
+  respond_to do |format|
+    format.html # index.html.erb
+    format.xml  { render :xml => @posts }
+  end
+end
+```
+
+10\. Refresh `http://localhost:3000/posts`. Now there's no alert box and nothing new in the log.
+
+The generated SQL is:
+
+```
+Post Load (0.5ms)   SELECT * FROM "posts"
+Comment Load (0.5ms)   SELECT "comments".* FROM "comments" WHERE ("comments".post_id IN (1,2))
+```
+
+N+1 query fixed. Cool!
+
+11\. Now simulate unused eager loading. Change
+`app/controllers/posts_controller.rb` and
+`app/views/posts/index.html.erb`
+
+```ruby
+def index
+  @posts = Post.includes(:comments)
+
+  respond_to do |format|
+    format.html # index.html.erb
+    format.xml  { render :xml => @posts }
+  end
+end
+```
+
+```
+<% @posts.each do |post| %>
+  <tr>
+    <td><%= post.name %></td>
+    <td><%= link_to 'Show', post %></td>
+    <td><%= link_to 'Edit', edit_post_path(post) %></td>
+    <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', :method => :delete %></td>
+  </tr>
+<% end %>
+```
+
+12\. Refresh `http://localhost:3000/posts`, and you will see a popup alert box that says
+
+```
+The request has unused preload associations as follows:
+model: Post => associations: [comment]
+The request has N+1 queries as follows:
+None
+```
+
+Meanwhile, there's a line appended to `log/bullet.log`
+
+```
+2009-08-25 21:13:22[INFO] Unused preload associations: PATH_INFO: /posts;    model: Post => associations: [comments]·
+Remove from your finder: :include => [:comments]
+```
+
+13\. Simulate counter_cache. Change `app/controllers/posts_controller.rb`
+and `app/views/posts/index.html.erb`
+
+```ruby
+def index
+  @posts = Post.all
+
+  respond_to do |format|
+    format.html # index.html.erb
+    format.xml  { render :xml => @posts }
+  end
+end
+```
+
+```
+<% @posts.each do |post| %>
+  <tr>
+    <td><%= post.name %></td>
+    <td><%= post.comments.size %></td>
+    <td><%= link_to 'Show', post %></td>
+    <td><%= link_to 'Edit', edit_post_path(post) %></td>
+    <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', :method => :delete %></td>
+  </tr>
+<% end %>
+```
+
+14\. Refresh `http://localhost:3000/posts`, then you will see a popup alert box that says
+
+```
+Need counter cache
+  Post => [:comments]
+```
+
+Meanwhile, there's a line appended to `log/bullet.log`
+
+```
+2009-09-11 10:07:10[INFO] Need Counter Cache
+  Post => [:comments]
+```
+
+Copyright (c) 2009 - 2014 Richard Huang (flyerhzm@gmail.com), released under the MIT license

data/Rakefile

@@ -3,7 +3,6 @@ require "bundler"
 Bundler.setup
 
 require "rake"
-require "rdoc/task"
 require "rspec"
 require "rspec/core/rake_task"
 
@@ -35,11 +34,19 @@ RSpec::Core::RakeTask.new('spec:progress') do |spec|
   spec.pattern = "spec/**/*_spec.rb"
 end
 
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = "rdoc"
-  rdoc.title = "bullet #{Bullet::VERSION}"
-  rdoc.rdoc_files.include("README*")
-  rdoc.rdoc_files.include("lib/**/*.rb")
+
+begin
+  require 'rdoc/task'
+
+  desc "Generate documentation for the plugin."
+  Rake::RDocTask.new do |rdoc|
+    rdoc.rdoc_dir = "rdoc"
+    rdoc.title = "bullet #{Bullet::VERSION}"
+    rdoc.rdoc_files.include("README*")
+    rdoc.rdoc_files.include("lib/**/*.rb")
+  end
+rescue LoadError
+  puts 'RDocTask is not supported for this platform'
 end
 
 task :default => :spec

data/bullet.gemspec

@@ -10,12 +10,15 @@ Gem::Specification.new do |s|
   s.authors     = ["Richard Huang"]
   s.email       = ["flyerhzm@gmail.com"]
   s.homepage    = "http://github.com/flyerhzm/bullet"
-  s.summary     = "A rails plugin to kill N+1 queries and unused eager loading."
-  s.description = "A rails plugin to kill N+1 queries and unused eager loading."
+  s.summary     = "help to kill N+1 queries and unused eager loading."
+  s.description = "help to kill N+1 queries and unused eager loading."
+
+  s.license     = 'MIT'
 
   s.required_rubygems_version = ">= 1.3.6"
 
-  s.add_dependency "uniform_notifier", "~> 1.0.0"
+  s.add_runtime_dependency "activesupport", ">= 3.0.0"
+  s.add_runtime_dependency "uniform_notifier", ">= 1.6.0"
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/lib/bullet/active_record3.rb

@@ -9,11 +9,11 @@ module Bullet
         def to_a
           records = origin_to_a
           if records.size > 1
-            Bullet::Detector::Association.add_possible_objects(records)
-            Bullet::Detector::Counter.add_possible_objects(records)
+            Bullet::Detector::NPlusOneQuery.add_possible_objects(records)
+            Bullet::Detector::CounterCache.add_possible_objects(records)
           elsif records.size == 1
-            Bullet::Detector::Association.add_impossible_object(records.first)
-            Bullet::Detector::Counter.add_impossible_object(records.first)
+            Bullet::Detector::NPlusOneQuery.add_impossible_object(records.first)
+            Bullet::Detector::CounterCache.add_impossible_object(records.first)
           end
           records
         end
@@ -29,7 +29,7 @@ module Bullet
           records.each do |record|
             Bullet::Detector::Association.add_object_associations(record, associations)
           end
-          Bullet::Detector::Association.add_eager_loadings(records, associations)
+          Bullet::Detector::UnusedEagerLoading.add_eager_loadings(records, associations)
           origin_preload_associations(records, associations, preload_options={})
         end
       end
@@ -42,21 +42,39 @@ module Bullet
           associations = (@eager_load_values + @includes_values).uniq
           records.each do |record|
             Bullet::Detector::Association.add_object_associations(record, associations)
-            Bullet::Detector::NPlusOneQuery.call_association(record, associations)
           end
-          Bullet::Detector::Association.add_eager_loadings(records, associations)
+          Bullet::Detector::UnusedEagerLoading.add_eager_loadings(records, associations)
           records
         end
       end
 
       ::ActiveRecord::Associations::ClassMethods::JoinDependency.class_eval do
+        alias_method :origin_instantiate, :instantiate
         alias_method :origin_construct_association, :construct_association
+
+        def instantiate(rows)
+          @bullet_eager_loadings = {}
+          records = origin_instantiate(rows)
+
+          @bullet_eager_loadings.each do |klazz, eager_loadings_hash|
+            objects = eager_loadings_hash.keys
+            Bullet::Detector::UnusedEagerLoading.add_eager_loadings(objects, eager_loadings_hash[objects.first].to_a)
+          end
+          records
+        end
+
         # call join associations
         def construct_association(record, join, row)
+          result = origin_construct_association(record, join, row)
+
           associations = join.reflection.name
           Bullet::Detector::Association.add_object_associations(record, associations)
           Bullet::Detector::NPlusOneQuery.call_association(record, associations)
-          origin_construct_association(record, join, row)
+          @bullet_eager_loadings[record.class] ||= {}
+          @bullet_eager_loadings[record.class][record] ||= Set.new
+          @bullet_eager_loadings[record.class][record] << associations
+
+          result
         end
       end
 
@@ -79,6 +97,18 @@ module Bullet
           Bullet::Detector::NPlusOneQuery.call_association(@owner, @reflection.name)
           origin_last(*args)
         end
+
+        alias_method :origin_empty?, :empty?
+        def empty?
+          Bullet::Detector::NPlusOneQuery.call_association(@owner, @reflection.name)
+          origin_empty?
+        end
+
+        alias_method :origin_include?, :include?
+        def include?(object)
+          Bullet::Detector::NPlusOneQuery.call_association(@owner, @reflection.name)
+          origin_include?(object)
+        end
       end
 
       ::ActiveRecord::Associations::AssociationProxy.class_eval do
@@ -88,9 +118,17 @@ module Bullet
           # avoid stack level too deep
           result = origin_load_target
           Bullet::Detector::NPlusOneQuery.call_association(@owner, @reflection.name) unless caller.any? { |c| c.include?("load_target") }
-          Bullet::Detector::Association.add_possible_objects(result)
+          Bullet::Detector::NPlusOneQuery.add_possible_objects(result)
           result
         end
+
+        alias_method :origin_set_inverse_instance, :set_inverse_instance
+        def set_inverse_instance(record, instance)
+          if record && we_can_set_the_inverse_on_this?(record)
+            Bullet::Detector::NPlusOneQuery.add_inversed_object(record, @reflection.inverse_of.name)
+          end
+          origin_set_inverse_instance(record, instance)
+        end
       end
 
       ::ActiveRecord::Associations::HasManyAssociation.class_eval do
@@ -98,7 +136,7 @@ module Bullet
 
         def has_cached_counter?
           result = origin_has_cached_counter?
-          Bullet::Detector::Counter.add_counter_cache(@owner, @reflection.name) unless result
+          Bullet::Detector::CounterCache.add_counter_cache(@owner, @reflection.name) unless result
           result
         end
       end
@@ -107,7 +145,7 @@ module Bullet
         alias_method :origin_has_cached_counter?, :has_cached_counter?
         def has_cached_counter?
           result = origin_has_cached_counter?
-          Bullet::Detector::Counter.add_counter_cache(@owner, @reflection.name) unless result
+          Bullet::Detector::CounterCache.add_counter_cache(@owner, @reflection.name) unless result
           result
         end
       end