Rollbar notifier for Ruby

Ruby gem for reporting exceptions, errors, and log messages to Rollbar.

Installation

Add this line to your application's Gemfile:

gem 'rollbar'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install rollbar

Then, run the following command from your rails root:

$ rails generate rollbar POST_SERVER_ITEM_ACCESS_TOKEN

That will create the file config/initializers/rollbar.rb, which holds the configuration values (currently just your access token). Make sure you're using the post_server_item access token.

If you want to store your access token outside of your repo, run the same command without arguments:

$ rails generate rollbar

Then, create an environment variable ROLLBAR_ACCESS_TOKEN and set it to your server-side access token.

$ export ROLLBAR_ACCESS_TOKEN=POST_SERVER_ITEM_ACCESS_TOKEN

For Heroku users

$ heroku config:add ROLLBAR_ACCESS_TOKEN=POST_SERVER_ITEM_ACCESS_TOKEN

That's all you need to use Rollbar with Rails.

Test your installation

To confirm that it worked, run:

$ rake rollbar:test

This will raise an exception within a test request; if it works, you'll see a stacktrace in the console, and the exception will appear in the Rollbar dashboard.

Reporting form validation errors

To get form validation errors automatically reported to Rollbar just add the following after_validation callback to your models:

after_validation :report_validation_errors_to_rollbar

Manually reporting exceptions and messages

To report a caught exception to Rollbar, simply call Rollbar.report_exception:

begin
  foo = bar
rescue Exception => e
  Rollbar.report_exception(e)
end

If you're reporting an exception in the context of a request and are in a controller, you can pass along the same request and person context as the global exception handler, like so:

begin
  foo = bar
rescue Exception => e
  Rollbar.report_exception(e, rollbar_request_data, rollbar_person_data)
end

You can also log individual messages:

# logs at the 'warning' level. all levels: debug, info, warning, error, critical
Rollbar.report_message("Unexpected input", "warning")

# default level is "info"
Rollbar.report_message("Login successful")

# can also include additional data as a hash in the final param. :body is reserved.
Rollbar.report_message("Login successful", "info", :user => @user)

Data sanitization (scrubbing)

By default, the notifier will "scrub" the following fields from requests before sending to Rollbar

:passwd
:password
:password_confirmation
:secret
:confirm_password
:password_confirmation
:secret_token

If a request contains one of these fields, the value will be replaced with a "*" before being sent.

Additional fields can be scrubbed by updating Rollbar.configuration.scrub_fields:

# scrub out the "user_password" field
Rollbar.configuration.scrub_fields |= [:user_password]

Person tracking

Rollbar will send information about the current user (called a "person" in Rollbar parlance) along with each error report, when available. This works by calling the current_user controller method. The return value should be an object with an id method and, optionally, username and email methods.

If the gem should call a controller method besides current_user, add the following in config/initializers/rollbar.rb:

config.person_method = "my_current_user"

If the methods to extract the id, username, and email from the object returned by the person_method have other names, configure like so in config/initializers/rollbar.rb:

config.person_id_method = "user_id"  # default is "id"
config.person_username_method = "user_name"  # default is "username"
config.person_email_method = "email_address"  # default is "email"

Including additional runtime data

You can provide a lambda that will be called for each exception or message report. custom_data_method should be a lambda that takes no arguments and returns a hash.

Add the following in config/initializers/rollbar.rb:

config.custom_data_method = lambda {
  { :some_key => :some_value, :complex_key => {:a => 1, :b => [2, 3, 4]} }
}

This data will appear in the Occurrences tab and on the Occurrence Detail pages in the Rollbar interface.

Exception level filters

By default, all exceptions reported through Rollbar.report_exception() are reported at the "error" level, except for the following, which are reported at "warning" level:

ActiveRecord::RecordNotFound
AbstractController::ActionNotFound
ActionController::RoutingError

If you'd like to customize this list, see the example code in config/initializers/rollbar.rb. Supported levels: "critical", "error", "warning", "info", "debug", "ignore". Set to "ignore" to cause the exception not to be reported at all.

Silencing exceptions at runtime

If you just want to disable exception reporting for a single block, use Rollbar.silenced:

Rollbar.silenced {
  foo = bar  # will not be reported
}

Asynchronous reporting

By default, all messages are reported synchronously. You can enable asynchronous reporting with girl_friday or Sidekiq.

Using girl_friday

Add the following in config/initializers/rollbar.rb:

config.use_async = true

Asynchronous reporting falls back to Threading if girl_friday is not installed.

Using Sidekiq

Add the following in config/initializers/rollbar.rb:

config.use_sidekiq = true

You can also supply custom Sidekiq options:

config.use_sidekiq = { 'queue' => 'my_queue' }

Start the redis server:

$ redis-server

Start Sidekiq from the root directory of your Rails app and declare the name of your queue. Unless you've configured otherwise, the queue name is "rollbar":

$ bundle exec sidekiq -q rollbar

Using another handler

You can supply your own handler using config.async_handler. The handler should schedule the payload for later processing (i.e. with a delayed_job, in a resque queue, etc.) and should itself return immediately. For example:

config.async_handler = Proc.new { |payload|
  Thread.new { Rollbar.process_payload(payload) }
}

Make sure you pass payload to Rollbar.process_payload in your own implementation.

Using with rollbar-agent

For even more asynchrony, you can configure the gem to write to a file instead of sending the payload to Rollbar servers directly. rollbar-agent can then be hooked up to this file to actually send the payload across. To enable, add the following in config/initializers/rollbar.rb:

config.write_to_file = true
# optional, defaults to "#{AppName}.rollbar"
config.filepath = '/path/to/file.rollbar' #should end in '.rollbar' for use with rollbar-agent

For this to work, you'll also need to set up rollbar-agent--see its docs for details.

Deploy Tracking with Capistrano

Add the following to deploy.rb:

require 'rollbar/capistrano'
set :rollbar_token, 'POST_SERVER_ITEM_ACCESS_TOKEN'

Available options:

rollbar_token: The same project access token as you used for the ```rails generate rollbar``` command; find it in ```config/initializers/rollbar.rb```. (It's repeated here for performance reasons, so the rails environment doesn't have to be initialized.)
rollbar_env: Deploy environment name
Default: rails_env

For capistrano/multistage, try:

set(:rollbar_env) { stage }

Counting specific gems as in-project code

In the Rollbar interface, stacktraces are shown with in-project code expanded and other code collapsed. Stack frames are counted as in-project if they occur in a file that is inside of the configuration.root (automatically set to Rails.root if you're using Rails). The collapsed sections can be expanded by clicking on them.

If you want code from some specific gems to start expanded as well, you can configure this in config/initializers/rollbar.rb:

Rollbar.configure do |config |
  config.access_token = '...'
  config.project_gems = ['my_custom_gem', 'my_other_gem']
end

Using with Goalie

If you're using Goalie for custom error pages, you may need to explicitly add require 'goalie' to config/application.rb (in addition to require 'goalie/rails') so that the monkeypatch will work. (This will be obvious if it is needed because your app won't start up: you'll see a cryptic error message about Goalie::CustomErrorPages.render_exception not being defined.)

Using with Resque

Check out resque-rollbar for using Rollbar as a failure backend for Resque.

Using with Zeus

Some users have reported problems with Zeus when rake was not explicitly included in their Gemfile. If the zeus server fails to start after installing the rollbar gem, try explicitly adding gem 'rake' to your Gemfile. See this thread for more information.

Help / Support

If you run into any issues, please email us at support@rollbar.com

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

We're using RSpec for testing. Run the test suite with rake spec. Tests for pull requests are appreciated but not required. (If you don't include a test, we'll write one before merging.)

fab/rollbar-gem

Rollbar notifier for Ruby

Installation

For Heroku users

Test your installation

Reporting form validation errors

Manually reporting exceptions and messages

Data sanitization (scrubbing)

Person tracking

Including additional runtime data

Exception level filters

Silencing exceptions at runtime

Asynchronous reporting

Using girl_friday

Using Sidekiq

Using another handler

Using with rollbar-agent

Deploy Tracking with Capistrano

Counting specific gems as in-project code

Using with Goalie

Using with Resque

Using with Zeus

Help / Support

Contributing