Other Ruby apps

Add BugSnag to other Ruby applications, such as standalone scripts.

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 app, add the following code to your entrypoint:

require 'bugsnag'

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

Alternatively, you can set the BUGSNAG_API_KEY environment variable.

You can find your API key in Project Settings from your BugSnag dashboard.

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

Reporting unhandled exceptions

You can ensure that all unhandled exceptions are sent to BugSnag by adding the following code to your app:

at_exit do
  if $!
    Bugsnag.notify($!)
  end
end

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 calling Bugsnag.notify(), adding a custom skip_bugsnag property to your exception, and then re-raising the exception:

begin
  raise 'Something went wrong!'
rescue => exception
  Bugsnag.notify(exception)
  exception.instance_eval { def skip_bugsnag; true; end }

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

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 set_user in an add_on_error callback:

Bugsnag.configure do |config|
  config.add_on_error(proc do |event|
    event.set_user("9000", "bugs.nag@bugsnag.com", "Bugs Nag")
  end)
end

For more information, see reporting handled errors.

Sending diagnostic data

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 an add_on_error callback as follows:

Bugsnag.configure do |config|
  config.add_on_error(proc do |event|
    event.add_metadata(:diagnostics, {
      product: current_product.name
    })
  end)
end

For more information, see the customizing error reports reference.

Session tracking

BugSnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

To manually start a session call Bugsnag.start_session where appropriate in your application.

For more information about manually controlling session tracking, see Capturing sessions.

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 event 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_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.

Breadcrumbs are scoped to the current thread.

Additional data can also be attached to breadcrumbs by providing the optional metadata and type parameters. For more information and examples for how custom breadcrumbs can be integrated, see customizing breadcrumbs.

Declaring feature flags and experiments

Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the BugSnag client. You can use the Features dashboard to identify whether these features have introduced errors into your app.

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

Feature flags are scoped to the current thread.

For more information, see Feature flags & experiments.

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.

If you use Capistrano to release your apps, check out the Capistrano release tracking guide