Rack integration guide

Add Bugsnag to your Rack based projects.

Installation

Add the bugsnag gem to your Gemfile:

bundle add bugsnag

Basic configuration

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 config.ru file:

require 'bugsnag'

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

To automatically capture unhandled exceptions, you’ll need to enable the Bugsnag Rack middleware:

use Bugsnag::Rack

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 following diagnostic data:

  • Request information, including ip, headers, URL, HTTP method, and HTTP params
  • Release stage (production, beta, staging, etc)
  • Hostname

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.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard.

You can set this information using a before notify callback as follows:

Bugsnag.before_notify_callbacks << lambda {|report|
  report.user = {
    email: current_user.email,
    name: current_user.name,
    id: current_user.id
  }
}

For more information, see reporting handled errors.

Session tracking

Bugsnag can track the number of “sessions” that happen in your application. This enables Bugsnag to provide and compare stability scores between releases to help you understand the quality of your releases. This functionality is disabled by default, but can be enabled through the configuration:

Bugsnag.configure do |configuration|
  configuration.auto_capture_sessions = true
end

Using this option, Bugsnag will report a session each time a request is made to the server.

If you want control over what is deemed a session, rather than using the auto_capture_sessions option, you can call Bugsnag.start_session when appropriate for your application.

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