Configuration

(Please note that this configuration should be in a global configuration,
and is not environment-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.)

After adding to your config/initializers like this you must restart your
server. This will not affect the rake task but it bears stating.

That should be it! Now all exceptions will be logged to Hoptoad where they
can be aggregated, filtered, sorted, analyzed, massaged, and searched. In
previous releases you had to include HoptoadNotifier::Catcher into your
ApplicationController, but the plugin takes care of that now.

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.

NOTE FOR RAILS 1.2.* USERS:

You will need to copy the hoptoad_notifier_tasks.rake file into your
RAILS_ROOT/lib/tasks directory in order for the rake hoptoad:test task to
work.

Usage

for the most part, Hoptoad works for itself. Once you've included the
notifier in your ApplicationController (which is now done automatically by
the plugin), 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:

The #notify_hoptoad call will send the notice over to Hoptoad for later
analysis. While in your controllers you use the notify_hoptoad method,
anywhere else in your code, use HoptoadNotifier.notify.

To perform custom error processing after Hoptoad has been notified, define
the instance method #rescue_action_in_public_without_hoptoad(exception) in
your controller.

Tracking deployments in Hoptoad

Paying Hoptoad plans support the ability to track deployments of your
application in Hoptoad. By notifying Hoptoad of your application
deployments, all errors are resolved when a deploy occurs, so that
you'll be notified again about any errors that reoccur after a
deployment.

Additionally, it's possible to review the errors in Hoptoad that
occurred before and after a deploy.

When Hoptoad is installed as a plugin this functionality is loaded
automatically (if you have Capistrano version 2.0.0 or greater).

When Hoptoad is installed as a gem, you need to add

require 'hoptoad_notifier/recipes/hoptoad'

to your deploy.rb

Going beyond exceptions

You can also pass a hash to notify_hoptoad method and store whatever you
want, not just an exception. And you can also use it anywhere, not just in
controllers:

While in your controllers you use the notify_hoptoad method, anywhere else
in your code, use HoptoadNotifier.notify. Hoptoad will get all the
information about the error itself. As for a hash, these are the keys you
should pass:

:error_class – Use this to group similar errors together. When Hoptoad
catches an exception it sends the class name of that exception object.

:error_message – This is the title of the error you see in the errors list.
For exceptions it is “#{exception.class.name}: #{exception.message}”

:parameters – While there are several ways to send additional data to
Hoptoad, passing a Hash as :parameters as in the example above is the most
common use case. When Hoptoad catches an exception in a controller, the
actual HTTP client request parameters are sent using this key.

Note that, when rescuing exceptions within an ActionController method,
hoptoad_notifier will reuse filters specified by #filter_params_logging.

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 HoptoadNotifier::Catcher
def notify(thing)
# do nothing.
end
end

Supported rails versions

the notifier currently supports the following versions of Rails:

1.2.6

2.0.2

2.1.0

2.1.2

2.2.2

2.3.2

2.3.3

2.3.4

Please open up a support ticket on Tender ( help.hoptoadapp.com ) if you're
using a version of Rails that is not listed above and the notifier is not
working properly.

Thanks

Thanks to Eugene Bolshakov for the excellent write-up on GOING BEYOND
EXCEPTIONS, which we have included above.