Install

You can install it as a gem:

gem install bullet

or add it into a Gemfile (Bundler):

gem 'bullet', group: 'development'

enable the Bullet gem with generate command

bundle exec rails g bullet:install

The generate command will auto generate the default configuration and may ask to include in the test environment as well. See below for custom configuration.

Note: make sure bullet gem is added after activerecord (rails) and mongoid.

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.sentry = true
  Bullet.alert = true
  Bullet.bullet_logger = true
  Bullet.console = true
  Bullet.growl = true
  Bullet.xmpp = { :account  => '[email protected]',
                  :password => 'sample_password',
                  :receiver => '[email protected]',
                  :show_online_status => true }
  Bullet.rails_logger = true
  Bullet.honeybadger = true
  Bullet.bugsnag = true
  Bullet.appsignal = true
  Bullet.airbrake = true
  Bullet.rollbar = true
  Bullet.add_footer = true
  Bullet.skip_html_injection = false
  Bullet.stacktrace_includes = [ 'your_gem', 'your_middleware' ]
  Bullet.stacktrace_excludes = [ 'their_gem', 'their_middleware', ['my_file.rb', 'my_method'], ['my_file.rb', 16..20] ]
  Bullet.slack = { webhook_url: 'http://some.slack.url', channel: '#default', username: 'notifier' }
end

The notifier of Bullet is a wrap of uniform_notifier

The code above will enable all 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.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.rails_logger: add warnings directly to the Rails log
• Bullet.honeybadger: add notifications to Honeybadger
• Bullet.bugsnag: add notifications to bugsnag
• Bullet.airbrake: add notifications to airbrake
• Bullet.appsignal: add notifications to AppSignal
• Bullet.rollbar: add notifications to rollbar
• Bullet.sentry: add notifications to sentry
• Bullet.add_footer: adds the details in the bottom left corner of the page. Double click the footer or use close button to hide footer.
• Bullet.skip_html_injection: prevents Bullet from injecting code into the returned HTML. This must be false for receiving alerts, showing the footer or console logging.
• Bullet.skip_http_headers: don't add headers to API requests, and remove the javascript that relies on them. Note that this prevents bullet from logging warnings to the browser console or updating the footer.
• Bullet.stacktrace_includes: include paths with any of these substrings in the stack trace, even if they are not in your main app
• Bullet.stacktrace_excludes: ignore paths with any of these substrings in the stack trace, even if they are not in your main app. Each item can be a string (match substring), a regex, or an array where the first item is a path to match, and the second item is a line number, a Range of line numbers, or a (bare) method name, to exclude only particular lines in a file.
• Bullet.slack: add notifications to slack
• Bullet.raise: raise errors, useful for making your specs fail unless they have optimized queries

Bullet also allows you to disable any of its detectors.

# 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:

Bullet.add_whitelist :type => :n_plus_one_query, :class_name => "Blog", :association => :comments
Bullet.add_whitelist :type => :unused_eager_loading, :class_name => "Blog", :association => :comments
Bullet.add_whitelist :type => :counter_cache, :class_name => "Country", :association => :cities

If you want to skip bullet in some specific controller actions, you can do like

class ApplicationController < ActionController::Base
  around_action :skip_bullet, if: -> { defined?(Bullet) }

  def skip_bullet
    previous_value = Bullet.enable?
    Bullet.enable = false
    yield
  ensure
    Bullet.enable = previous_value
  end
end

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: /blogs;    model: Blog => associations: [comments]·
Add to your finder: :include => [:comments]
2009-08-25 20:40:17[INFO] N+1 Query: method call stack:·
../app/views/blogs/index.html.erb:11:in `_run_erb_app47views47blogs47index46html46erb'
../app/views/blogs/index.html.erb:8:in `each'
../app/views/blogs/index.html.erb:8:in `_run_erb_app47views47blogs47index46html46erb'
../app/controllers/blogs_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: /blogs;    model: Blog => 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
  Blog => [:comments]

Growl, XMPP/Jabber and Airbrake Support

see https://github.com/flyerhzm/uniform_notifier

Important

If you find Bullet does not work for you, please disable your browser's cache.

Advanced

Work with ActiveJob

Include Bullet::ActiveJob in your ApplicationJob.

class ApplicationJob < ActiveJob::Base
  include Bullet::ActiveJob if Rails.env.development?
end

Work with other background job solution

Use the Bullet.profile method.

class ApplicationJob < ActiveJob::Base
  around_perform do |_job, block|
    Bullet.profile do
      block.call
    end
  end
end

Work with sinatra

Configure and use Bullet::Rack

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.

# 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.

# spec/rails_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

Demo

Bullet is designed to function as you browse through your application in development. To see it in action, you can visit https://github.com/flyerhzm/bullet_test or follow these steps to create, detect, and fix example query problems.

1. Create an example application

$ rails new sample_bullet
$ cd sample_bullet
$ rails g scaffold Blog name:string
$ rails g scaffold comment name:string blog_id:integer
$ bundle exec rake db:migrate

2. Change app/model/blog.rb and app/model/comment.rb

class Blog < ActiveRecord::Base
  has_many :comments
end

class Comment < ActiveRecord::Base
  belongs_to :blog
end

3. Go to rails c and execute

blog_1 = Blog.create(:name => 'first')
blog_2 = Blog.create(:name => 'second')
blog_1.comments.create(:name => 'first')
blog_2.comments.create(:name => 'second')
blog_1.comments.create(:name => 'third')
blog_2.comments.create(:name => 'fourth')

4. Change the app/views/blogs/index.html.erb to produce a N+1 query

<% @blogs.each do |blog| %>
  <tr>
    <td><%= blog.name %></td>
    <td><%= blog.comments.map(&:name) %></td>
    <td><%= link_to 'Show', blog %></td>
    <td><%= link_to 'Edit', edit_blog_path(blog) %></td>
    <td><%= link_to 'Destroy', blog, :confirm => 'Are you sure?', :method => :delete %></td>
  </tr>
<% end %>

5. Add the bullet gem to the Gemfile

gem "bullet"

And run

bundle install

6. enable the Bullet gem with generate command

bundle exec rails g bullet:install

7. Start the server

$ rails s

8. Visit http://localhost:3000/blogs 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: Blog => associations: [comment]

which means there is a N+1 query from the Blog object to its Comment association.

In the meantime, there's a log appended into log/bullet.log file

2010-03-07 14:12:18[INFO] N+1 Query in /blogs
  Blog => [:comments]
  Add to your finder: :include => [:comments]
2010-03-07 14:12:18[INFO] N+1 Query method call stack
  ../app/views/blogs/index.html.erb:14:in `_render_template__600522146_80203160_0'
  ../app/views/blogs/index.html.erb:11:in `each'
  ../app/views/blogs/index.html.erb:11:in `_render_template__600522146_80203160_0'
  /home/flyerhzm/Downloads/test_bullet/app/controllers/blogs_controller.rb:7:in `index'

The generated SQL is:

Blog Load (1.0ms)   SELECT * FROM "blogs"
Comment Load (0.4ms)   SELECT * FROM "comments" WHERE ("comments".blog_id = 1)
Comment Load (0.3ms)   SELECT * FROM "comments" WHERE ("comments".blog_id = 2)

9. To fix the N+1 query, change app/controllers/blogs_controller.rb file

def index
  @blogs = Blog.includes(:comments)

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

10. Refresh http://localhost:3000/blogs. Now there's no alert box and nothing new in the log.

The generated SQL is:

Blog Load (0.5ms)   SELECT * FROM "blogs"
Comment Load (0.5ms)   SELECT "comments".* FROM "comments" WHERE ("comments".blog_id IN (1,2))

N+1 query fixed. Cool!

11. Now simulate unused eager loading. Change app/controllers/blogs_controller.rb and app/views/blogs/index.html.erb

def index
  @blogs = Blog.includes(:comments)

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

<% @blogs.each do |blog| %>
  <tr>
    <td><%= blog.name %></td>
    <td><%= link_to 'Show', blog %></td>
    <td><%= link_to 'Edit', edit_blog_path(blog) %></td>
    <td><%= link_to 'Destroy', blog, :confirm => 'Are you sure?', :method => :delete %></td>
  </tr>
<% end %>

12. Refresh http://localhost:3000/blogs, and you will see a popup alert box that says

The request has unused preload associations as follows:
model: Blog => 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: /blogs;    model: Blog => associations: [comments]·
Remove from your finder: :include => [:comments]

13. Simulate counter_cache. Change app/controllers/blogs_controller.rb and app/views/blogs/index.html.erb

def index
  @blogs = Blog.all

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

<% @blogs.each do |blog| %>
  <tr>
    <td><%= blog.name %></td>
    <td><%= blog.comments.size %></td>
    <td><%= link_to 'Show', blog %></td>
    <td><%= link_to 'Edit', edit_blog_path(blog) %></td>
    <td><%= link_to 'Destroy', blog, :confirm => 'Are you sure?', :method => :delete %></td>
  </tr>
<% end %>

14. Refresh http://localhost:3000/blogs, then you will see a popup alert box that says

Need counter cache
  Blog => [:comments]

Meanwhile, there's a line appended to log/bullet.log

2009-09-11 10:07:10[INFO] Need Counter Cache
  Blog => [:comments]

swazahmad

Swaz is Practice Lead of ROR Developer. he's a Blogger, Mentor, and Rubyst. He has expertise in Javascript also . he's highly skilled in designing, developing and testing web applications. He enjoys being challenged and interesting with projects that need him to