Reporting handled errors

Reporting handled errors allows your application to recover from an error, while still reporting it to BugSnag.

To notify Bugsnag of a handled exception you can call Bugsnag.notify:

begin
  raise 'Something went wrong!'
rescue => e
  Bugsnag.notify(e)
end

Sending custom diagnostics

In order to quickly understand and fix some errors, it is often helpful to send additional diagnostic data which is specific to that error. Bugsnag.notify accepts a block which can alter the report before it is sent to BugSnag.

Bugsnag.notify(exception) do |event|
  # Adjust the severity of this error
  event.severity = "warning"

  # Add customer information to this event
  event.add_metadata(:account, {
    name: "Acme Co.",
    paying_customer: true
  })
end

See the event object below for all available customization options.

The event object

add_feature_flag

Declare a single feature flag or experiment with variant as an optional second parameter.

event.add_feature_flag('Checkout button color', 'Blue')
event.add_feature_flag('New checkout flow')

For more information, see Feature flags & experiments.

add_feature_flags

Declare multiple feature flags or experiments.

event.add_feature_flags(
  [
    Bugsnag::FeatureFlag.new('Checkout button color', 'Blue')
    Bugsnag::FeatureFlag.new('New checkout flow')
  ]
)

For more information, see Feature flags & experiments.

add_metadata

Adds the specified key and value in the specified section, which is shown as a tab on the BugSnag dashboard.

Data can be added key-by-key:

event.add_metadata(:company, :name, 'Acme Co.')

Alternatively a Hash can be added to a section:

event.add_metadata(:company, {
  name: 'Acme Co.',
  country: 'uk'
})

add_tab

Call add_tab on an event object to add a tab to the event so that it would appear on your dashboard.

event.add_tab(:user_info, { name: "Bugs Nag" })

The first parameter is the tab name that will appear in the event and the second is the key, value list that will be displayed in the tab.

api_key

Set the project API key for the event. The API key is normally set in the configuration, but it can be overridden to report to a different API key in some situations.

event.api_key = 'your-api-key-here'

breadcrumbs

Customize or filter breadcrumbs to be sent with the event. Modified breadcrumbs will not be validated again.

event.breadcrumbs.each { |breadcrumb| breadcrumb.metadata = {} } # Clear the metadata

clear_feature_flag

Remove a single feature flag or experiment.

event.clear_feature_flag('Checkout button color')

clear_feature_flags

Remove all feature flags and experiments.

event.clear_feature_flags

clear_metadata

Removes all the data from the specified section or from a key in the section:

# Remove a single key
event.clear_metadata(:company, :name)

# Remove an entire section
event.clear_metadata(:company)

context

Set the context of the event. This is notionally the location of the error and should be populated automatically. Context is displayed in the dashboard prominently.

event.context = 'billing'

errors

Allows you to read the class, message and stacktrace of each error in this event.

puts "#{event.errors.first.error_class}: #{event.errors.first.error_message}"
puts event.errors.first.stacktrace

exceptions

Allows you to access and modify the exceptions that will be combined into the event.

puts event.exceptions.first[:message] + ' found!'

grouping_hash

Sets the grouping hash of the event. All errors with the same grouping hash are grouped together. This is an advanced usage of the library and misusing it will cause your errors not to group properly in your dashboard.

event.grouping_hash = event.exceptions.first[:message] + event.exceptions.first[:errorClass]

ignore!

Calling ignore! on an event object will prevent it from being sent to BugSnag. This means that you can choose dynamically not to send an error depending on application state or the error itself.

event.ignore! if foo == 'bar'

metadata

Provides access to the metadata in the event.

event.ignore! if event.metadata[:sidekiq][:retry_count] < 2

original_error

The Exception instance used to create this event

puts event.original_error.message

remove_tab

Removes a tab completely from the event.

event.remove_tab(:user_info)

request

Contains data for the active HTTP request, or nil if no request data has been captured.

puts event.request[:url]

set_user

Sets the current user information.

event.set_user('1234', 'bugs.nag@bugsnag.com', 'Bugs Nag')

nil can be used as a parameter value to clear the user attribute.

severity

Set the severity of the error. Severity can be error, warning or info.

event.severity = 'error'

summary

Creates a hashed summary of the event. Given keys are :error_class, :severity, and optionally :message.

summary = event.summary
puts "#{summary[:error_class]} occurred with message: #{summary[:message]}"

unhandled

By default this is true if the event was automatically detected by BugSnag and false if it was reported manually via Bugsnag.notify. See our product pages for more information on handled vs unhandled events.

event.unhandled = true

user

Returns the current user information.

puts event.user[:id], event.user[:email], event.user[:name]