Add BugSnag to your Ruby on Rails projects to automatically monitor exceptions in your Rails applications.
New to BugSnag? Create an account
Looking for performance monitoring? See our performance guide
Add the bugsnag gem to your Gemfile:
bundle add bugsnag
The latest available version of bugsnag is v6.27.1.
Run our generator to create the config/initializers/bugsnag.rb configuration file and set your project’s integration API key:
$ rails generate bugsnag YOUR_API_KEY_HERE
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.
After completing installation and basic configuration, unhandled exceptions in your Rails app will be automatically reported to your BugSnag dashboard.
Exceptions in Active Job, Sidekiq, Resque, Delayed Job, Mailman, and Rake will also be automatically reported.
Reporting handled exceptions can be accomplished as follows:
begin
raise 'Something went wrong!'
rescue => exception
Bugsnag.notify(exception)
end
It can often be helpful to adjust the severity or attach custom diagnostics to handled exceptions. For more information, see reporting handled errors.
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
Errors that occur during an Active Job execution are captured by BugSnag. Events will be captured for each job failure irrespective of retry or discard conditions in place. For more information on how to change this behaviour, see customizing error reports.
BugSnag will automatically capture and attach the following diagnostic data to every exception event:
It can often be helpful to attach application-specific diagnostic data to events. This can be accomplished as follows:
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
For more information, see customizing error reports.
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:
If you are using the Devise, Warden, or Clearance authentication frameworks, we will automatically capture information about the currently authenticated user. Otherwise, you can set this information as follows:
class ApplicationController < ActionController::Base
before_bugsnag_notify :add_user_info_to_bugsnag
# Your controller code here
private
def add_user_info_to_bugsnag(event)
event.set_user("9000", "bugs.nag@bugsnag.com", "Bugs Nag")
end
end
For more information, see customizing error reports.
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.
Sessions are captured and reported by default. This behavior can be disabled using the auto_track_sessions configuration option.
When enabled, sessions are automatically captured whenever a request is made to the Rails server.
For more information about manually controlling session tracking, see Capturing sessions.
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.
By default, BugSnag captures common events including:
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.
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 thread serving the current request or queued job.
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.
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 thread serving the current request or queued job.
For more information, see Feature flags & experiments.
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
Catch and report errors in your client-side JavaScript with the Web browser JavaScript guide