Rake integration guide

Add Bugsnag error monitoring to your Rake tasks.

Installation

Add the bugsnag gem to your Gemfile:

bundle add bugsnag

Basic configuration

Rails applications

If you are using Rake as part of Rails application, and have already configured Bugsnag in your Rails application, then Bugsnag will automatically be configured, as long as your Rake tasks depend on the :environment task.

Other applications

To identify your app in the Bugsnag dashboard, you’ll need to configure your Bugsnag API key. You can find your API key when creating a project in your Bugsnag dashboard, or later from your project settings page.

To set your API key in your Rack app, add the following code to your Rakefile:

require 'bugsnag/integrations/rake'

Bugsnag.configure do |config|
  config.api_key = 'YOUR_API_KEY_HERE'
end

Alternatively, you can set the BUGSNAG_API_KEY environment variable.

If you’d like to configure Bugsnag further, check out the configuration options reference.

Reporting unhandled exceptions

Rails applications

If you are using Rake as part of Rails application, then Bugsnag will automatically detect unhandled exceptions, as long as your Rake tasks depend on the :environment task.

Other applications

In your Rakefile, simply require bugsnag:

require 'bugsnag'

At this point, Bugsnag should be installed and configured, and any unhandled exceptions will be automatically detected and should appear in your Bugsnag dashboard.

Reporting handled exceptions

Reporting handled exceptions can be accomplished as follows:

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

Adding diagnostics or adjusting severity

It can often be helpful to adjust the severity or attach custom diagnostics to handled exceptions. For more information, see reporting handled errors.

Avoiding re-notifying exceptions

Sometimes after catching and notifying a handled exception you may want to re-raise the exception to be dealt with by your standard error handlers without sending an automatic exception to Bugsnag. This can be accomplished by setting a skip_bugsnag property on the exception to true as follows:

begin
  raise 'Something went wrong!'
rescue CustomException => exception
  Bugsnag.notify(exception)
  exception.skip_bugsnag = true

  # Now this won't be sent a second time by the exception handlers
  raise exception
end

Sending diagnostic data

Automatically captured diagnostics

As well as a full stacktrace for every exception, Bugsnag will automatically capture the name, description, and arguments of the running task.

Custom diagnostics

In order to quickly reproduce and fix errors, it is often helpful to send additional application-specific diagnostic data to Bugsnag. This can be accomplished using a before notify callback as follows:

Bugsnag.before_notify_callbacks << lambda {|report|
  report.add_tab(:diagnostics, {
    product: current_product.name
  })
}

For more information, see the customizing error reports reference.

Logging breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. By default, the last 25 breadcrumbs are attached to an error report to help diagnose what events lead to the error. Captured breadcrumbs are shown on your Bugsnag dashboard as a part of the error report.

Automatically captured breadcrumbs

By default, Bugsnag captures common events including:

  • Error reports
  • Mongo queries

A full breakdown of automatically captured events can be found here. You can prevent the capture of certain automatically captured breadcrumbs by removing the type from the enabled_automatic_breadcrumb_types configuration array.

Attaching custom breadcrumbs

Leaving a breadcrumb is accomplished using the leave_breadcrumb method:

Bugsnag.leave_breadcrumb "Something happened!"

When logging breadcrumbs, we’ll keep track of the timestamp, and show both the message and timestamp on your dashboard.

Additional data can optionally be attached to breadcrumbs:

meta_data = {
    :userId => get_current_user.id,
    :authLevel => get_current_user.get_level
}
Bugsnag.leave_breadcrumb("User logged in", meta_data, Bugsnag::Breadcrumbs::USER_BREADCRUMB_TYPE)

The breadcrumb name will be trimmed to be 30 characters maximum, and all meta data must be of the Numeric, String, TrueClass, or FalseClass types, or nil.

Filtering breadcrumbs

Both automatically and manually created breadcrumbs can be filtered to remove sensitive data, or be ignored completely.

Callbacks can be registered by adding them to the before_breadcrumb_callbacks array in the configuration. This callback will have access to each breadcrumb, and can modify it or prevent collection using the methods described in the breadcrumb object:

config.before_breadcrumb_callbacks << Proc.new do |breadcrumb|
  # Ignores all breadcrumbs of a certain type
  breadcrumb.ignore! if breadcrumb.type == Bugsnag::Breadcrumbs::PROCESS_BREADCRUMB_TYPE

  # Removes any collected breadcrumb meta data
  breadcrumb.meta_data = {}
end

Similarly to the report meta data, the breadcrumb’s meta data will be filtered based on the meta_data_filters before delivery.

Tracking releases

By sending your application version to us when you release a new version of your app, you’ll be able to see which release each error was introduced or seen in.

Ensure you’ve set your app version within the application:

Bugsnag.configure do |config|
  config.app_version = '1.3.0'
end

Set up a build tool integration to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.

Catching JavaScript errors

Catch and report errors in your client-side JavaScript with the Web browser JavaScript guide