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.
- How to Install
- Sending Custom Data With Exceptions
- Sending Non-Fatal Exceptions
- Configuration
- Bugsnag Middleware
- Deploy Tracking
- EventMachine Apps
-
Add the
bugsnag
gem to yourGemfile
gem "bugsnag"
-
Install the gem
bundle install
-
Configure the Bugsnag module with your API key.
In rails apps, put this code to a new file at
config/initializers/bugsnag.rb
Bugsnag.configure do |config| config.api_key = "YOUR_API_KEY_HERE" end
If you don't configure the api_key, the Bugsnag module will read the
BUGSNAG_API_KEY
environment variable. -
Rack/Sinatra apps only: Activate the Bugsnag Rack middleware
use Bugsnag::Rack
It is often useful to send additional meta-data about your app, such as information about the currently logged in user, along with any exceptions, to help debug problems.
In any rails controller you can define a before_bugsnag_notify
callback,
which allows you to add this additional data by calling add_tab
on the
exception notification object.
class MyController < ApplicationController
# Define the filter
before_bugsnag_notify :add_user_info_to_bugsnag
# Your controller code here
private
def add_user_info_to_bugsnag(notif)
# Add some app-specific data which will be displayed on a custom
# "User Info" tab on each error page on bugsnag.com
notif.add_tab(:user_info, {
name: current_user.name
})
end
end
In other ruby apps, you can provide lambda functions to execute before any
Bugsnag.notify
calls as follows. Don't forget to clear the callbacks at the
end of each request or session.
# Set a before notify callback
Bugsnag.before_notify_callbacks << lambda {|notif|
notif.add_tab(:user_info, {
name: current_user.name
})
}
# Your app code here
# Clear the callbacks
Bugsnag.before_notify_callbacks.clear
If you include the Bugsnag::MetaData
module into your own exceptions, you can
associate meta data with a paticular exception.
class MyCustomException < Exception
include Bugsnag::MetaData
end
exception = MyCustomException.new("It broke!")
exception.bugsnag_meta_data = {
:user_info => {
name: current_user.name
}
}
raise exception
You can read more about how callbacks work in the Bugsnag Middleware documentation below.
If you would like to send non-fatal exceptions to Bugsnag, you can call
Bugsnag.notify
:
Bugsnag.notify(RuntimeError.new("Something broke"))
You can also send additional meta-data with your exception:
Bugsnag.notify(RuntimeError.new("Something broke"), {
:username => "bob-hoskins",
:registered_user => true
})
Rake integration is automatically enabled in Rails 3 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.
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
To test that bugsnag is properly configured, you can use the test_exception rake task like this,
rake bugsnag:test_exception
A test exception will be sent to your bugsnag dashboard if everything is configured correctly.
To configure additional Bugsnag settings, use the block syntax and set any
settings you need on the config
block variable. For example:
Bugsnag.configure do |config|
config.api_key = "your-api-key-here"
config.use_ssl = true
config.notify_release_stages = ["production", "development"]
end
###api_key
Your Bugsnag API key (required).
config.api_key = "your-api-key-here"
###release_stage
If you would like to distinguish between errors that happen in different
stages of the application release process (development, production, etc)
you can set the release_stage
that is reported to Bugsnag.
config.release_stage = "development"
In rails apps this value is automatically set from RAILS_ENV
, and in rack
apps it is automatically set to RACK_ENV
. Otherwise the default is
"production".
###notify_release_stages
By default, we will notify Bugsnag of exceptions that happen in any
release_stage
. If you would like to change which release stages
notify Bugsnag of exceptions you can set notify_release_stages
:
config.notify_release_stages = ["production", "development"]
###auto_notify
By default, we will automatically notify Bugsnag of any fatal exceptions
in your application. If you want to stop this from happening, you can set
auto_notify
:
config.auto_notify = false
###use_ssl
Enforces all communication with bugsnag.com be made via ssl.
config.use_ssl = true
By default, use_ssl
is set to false.
###project_root
We mark stacktrace lines as inProject
if they come from files inside your
project_root
. In rails apps this value is automatically set to RAILS_ROOT
,
otherwise you should set it manually:
config.project_root = "/var/www/myproject"
###app_version
If you want to track which versions of your application each exception
happens in, you can set app_version
. This is set to nil
by default.
config.app_version = "2.5.1"
###params_filters
Sets the strings to filter out from the params
hashes before sending
them to Bugsnag. Use this if you want to ensure you don't send
sensitive data such as passwords, and credit card numbers to our
servers. Any keys which contain these strings will be filtered.
config.params_filters << "credit_card_number"
By default, params_filters
is set to ["password", "secret"]
###ignore_classes
Sets for which exception classes we should not send exceptions to bugsnag.com.
config.ignore_classes << "ActiveRecord::StatementInvalid"
You can also provide a lambda function here to ignore by other exception attributes or by a regex:
config.ignore_classes << lambda {|ex| ex.message =~ /timeout/}
By default, ignore_classes
contains the following:
[
"ActiveRecord::RecordNotFound",
"ActionController::RoutingError",
"ActionController::InvalidAuthenticityToken",
"CGI::Session::CookieStore::TamperedWithCookie",
"ActionController::UnknownAction",
"AbstractController::ActionNotFound"
]
###ignore_user_agents
Sets an array of Regexps that can be used to ignore exceptions from certain user agents.
config.ignore_user_agents << %r{Chrome}
By default, ignore_user_agents
is empty, so exceptions caused by all
user agents are reported.
###proxy_host
Sets the address of the HTTP proxy that should be used for requests to bugsnag.
config.proxy_host = "10.10.10.10"
###proxy_port
Sets the port of the HTTP proxy that should be used for requests to bugsnag.
config.proxy_port = 1089
###proxy_user
Sets the user that should be used to send requests to the HTTP proxy for requests to bugsnag.
config.proxy_user = "proxy_user"
###proxy_password
Sets the password for the user that should be used to send requests to the HTTP proxy for requests to bugsnag.
config.proxy_password = "proxy_secret_password_here"
###logger
Sets which logger to use for Bugsnag log messages. In rails apps, this is
automatically set to use Rails.logger
, otherwise it will be set to
Logger.new(STDOUT)
.
###middleware
Provides access to the middleware stack, see the Bugsnag Middleware section below for details.
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.
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.
If you use capistrano to deploy
your apps, you can enable deploy tracking by adding the following line to your
app's deploy.rb
:
require "bugsnag/capistrano"
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
The bugsnag rake tasks will be automatically available for Rails 3
apps, to make the rake tasks available in other apps, add the following to
your Rakefile
:
require "bugsnag/tasks"
You can set the following environmental variables to override or specify additional deploy information:
-
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_API_KEY - Your Bugsnag API key. This is set automatically from your Bugsnag settings in your app.
-
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.
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
.
Please report any bugs or feature requests on the github issues page for this project here:
https://github.com/bugsnag/bugsnag-ruby/issues
- Fork the notifier on github
- Commit and push until you are happy with your contribution
- Run the tests with
rake spec
and make sure they all pass - Make a pull request
- Thanks!
The Bugsnag ruby notifier is free software released under the MIT License. See LICENSE.txt for details.