Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

274 lines (204 sloc) 9.923 kB

Bullet

The Bullet plugin 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) or when you’re using eager loading that isn’t necessary.

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.


Thanks

flipsasser added Growl, console.log and Rails.log support, very awesome. And he improved README.
rainux add group style console.log.


Install

You can add Bullet to your Rails gem requirements:

config.gem 'flyerhzm-bullet', :lib => 'bullet', :source => 'http://gems.github.com'

You can install it as a gem:

sudo gem install flyerhzm-bullet --source http://gems.github.com

Or you can install it as a rails plugin:

script/plugin install git://github.com/flyerhzm/bullet.git


Configuration

Bullet won’t do ANYTHING unless you tell it to explicitly. Append to config/environments/development.rb initializer with the following code:


config.after_initialize do
  Bullet.enable = true 
  Bullet::Association.alert = true
  Bullet::Association.bullet_logger = true  
  Bullet::Association.console = true
  Bullet::Association.growl = true
  Bullet::Association.rails_logger = true
end

It is recommended to config growl notification as follows if your collaborators are not using MacOS


  begin
    require 'ruby-growl'
    Bullet::Association.growl = true
  rescue MissingSourceFile
  end

The code above will enable all five of the Bullet notification systems:

  • Bullet.enable: enable Bullet plugin, otherwise do nothing
  • Bullet::Association.alert: pop up a JavaScript alert in the browser
  • Bullet::Association.bullet_logger: log to the Bullet log file (RAILS_ROOT/log/bullet.log)
  • Bullet::Association.rails_logger: add warnings directly to the Rails log
  • Bullet::Association.console: log warnings to your browser’s console.log (Safari/Webkit browsers or Firefox w/Firebug installed)
  • Bullet::Association.growl: pop up Growl warnings if your system has Growl installed. Requires a little bit of configuration

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.

  • Unsed 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.


Growl Support

To get Growl support up-and-running for Bullet, follow the steps below:

  • Install the ruby-growl gem: sudo gem install ruby-growl
  • Open the Growl preference pane in Systems Preferences
  • Click the “Network” tab
  • Make sure both “Listen for incoming notifications” and “Allow remote application registration” are checked. Note: If you set a password, you will need to set Bullet::Association.growl_password = 'your_growl_password’ in the config file.
  • Restart Growl (“General” tab → Stop Growl → Start Growl)
  • Boot up your application. Bullet will automatically send a Growl notification when Growl is turned on. If you do not see it when your application loads, make sure it is enabled in your initializer and double-check the steps above.

Step by step example

Bullet is designed to function as you browse through your application in development. It will alert you whenever it encounters N+1 queries or unused eager loading.

Important: It is strongly recommended you disable your browser’s cache.

1. setup test environment


$ rails test
$ cd test
$ script/generate scaffold post name:string 
$ script/generate scaffold comment name:string post_id:integer
$ rake db:migrate

2. change app/model/post.rb and app/model/comment.rb


class Post < ActiveRecord::Base
  has_many :comments
end

class Comment < ActiveRecord::Base
  belongs_to :post
end

3. go to script/console and execute


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><%=h post.name %></td>
    <td><%= post.comments.collect(&: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 bullet plugin


$ script/plugin install git://github.com/flyerhzm/bullet.git

6. enable the bullet plugin in development, add a line to config/environments/development.rb


config.after_initialize do
  Bullet.enable = true 
  Bullet::Association.alert = true
  Bullet::Association.bullet_logger = true  
end

7. start server


$ script/server

8. input http://localhost:3000/posts in browser, then you will see a popup alert box 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 post object to comments associations.

In the meanwhile, there’s a log appended into log/bullet.log file


2009-08-20 09:12:19[INFO] N+1 Query: PATH_INFO: /posts;    model: Post => assocations: [comments]
Add your finder: :include => [:comments]
2009-08-20 09:12:19[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 generated SQLs are


  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. fix the N+1 query, change app/controllers/posts_controller.rb file


  def index
    @posts = Post.find(:all, :include => :comments)

    respond_to do |format|
      format.html # index.html.erb
      format.xml  { render :xml => @posts }
    end 
  end 

10. refresh http://localhost:3000/posts page, no alert box and no log appended.

The generated SQLs are


  Post Load (0.5ms)   SELECT * FROM "posts" 
  Comment Load (0.5ms)   SELECT "comments".* FROM "comments" WHERE ("comments".post_id IN (1,2)) 

a N+1 query fixed. Cool!

11. now simulate unused eager loading. Change app/controllers/posts_controller.rb and app/views/posts/index.html.erb


  def index
    @posts = Post.find(:all, :include => :comments)

    respond_to do |format|
      format.html # index.html.erb
      format.xml  { render :xml => @posts }
    end 
  end 

<% @posts.each do |post| %>
  <tr>
    <td><%=h 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 page, then you will see a popup alert box says


The request has unused preload associations as follows:
model: Post => associations: [comment]
The request has N+1 queries as follows:
None

In the meanwhile, there’s a log appended into log/bullet.log file


2009-08-25 21:13:22[INFO] Unused preload associations: PATH_INFO: /posts;    model: Post => associations: [comments]·
Remove from your finder: :include => [:comments]

Copyright © 2009 Richard Huang (flyerhzm@gmail.com), released under the MIT license

Jump to Line
Something went wrong with that request. Please try again.