Hoptoad Notifier Plugin

This is the notifier plugin for integrating apps with Hoptoad. It can be used with Rails applications using a simple controller mixin or as a standalone interface to the Hoptoad API.

Rails Integration

This is the simplest form of integration. When an uncaught exception occurs, the relevant data will be POSTed to the Hoptoad server specified in your environment.

From your project’s RAILS_ROOT, run:

script/plugin install git://github.com/thoughtbot/hoptoad_notifier.git

Configuration

You should have something like this in config/initializers/hoptoad.rb.

Hoptoad.configure do |config| config.api_key = ‘1234567890abcdef’ end

Please note that this configuration should be in a global configuration, and is not enrivonment-specific. Hoptoad is smart enough to know what errors are
caused by what environments, so your staging errors don’t get mixed in with your production errors.

Then, to enable hoptoad in your appication, simply include the controller mixin somewhere in your ApplicationController:

include Hoptoad::Catcher

All exceptions will be logged to Hoptoad where they can be aggregated, filtered, sorted, analyzed, massaged, and searched.

Testing the plugin is installed correctly

NOTE FOR RAILS 1.2.x USERS: You will need to copy the hoptoad_notifier_tasks.rake file into yourRAILS_ROOT/lib/tasks directory in order for the following to work.

You can test that hoptoad is working in your production environment by using this rake task (from RAILS_ROOT):

rake hoptoad:test

If everything is configured properly, that task will send a notice to hoptoad which will be visible immediately.

Manually sending exceptions to Hoptoad

For the most part, hoptoad works for itself. Once you’ve included the notifier in your ApplicationController, all errors will be rescued by the
#rescue_action_in_public provided by the plugin.

If you want to log arbitrary things which you’ve rescued yourself from a controller, you can do something like this:

… rescue => ex notify_hoptoad(ex) flash[:failure] = ‘Encryptions could not be rerouted, try again.’ end …

The #notify_hoptoad call will send the notice over to hoptoad for later analysis.

Standalone usage

The plugin provides a standlone notifier object that can be used to send exception data to Hoptoad outside of a Rails request. To use this, first require the Hoptoad standalone library and configure as usual (this assumes the Hoptoad plugin lib folder is in your load path):

require ‘hoptoad/standalone’ Hoptoad.configure do |config| config.api_key = ‘1234567890abcdef’ config.logger = my_custom_logger end

Then create the notifier instance:

notifier = Hoptoad::Notifier.from_config(Hoptoad)

To send exceptions to Hoptoad, call the #notify method. This can be used in two ways:

Using objects:

notifier.notify(exception, request, session, environment)

Using a hash:

notifier.notify({:error_message => “Some error”})

For a full list of parameters when using the hash format, see the documentation for Hoptoad::Notice#new.

Ignoring specific exceptions

You can specify a whitelist of errors, that Hoptoad will not report on. Use this feature when you are so apathetic to certain errors that you don’t want them even logged.

This filter will only be applied to automatic notifications (using Rails integration mode), not manual notifications (when #notify_hoptoad_ is called directly or using the standalone library).

Hoptoad ignores the following exceptions by default:

• ActiveRecord::RecordNotFound
• ActionController::RoutingError
• ActionController::InvalidAuthenticityToken
• CGI::Session::CookieStore::TamperedWithCookie

To ignore errors in addition to those, specify their names in your Hoptoad configuration block.

Hoptoad.configure do |config| config.api_key = ‘1234567890abcdef’ config.ignore << ActiveRecord::IgnoreThisError end

To ignore only certain errors (and override the defaults), use the #ignore_only attribute.

Hoptoad.configure do |config| config.api_key = ‘1234567890abcdef’ config.ignore_only = [ActiveRecord::IgnoreThisError] end

Filtering

You can also filter out data from the params hash and the backtrace before sending an exception to Hoptoad. This works in the Rails integration or standalone mode.

To filter backtraces:

Hoptoad.config.filter_backtrace do |line| line.gsub(/some private value/, ‘[DO NOT SHOW]’) end

To filter parameters:

Hoptoad.config.filter_params << “my_secret_param”

The Hoptoad plugin will filter out password parameters (and password confirmations) by default.

Testing

When you run your tests, you might notice that the hoptoad service is recording notices generated using #notify when you don’t expect it to. You can use code like this in your test_helper.rb to redefine that method so those errors are not reported while running tests.

module Hoptoad::Catcher def notify_hoptoad(thing)

1. do nothing.
   end
   end