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 error report, or adjust error reports 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(report)
    report.add_tab(: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 report 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 |report|
    # Add user information to every report
    report.user = {
      id: current_user.id,
      email: current_user.email,
      name: current_user.name
    }
  end)
end

On error callbacks receive the same report 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 |report|
    !user_has_opted_out
  end)
end

Custom error diagnostic data

If you are using custom error classes within your application, diagnostic data can be automatically attached to each error report 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.

The report object

add_tab

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

report.add_tab(:user_info, { name: current_user.name })

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

api_key

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

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

breadcrumbs

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

report.breadcrumbs.each { |breadcrumb| breadcrumb.meta_data = {} } # Clear the meta data

context

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

report.context = 'billing'

exceptions

Allows you to read the exceptions that will be combined into the report.

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

grouping_hash

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

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

ignore!

Calling ignore! on a report object will cause the report to not be sent to Bugsnag. This means that you can choose dynamically not to send an error depending on application state or the error itself.

report.ignore! if foo == 'bar'

meta_data

Provides access to the meta_data in the error report.

report.ignore! if report.meta_data[:sidekiq][:retry_count] < 2

remove_tab

Removes a tab completely from the error report

report.remove_tab(:request)

severity

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

report.severity = 'error'

summary

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

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

user

You can set or read the user with the user property of the report.

report.user = {
  id: current_user.id,
  email: current_user.email,
  name: current_user.name
}

The breadcrumb object

name

A short description of the breadcrumbed event. This shows up prominently on the Bugsnag dashboard.

breadcrumb.name += ': some extra context'

type

Identifies what kind of event occurred.

breadcrumb.meta_data = {} if breadcrumb.type == Bugsnag::Breadcrumbs::PROCESS_BREADCRUMB_TYPE

There is a list of valid types within the Bugsnag::Breadcrumbs module, defaulting to MANUAL_BREADCRUMB_TYPE.

meta_data

A hash of additional data about the event. This can help to determine if or how this event may have caused an error notification.

breadcrumb.meta_data[:authorized] = user_authorized?(user_id)

This data can only consist of String, Numeric, or TrueClass/FalseClass type objects, or nil, with non-conforming entries being removed.

auto

Describes if the breadcrumb was automatically generated or not.

puts breadcrumb.auto ? "Bugsnag generated" : "Manually created"

This cannot be modified.

timestamp

The time the breadcrumb was created.

puts "Breadcrumb created at #{breadcrumb.timestamp}"

This cannot be modified.