Rollbar

This add-on is operated by Rollbar

High performance error tracking for developers.

Rollbar

Last Updated: 04 June 2015

Table of Contents

Rollbar is an add-on for tracking and reproducing exceptions and errors. We collect, de-duplicate, and alert on error conditions, and provide a dashboard and analysis tools so you can understand, reproduce, and fix errors quickly.

Adding Rollbar to your app means you’ll always know what errors your users are seeing, and you’ll often be able to fix them before users complain.

Rollbar is accessible via an API and has supported client libraries for Ruby, Python, Node.js, PHP, Javascript, and Flash.

Provisioning the add-on

Rollbar can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:create rollbar:free

Once Rollbar has been added, a ROLLBAR_ACCESS_TOKEN setting will be available in the app configuration and will contain your server-side access token. This can be confirmed using the heroku config:get command.

$ heroku config:get ROLLBAR_ACCESS_TOKEN
a1a1b2b2c3c3d4d4e5e5f6f6e7e7d8d8

After installing Rollbar the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export ROLLBAR_ACCESS_TOKEN=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the ROLLBAR_ACCESS_TOKEN values retrieved from heroku config to .env.

$ heroku config -s | grep ROLLBAR_ACCESS_TOKEN >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using with Ruby / Rails

Add the following to your Gemfile:

gem 'rollbar', '~> 1.2.7'

Then from your project’s RAILS_ROOT, run:

$ bundle install
$ bundle exec rails generate rollbar

To make sure things are working, run:

$ bundle exec rake rollbar:test

That’s all you need for the basics: uncaught exceptions (anything that would display an error page) will now be reported to Rollbar. Access the Rollbar interface via the link on the Addons page in heroku.

Additional configuration options are available and can be set in config/initializers/rollbar.rb (which was generated by rails generate rollbar).

If not using Rails

Be sure to initialize Rollbar somewhere during startup:

Rollbar.configure do |config|
  config.access_token = ENV['ROLLBAR_ACCESS_TOKEN']
  # other configuration settings
  # ...
end

Manually reporting exceptions and messages

Uncaught exceptions are reported automatically. To report caught exceptions or other messages, you can use one of Rollbar.log(level, ...), Rollbar.debug(), Rollbar.info(), Rollbar.warning(), Rollbar.error() and Rollbar.critical() to report exceptions and messages.

The methods take in any number of arguments, but the last exception is used as the reported exception, the last string is used as the message/description, and the last hash is used as the extra data.

For example:

begin
  result = user_info[:key1][:key2][:key3]
rescue NoMethodError => e
  # simple exception report (level can be 'debug', 'info', 'warning', 'error' and 'critical')
  Rollbar.log('error', e)

  # same functionality as above
  Rollbar.error(e)

  # with a description
  Rollbar.error(e, 'The user info hash doesn\'t contain the correct data')

  # with extra data giving more insight about the exception
  Rollbar.error(e, :user_info => user_info, :job_id => job_id)
end

You can also log individual messages:

Rollbar.warning('Unexpected input')

# can also include extra data
Rollbar.info("Login successful", :username => @username)

Rollbar.log('debug', 'Settings saved', :account_id => account.id)

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

Advanced usage

You can use Rollbar.scope() to copy a notifier instance and customize the payload data for one-off reporting. The hash argument to scope() will be merged into the copied notifier’s “payload options”, a hash that will be merged into the final payload just before it is reported to Rollbar.

For example:

while job
  user = job.user

  # Overwrites any existing person data
  notifier = Rollbar.scope({
    :person => {:id => user.id, :username => user.username, :email => user.email}
  })

  begin
    job.do_work
  rescue => e
    # Sends a report with the above person data
    notifier.critical(e)
  end

  job = next_job
end

# Wipe person data
notifier = notifier.scope({
  :person => nil
})

# No associated person data
notifier.info('Jobs processed')

If you don’t want to work with a new Notifier instance #scoped will do it for you:

while job
  user = job.user

  # Overwrites any existing person data
  scope = {
    :person => {:id => user.id, :username => user.username, :email => user.email}
  }

  Rollbar.scoped(scope) do
    begin
      job.do_work
    rescue => e
      # Sends a report with the above person data
      Rollbar.critical(e)
    end
  end

  job = next_job
end

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.

This will happen automatically for uncaught Rails exceptions and for any manual exception or log reporting done within a Rails request.

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

Rollbar.configure do |config|
  config.person_method = "my_current_user"
end

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:

Rollbar.configure do |config|
  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"
end

Special note about reporting within a request

The gem instantiates one Notifier instance on initialization, which will be the base notifier that is used for all reporting (via a method_missing proxy in the Rollbar module). Calling Rollbar.configure() will configure this base notifier that will be used globally in a ruby app.

However, the Rails middleware will actually scope this base notifier for use within a request by storing it in thread-local storage (see here). This is done to make any manual logging within a request automatically contain request and person data. Calling Rollbar.configure() therefore will only affect the notifier for the duration of the request, and not the base notifier used globally.

Data sanitization (scrubbing)

By default, the notifier will “scrub” the following fields from payloads before sending to Rollbar

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

And the following http header

  • "Authorization"

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]

And Rollbar.configuration.scrub_headers:

# scrub out the "X-Access-Token" http header
Rollbar.configuration.scrub_headers |= ["X-Access-Token"]

Including additional runtime data

You can provide a callable 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 uncaught exceptions 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
}

Delayed::Job integration

If delayed_job is defined, Rollbar will automatically install a plugin that reports any uncaught exceptions that occur in jobs.

By default, the job’s data will be included in the report. If you want to disable this functionality to prevent sensitive data from possibly being sent, use the following configuration option:

config.report_dj_data = false # default is true

You can also change the threshold of job retries that must occur before a job is reported to Rollbar:

config.dj_threshold = 2 # default is 0

If you use custom jobs that define their own hooks to report exceptions, please consider disabling our plugin. Not doing so will result in duplicate exceptions being reported as well as lack of control when exceptions should be reported. To disable our Delayed::Job plugin, add the following line after the Rollbar.configure block.

config.delayed_job_enabled = false

Asynchronous reporting

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

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 sucker_punch

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

config.use_sucker_punch

Using Sidekiq

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

config.use_sidekiq

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 Resque

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

config.use_resque

You can also supply a custom Resque queue:

config.use_resque :queue => 'my_queue'

Now you can just start a new Resque worker processing jobs in that queue:

$ QUEUE=my_queue bundle exec resque:work

Using threading

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

config.use_thread

Using another handler

You can supply your own handler using config.async_handler. The object to set for async_handler should respond to #call and receive the payload. 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.use_async
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.

Failover handlers

If you are using async_handler to process asynchronous the error it’s possible that the handler fails before it calls Rollbar.process_payload. For example, for the Resque handler, the Redis connection could fail so the job is finally not processed.

To ensure that the error is sent you can define a chain of failover handlers that Rollbar will use to send the payload in case that the primary handler fails. The failover handlers, as for async_handler, are just objects responding to #call.

To configure the failover handlers you can add the following:

config.use_resque
config.failover_handlers = [Rollbar::Delay::GirlFriday, Rollbar::Delay::Thread]

With the configuration above Resque will be your primary asynchronous handler but if it fails queueing the job Rollbar will use GirlFriday at first, and just a thread in case that GirlFriday fails too.

Using with PHP

Add rollbar/rollbar to your composer.json:

{
    "require": {
        "rollbar/rollbar": "~0.12.0"
    }
}

In your application initialization (i.e. index.php), add the following:

<?php
Rollbar::init(array(
    'environment' => 'production'
));

That’s all you need for the basics: uncaught exceptions and PHP errors (E_NOTICE and higher) will be automatically reported to Rollbar. Access the Rollbar interface with:

heroku addons:open rollbar

Manually reporting exceptions and messages

<?php
// Default level is 'error'
Rollbar::report_message("Job failed");

// Custom level and extra context data
Rollbar::report_message("Job failed, retrying", "warning", array("job_id" => $job_id));

// Report a caught exception with stack trace
try {
    foo();
catch (Exception $e) {
    Rollbar::report_exception($e);
}

Dashboard

For more information on the features available within the Rollbar dashboard please see the docs at rollbar.com/features.

The dashboard can be accessed via the CLI:

$ heroku addons:open rollbar

or by visiting the Heroku apps web interface and selecting the application in question. Select Rollbar from the Add-ons menu.

Migrating between plans

Use the heroku addons:upgrade command to choose a new plan. This is a downtime-free operation.

$ heroku addons:upgrade rollbar:hobby
-----> Upgrading rollbar:small to sharp-mountain-4005... done, v18 ($12.00/mo)
       Your plan has been updated to: rollbar:hobby

Removing the add-on

Rollbar can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy rollbar
-----> Removing rollbar from sharp-mountain-4005... done, v20 (free)

Before removing Rollbar, a data export can be performed by contacting support@rollbar.com.

Support

All Rollbar support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at team@rollbar.com.