Bullet

Bullet integrates with Rails by extending ActiveRecord (and ActiveController for Rails 2.x) or by inserting itself as Rack middleware in Rails 3+.

The request lifecycle follows these steps:

1. Bullet.start_request is called, resetting detectors and clearing the notification collector.
2. Rails handles the request; ActiveRecord extensions trigger Detector callbacks.
3. Detectors identify noteworthy events and create Notification instances, which are stored in the main Bullet module's collector.
4. After the request is handled, Bullet iterates over each notification using a Presenter to generate inline messages appended to the response body.
5. Bullet generates out-of-channel messages for each notification.
6. Bullet calls end_request for each detector.
7. The cycle repeats for the next request.

For Minitest, wrap tests by overriding before_setup and after_teardown in your TestCase class to ensure Bullet.start_request and Bullet.end_request are called.

# test/test_helper.rb
module ActiveSupport
  class TestCase
    def before_setup
      Bullet.start_request
      super
    end

    def after_teardown
      super
      Bullet.perform_out_of_channel_notifications if Bullet.notification?
      Bullet.end_request
    end
  end
end

To use Bullet in a Sinatra application, configure it and use the Bullet::Rack middleware. If your application uses a separate middleware for Content-Security-Policy, ensure Bullet::Rack is loaded before that middleware.

configure :development do
  Bullet.enable = true
  Bullet.bullet_logger = true
  use Bullet::Rack
end

To detect N+1 queries within background jobs, include Bullet::ActiveJob in your ApplicationJob class.

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

To extend Bullet with new detection capabilities, follow these steps:

1. Add your new detector class to the DETECTORS constant in the main Bullet module.
2. Add any necessary Rails monkey patches to Bullet.enable.
3. Add an autoload directive to lib/bullet/detector.rb.
4. Create a corresponding notification class within the Bullet::Notification namespace.
5. Add an autoload directive to lib/bullet/notification.rb.

Note: It is recommended that each Detector has its own dedicated Notification class. For implementation guidance, refer to the existing counter cache detector and its associated notification.

For background job solutions other than ActiveJob, use the Bullet.profile method to wrap the job execution logic.

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

Enable Bullet in your test environment configuration (e.g., config/environments/test.rb) to catch N+1 queries during automated tests. You can also set Bullet.raise = true to raise an error immediately when an N+1 query is detected.

# 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

After adding gem "bullet" to your Gemfile and running bundle install, use the Rails generator to complete the installation.

bundle exec rails g bullet:install

While Controller and integration tests work automatically via Rack middleware, model tests and other non-HTTP tests require manual wrapping using Bullet.start_request and Bullet.end_request. Use the following configuration in spec/rails_helper.rb to wrap every test.

# spec/rails_helper.rb
RSpec.configure do |config|
  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

You can install Bullet as a standalone gem or add it to your Gemfile. If using a Gemfile, ensure bullet is added after activerecord (Rails) or mongoid.

To install via command line:

gem install bullet

To add to a Gemfile (recommended for Rails/Mongoid apps):

gem 'bullet', group: 'development'

After adding to your Gemfile, run the generator to create default configuration files:

bundle exec rails g bullet:install

You can enable or disable specific query detection types. All settings default to true.

• Bullet.n_plus_one_query_enable: Detects N+1 queries.
• Bullet.unused_eager_loading_enable: Detects eager-loaded associations that are not used.
• Bullet.counter_cache_enable: Detects unnecessary COUNT queries that could be avoided with a counter_cache.