Ruby gem to report exceptions to
Ruby JavaScript
Pull request Compare This branch is 1 commit ahead, 1190 commits behind rollbar:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

This library is deprecated, please use rollbar-gem

Ratchetio Build Status

Ruby gem for, for reporting exceptions in Rails 3 to Requires a account (you can sign up for free).


Add this line to your application's Gemfile:

gem 'ratchetio'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install ratchetio

Then, run the following command from your rails root:

$ rails generate ratchetio YOUR_RATCHETIO_PROJECT_ACCESS_TOKEN

That will create the file config/initializers/ratchetio.rb, which holds the configuration values (currently just your access token) and is all you need to use with Rails.

To confirm that it worked, run:

$ rake ratchetio: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 dashboard.

Manually reporting exceptions and messages

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

  foo = bar
rescue Exception => e

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:

  foo = bar
rescue Exception => e
  Ratchetio.report_exception(e, ratchetio_request_data, ratchetio_person_data)

You can also log individual messages:

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

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

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

Person tracking

Ratchet will send information about the current user (called a "person" in Ratchet 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/ratchetio.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/ratchetio.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"

Exception level filters

By default, all exceptions reported through Ratchetio.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/ratchetio.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 Ratchetio.silenced:

Ratchetio.silenced {
  foo = bar  # will not be reported

Asynchronous reporting

By default, all messages are reported synchronously. You can enable asynchronous reporting by adding the following in config/initializers/ratchetio.rb:

  config.use_async = true

Ratchet uses girl_friday to handle asynchronous reporting when installed, and falls back to Threading if girl_friday is not installed.

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 = { |payload| { Ratchetio.process_payload(payload) }

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

Using with ratchet-agent

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

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

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

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-ratchetio for using Ratchetio as a failure backend for Resque.

Help / Support

If you run into any issues, please email us at


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. 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.)