Skip to content
Bugsnag error monitoring for rails, sinatra, rack and ruby
Ruby HTML Other
Latest commit e21d012 May 11, 2016 @kattrali kattrali Release v4.1.0

Bugsnag Notifier for Ruby build status

The Bugsnag Notifier for Ruby gives you instant notification of exceptions thrown from your Rails, Sinatra, Rack or plain Ruby app. Any uncaught exceptions will trigger a notification to be sent to your Bugsnag project.

Capture Rails errors with Bugsnag's Rails error monitoring solution. Bugsnag captures errors in real-time from your web, mobile and desktop applications, helping you to understand and resolve them as fast as possible. Create a free account to start capturing exceptions from your applications.


Getting Started


  1. Add the bugsnag gem to your Gemfile

    gem "bugsnag"
  2. Install the gem

    bundle install
  3. Configure the Bugsnag module with your API key.

    Rails: Use our generator

    rails generate bugsnag YOUR_API_KEY_HERE

    Other Ruby/Rack/Sinatra apps: Put this snippet in your initialization.

    Bugsnag.configure do |config|
      config.api_key = "YOUR_API_KEY_HERE"

    The Bugsnag module will read the BUGSNAG_API_KEY environment variable if you do not configure one automatically.

Rake Integration

Rake integration is automatically enabled in Rails 3/4/5 apps, so providing you load the environment in your Rake tasks you dont need to do anything to get Rake support. If you choose not to load your environment, you can manually configure Bugsnag with a bugsnag.configure block in the Rakefile.

Bugsnag can automatically notify of all exceptions that happen in your rake tasks. In order to enable this, you need to require "bugsnag/rake" in your Rakefile, like so:

require File.expand_path('../config/application', __FILE__)
require 'rake'
require "bugsnag/rake"

Bugsnag.configure do |config|
  config.api_key = "YOUR_API_KEY_HERE"


Note: We also configure Bugsnag in the Rakefile, so the tasks that do not load the full environment can still notify Bugsnag.

Sending a Test Notification

To test that bugsnag is properly configured, you can use the test_exception rake task:

rake bugsnag:test_exception

A test exception will be sent to your bugsnag dashboard if everything is configured correctly.


Catching and Reporting Exceptions

Bugsnag Ruby works out of the box with Rails, Sidekiq, Resque, DelayedJob (3+), Mailman, Rake and Rack. It should be easy to add support for other frameworks, either by sending a pull request here or adding a hook to those projects.

Rack/Sinatra Apps

Activate the Bugsnag Rack middleware

use Bugsnag::Rack

Sinatra: Note that raise_errors must be enabled. If you are using custom error handlers, then you will need to notify Bugsnag explicitly:

error 500 do
  erb :"errors/500"

Custom Ruby Scripts

Custom Ruby Scripts: If you are running a standard ruby script, you can ensure that all exceptions are sent to Bugsnag by adding the following code to your app:

at_exit do
  if $!

EventMachine Apps

If your app uses EventMachine you'll need to manually notify Bugsnag of errors. There are two ways to do this in your EventMachine apps, first you should implement EventMachine.error_handler:


If you want more fine-grained error handling, you can use the errback function, for example:

EventMachine::run do
  server = EventMachine::start_server('', PORT, MyServer)
  server.errback {
    EM.defer do
      Bugsnag.notify("Something bad happened"))

For this to work, include Deferrable in your MyServer, then whenever you want to raise an error, call fail.

Sending Non-fatal Exceptions

If you would like to send non-fatal exceptions to Bugsnag, you can call Bugsnag.notify:

Bugsnag.notify("Something broke"))

Additional information can be attached to a notification using a configuration block:

Bugsnag.notify("Something broke")) do |notif|
  notif.severity = 'warning'

The complete list of available properties is available in the documentation for the Notification object


The Bugsnag Notifier for Ruby provides its own middleware system, similar to the one used in Rack applications. Middleware allows you to execute code before and after an exception is sent to, so you can do things such as:

  • Send application-specific information along with exceptions, eg. the name of the currently logged in user,
  • Write exception information to your internal logging system.

To make your own middleware, create a class that looks like this:

class MyMiddleware
  def initialize(bugsnag)
    @bugsnag = bugsnag

  def call(notification)
    # Your custom "before notify" code

    # Your custom "after notify" code

You can then add your middleware to the middleware stack as follows:

Bugsnag.configure do |config|
  config.middleware.use MyMiddleware

You can also view the order of the currently activated middleware by running rake bugsnag:middleware.

Check out Bugsnag's built in middleware classes for some real examples of middleware in action.

Deploy Tracking

Bugsnag allows you to track deploys of your apps. By sending the source revision or application version to when you deploy a new version of your app, you'll be able to see which deploy each error was introduced in.

Using Heroku

You can easily add Bugsnag deploy tracking to your Heroku application by running the following command from your application's directory:

$ bundle exec rake bugsnag:heroku:add_deploy_hook

If you have multiple Heroku apps, you can specify which app to add the hook for as with the HEROKU_APP environment variable:

$ bundle exec rake bugsnag:heroku:add_deploy_hook HEROKU_APP=my-app

Using Capistrano

If you use capistrano to deploy your apps, you can enable deploy tracking by adding the integration to your app's deploy.rb:

require "bugsnag/capistrano"

set :bugsnag_api_key, "api_key_here"

Using Rake

If you aren't using capistrano, you can run the following rake command from your deploy scripts.

rake bugsnag:deploy BUGSNAG_REVISION=source-control-revision BUGSNAG_RELEASE_STAGE=production BUGSNAG_API_KEY=api-key-here

The bugsnag rake tasks will be automatically available for Rails 3/4 apps, to make the rake tasks available in other apps, add the following to your Rakefile:

require "bugsnag/tasks"

Configuring Deploy Tracking

You can set the following environmental variables to override or specify additional deploy information:

  • BUGSNAG_API_KEY - Your Bugsnag API key (required).
  • BUGSNAG_RELEASE_STAGE - The release stage (eg, production, staging) currently being deployed. This is set automatically from your Bugsnag settings or rails/rack environment.
  • BUGSNAG_REPOSITORY - The repository from which you are deploying the code. This is set automatically if you are using capistrano.
  • BUGSNAG_BRANCH - The source control branch from which you are deploying the code. This is set automatically if you are using capistrano.
  • BUGSNAG_REVISION - The source control revision for the code you are currently deploying. This is set automatically if you are using capistrano.
  • BUGSNAG_APP_VERSION - The app version of the code you are currently deploying. Only set this if you tag your releases with semantic version numbers and deploy infrequently.

For more information, check out the deploy tracking api documentation.

Demo Applications

There are demo applications that use the Bugsnag Ruby gem: examples include Rails, Sinatra, Rack, Padrino integrations, etc.



We'd love you to file issues and send pull requests. The contributing guidelines details the process of building and testing bugsnag-ruby, as well as the pull request process. Feel free to comment on existing issues for clarification or starting points.


The Bugsnag ruby notifier is free software released under the MIT License. See LICENSE.txt for details.

Something went wrong with that request. Please try again.