Bugsnag Notifier for Ruby

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.

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
Usage
Demo Applications
Support
Contributing
License
Additional Documentation
- Configuration
- [Notification Options](docs/Notification Options.md)

Getting Started

Installation

Add the bugsnag gem to your Gemfile
```
gem "bugsnag"
```
Install the gem
```
bundle install
```
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"
end
```
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 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"
end

YourApp::Application.load_tasks

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.

Usage

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
  Bugsnag.auto_notify($!)
  erb :"errors/500"
end

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 $!
    Bugsnag.notify($!)
  end
end

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:

EventMachine.error_handler{|e|
  Bugsnag.notify(e)
}

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

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

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(RuntimeError.new("Something broke"))

Additional data can be sent with exceptions as an options hash as detailed in the [Notification Options](docs/Notification Options.md) documentation, including some [options specific to non-fatal exceptions](docs/Notification Options.md#handled-notification-options).

Callbacks

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 bugsnag.com, 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
  end

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

    @bugsnag.call(notification)

    # Your custom "after notify" code
  end
end

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

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

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 bugsnag.com 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.

Support

Additional Documentation
Search open and closed issues for similar problems
Report a bug or request a feature

Contributing

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.

License

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

jgrau/bugsnag-ruby