[Awesome Ruby Gem] Use bullet gem to help to kill N+1 queries and unused eager loading

Posted on Edited on In , , Views: Word count in article: 5.9k Reading time ≈ 5 mins.

bullet

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.

Installation

You can install it as a gem:

1
$ gem install bullet

or add it into a Gemfile (Bundler):

1
2
3
4
5
6
7
8
# Gemfile

# Put gems used only for development or testing in the appropriate group in the Gemfile
group :development do
  # flyerhzm/bullet: help to kill N+1 queries and unused eager loading
  # https://github.com/flyerhzm/bullet
  gem 'bullet', '6.1.2'
end

Then, run bundle install.

1
$ bundle install

Configuration

Enable the Bullet gem with generate command

1
$ 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.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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 => 'bullets_password_for_jabber',
                  :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

Bullet also allows you to disable any of its detectors.

1
2
3
4
5
6
7
8
9
10
11
# 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:

1
2
3
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

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

1
2
3
4
5
6
7
8
9
10
11
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:

1
2
3
4
5
6
7
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:

1
2
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:

1
2
2009-09-11 09:46:50[INFO] Need Counter Cache
  Post => [:comments]

Advanced

Work with ActiveJob

Include Bullet::ActiveJob in your ApplicationJob.

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

Work with other background job solution

Use the Bullet.profile method.

1
2
3
4
5
6
7
class ApplicationJob < ActiveJob::Base
  around_perform do |_job, block|
    Bullet.profile do
      block.call
    end
  end
end

Run in tests

First you need to enable Bullet in test environment.

1
2
3
4
5
6
# 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.

1
2
3
4
5
6
7
8
9
10
11
# 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

Demo

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

See Demo | flyerhzm/bullet: help to kill N+1 queries and unused eager loading - https://github.com/flyerhzm/bullet#demo to learn more.

References

[1] flyerhzm/bullet: help to kill N+1 queries and unused eager loading - https://github.com/flyerhzm/bullet

[2] bullet | RubyGems.org | your community gem host - https://rubygems.org/gems/bullet

[3] Optimize your Rails Code with Bullet Gem and Speed Up your site! | 123ish US - https://www.123ish.com/en/entries/2235-optimize-your-rails-code-with-bullet-gem-and-speed-up-your-site-

[4] Ruby’s Hidden Gems: Bullet | AppSignal Blog - https://blog.appsignal.com/2021/08/11/ruby-hidden-gems-bullet-and-how-it-integrates-with-appsignal.html