Upgrading from gem v3 to v4

While the public API remains mostly unchanged, v4 of the honeybadger gem has a few breaking changes and deprecations to be aware of when upgrading:

  1. The disabled config option has been removed. Use report_data instead.
  2. If you use Honeybadger.exception_filter, update it to use the new syntax.
  3. If you use Honeybadger.exception_fingerprint, update it to use the new syntax.
  4. If you use Honeybadger.backtrace_filter, update it to use the new syntax.
  5. If you access notice properties using the Notice#[] array accessor in any of the above callbacks, you need to update them to use method calls instead.
  6. If you use the backtrace, fingerprint, or context notice properties in any of the above callbacks, review these changes.

Changes and additions (including a new feature!) are discussed in detail below.

New features

Honeybadger v4 has a few additions which make customizing error reports much easier than before. Let's take a look at the major changes.

The before_notify Callback

The new before_notify callback allows you to customize each error report before it's sent to Honeybadger. You can add as many callbacks as you need via Honeybadger.configure:

Honeybadger.configure do |config|

  # Ignore the notice if in the auth controller
  config.before_notify do |notice|
    notice.halt! if notice.controller == 'auth'
  end

  # Enrich the context with product information
  config.before_notify do |notice|
    if notice.url =~ /^checkout/
      product_name = Product.find(notice.parameters[:product_id])&.name
      notice.context.merge!(product: product_name)
    end
  end

end

Essential attributes on Notice are now writable

The following attributes on a notice are now writable; you can overwrite their values from a before_notify callback:

Honeybadger.configure do |config|
  config.before_notify do |notice|
    notice.api_key = 'custom api key'
    notice.error_message = "badgers!"
    notice.error_class = 'MyError'
    notice.backtrace = ["/path/to/file.rb:5 in `method'"]
    notice.fingerprint = 'some unique string'
    notice.tags = ['foo', 'bar']
    notice.context = { user: 33 }
    notice.controller = 'MyController'
    notice.action = 'index'
    notice.parameters = { q: 'badgers?' }
    notice.session = { uid: 42 }
    notice.url = "/badgers"
  end
end

Make sure that the type of attributes being set is correct. For instance, don't set the notice.backtrace to a string instead of an array of strings.

Stop notices using the new halt! method

Notice#halt! is a new method which allows you to stop a notice from being sent. You can use this in before_notify callbacks to write custom reporting rules:

Honeybadger.configure do |config|

  # stop the notice from being sent if it originates from the AuthController
  config.before_notify do |notice|
    notice.halt! if notice.controller == 'auth'
  end

end

Changes

  1. Notice#backtrace now returns an array instead of a custom Honeybadger::Backtrace object.
  2. Notice#fingerprint now returns the original string which was passed in from the :fingerprint and not a SHA1 hashed value. The value is still hashed before sending through to the API.
  3. Notice#context now defaults to an empty Hash instead of nil.

Deprecations

A few of the custom callbacks on Notice have been deprecated in favor of the new before_notify callbacks.

exception_filter

Honeybadger.exception_filter has been deprecated in favor of before_notify. If you want to stop a notice from being sent, use the notice.halt! method with a before_notify callback:

Honeybadger.configure do |config|
  config.before_notify do |notice|
    notice.halt! if is_secret?(notice)
  end
end

exception_fingerprint

Honeybadger.exception_fingerprint has been deprecated in favor of before_notify:

Honeybadger.configure do |config|
  config.before_notify do |notice|
    notice.fingerprint = 'new fingerprint'
  end
end

backtrace_filter

Honeybadger.backtrace_filter has been deprecated in favor of before_notify:

Honeybadger.configure do |config|
  config.before_notify do |notice|
    notice.backtrace.reject!{|x| x =~ /gem/}
  end
end

Breaking Changes

Removal of the disabled config option

The disabled config option has been removed in favor of the report_data option:

Honeybadger.configure do |config|
  config.report_data = false # Default is true
end

Removal of the Notice#[] accessor

The Notice#[] accessor method has been removed; use method calls instead:

# Change:
notice[:error_message] = 'oops!'

# To:
notice.error_message = 'oops!'