Bugsnag

This add-on is operated by Bugsnag Inc

Intelligent exception monitoring for your apps

Bugsnag

Last Updated: 31 January 2014

Table of Contents

Bugsnag is an add-on for tracking your application’s exceptions.

Bugsnag lets you know which exceptions are happening most frequently, which users are affected, and what kinds of inputs cause problems. We notify you by email, hipchat or campfire the first time an exception happens and include enough information that you can find and fix bugs quickly and easily. We also integrate with bugtrackers and project management tools like Github Issues, Pivotal Tracker and JIRA so that your entire team can see what needs to be fixed.

Bugsnag is accessible via an API and has supported client libraries for Ruby, Python, Node.js, Java, and many other languages.

Provisioning the add-on

Bugsnag can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add bugsnag
-----> Adding bugsnag to sharp-mountain-4005... done, v18 ($39/mo)

Once Bugsnag has been added a BUGSNAG_API_KEY setting will be available in the app configuration and will contain the api key needed to talk to the bugsnag API. This can be confirmed using the heroku config:get command.

$ heroku config:get BUGSNAG_API_KEY
70d9b0852a968b1d0d0e329b5507f287

Most of the Bugsnag client libraries will automatically read this environment variable and will start sending unhandled exceptions to Bugsnag as soon as they are deployed.

Local setup

Environment setup

If you want to test Bugsnag in development you need to export the same BUGSNAG_API_KEY as we have provisioned in production.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the BUGSNAG_API_KEY values retrieved from heroku config to .env.

$ heroku config -s | grep BUGSNAG_API_KEY >> .env
$ more .env

A slightly less portable way of achieving the same thing is to just export BUGSNAG_API_KEY=value in a terminal before starting your app.

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using with Rails 3.x/4

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Bugsnag client library.

gem 'bugsnag'

Update application dependencies with bundler.

$ bundle install

At this point all unhandled exceptions in production will be sent to Bugsnag. You can also use Bugsnag.notify to send handled exceptions as described in the README.

Using with Rack/Sinatra

Ruby applications will need to add the following entry into their Gemfile specifying the Bugsnag client library.

gem 'bugsnag'

Update application dependencies with bundler.

$ bundle install

Add the Bugsnag middleware to your config.ru.

use Bugsnag::Rack

At this point all unhandled exceptions in production will be sent to Bugsnag. You can also use Bugsnag.notify to send handled exceptions as described in the README.

Using with Python

Python applications will need to add the following entry to their requirements.txt specifying the Bugsnag client library.

bugsnag>=1.2.5

Update application dependencies with pip.

$ pip install -r requirements.txt

And then add the Bugsnag middleware to your app. For Django apps you can edit your MIDDLEWARE_CLASSES in settings.py.

MIDDLEWARE_CLASSES = (
    ...
    "bugsnag.django.middleware.BugsnagMiddleware"
)

For other Python frameworks, see the notifier README.

Dashboard

For more information on the features available within the Bugsnag dashboard please see the docs at bugsnag.com/docs.

The Bugsnag dashboard allows you to see which exceptions are currently affecting your app, how frequently, and how severely. You can use it as a debugging tool for finding out what conditions cause exceptions, a todo list for prioritizing which bugs to fix, or a status page that gives you a feel for how buggy or not your app is.

The dashboard can be accessed via the CLI:

$ heroku addons:open bugsnag
Opening bugsnag for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Bugsnag from the Add-ons menu.

Troubleshooting

If you do not seem to be seeing any exceptions in Bugsnag, it’s worth checking that you have installed the notifier library and it is configured correctly.

For rails apps this can be done by running our rake task.

$ heroku run rake bugsnag:test_exception

For other apps, just add a manual Bugsnag notification call to your app.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade bugsnag:full
-----> Upgrading bugsnag:full to sharp-mountain-4005... done, v18 ($99/mo)
       Your plan has been updated to: bugsnag:full

Removing the add-on

Bugsnag can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove bugsnag
-----> Removing bugsnag from sharp-mountain-4005... done, v20 ($39/mo)

Before removing Bugsnag you can download any data you want to keep using the API.

Support

All Bugsnag support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome by email or in our Uservoice.