Customizing error reports

In order to quickly reproduce and fix errors, it is often helpful to send additional application-specific diagnostic data to BugSnag.

Updating events using callbacks

If you’d like to add diagnostic data to every event, or adjust events conditionally, you can add callbacks which will be invoked each time a report will be sent:

class ApplicationController < ActionController::Base
  before_bugsnag_notify :add_diagnostics_to_bugsnag

  # Your controller code here

  private
  def add_diagnostics_to_bugsnag(event)
    event.add_metadata(:diagnostics, {
      product: current_product.name
    })
  end
end

This callback will be executed for every handled and unhandled exception detected from requests processed by this controller.

See the event object for methods available inside the callback.

On error callbacks

Callbacks can also be added globally to avoid having to repeat the same before_bugsnag_notify in all of your controllers. This is done using add_on_error callbacks, which can be added in the BugSnag initializer:

Bugsnag.configure do |config|
  config.add_on_error(proc do |event|
    # Add user information to every event
    event.set_user("9000", "bugs.nag@bugsnag.com", "Bugs Nag")
  end)
end

On error callbacks receive the same event object as before_bugsnag_notify callbacks.

Discarding events

If you want to prevent an event from being sent to BugSnag, you can return false within an add_on_error callback. This would allow for users to opt out of sending error reports, for example:

Bugsnag.configure do |config|
  config.add_on_error(proc do |event|
    !user_has_opted_out
  end)
end

Discarding Active Job events

When processing events in a queue, failures will usually be automatically retried. Reporting all the failures to BugSnag may not be desirable, since you’ll be getting duplicate reports and if a subsequent retry succeeds you may not even have a bug that needs fixing. You can avoid this by discarding the Bugsnag events until the underlying queue event has reach a certain number of retries. This will work from Rails 5 onwards:

Bugsnag.configure do |config|
  config.add_on_error(proc do |event|

    next unless event.metadata.key?(:active_job)

    executions = event.metadata[:active_job][:executions]

    # discard events until at least 3 executions
    # note: 'executions' counts the attempt that triggered this error, i.e. it
    #       starts at '1' and will increase each time
    if executions < 3
      false
    end
  end)
end

It’s also possible to discard all events from our built-in Active Job handler with an on error callback like this:

config.add_on_error(proc do |event|
  if event.metadata.key?(:active_job)
    false
  end
end)

Custom error diagnostic data

If you are using custom error classes within your application, diagnostic data can be automatically attached to each event within the exception class itself.

This is achieved by creating a bugsnag_meta_data function on the custom error class that returns a hash with the data you wish to attach.

class MyCustomError < StandardError
  attr_reader :metadata
  def initialize(message, metadata)
    super(message)
    @metadata = metadata
  end

  def bugsnag_meta_data
     {tabname: metadata}
  end
end

Bugsnag.notify(MyCustomError.new("Error message", value1: '1', value2: {nested: 3}))

This will add a tab with the name tabname on the dashboard with the corresponding data listed in it.

Global metadata

If you have metadata that is applicable to all captured events, it can be set globally on the Bugsnag client and will be set on all subsequently generated events. To ensure that events contain metadata as soon as BugSnag starts capturing events, use the add_metadata method in your configure block.

The top-level key in the map is displayed as a tab in the BugSnag dashboard:

Bugsnag.configure do |config|
  config.add_metadata(:company, {
    name: 'Acme Co.',
    country: 'uk'
  })
end

Metadata can also be managed whilst your application is running using add_metadata and clear_metadata on the Bugsnag client:

Bugsnag.add_metadata(:company, {
  name: 'Acme Co.',
  country: 'uk'
})
# ...
Bugsnag.clear_metadata(:company)

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]