As always, if you choose not to vendor the hoptoad_notifier gem, make sure
every server you deploy to has the gem installed or your application
won't start.

Upgrading From Earlier Versions of Hoptoad

If you're currently using the plugin version (if you have a
vendor/plugins/hoptoad_notifier directory, you are), you'll need to
perform a few extra steps when upgrading to the gem version.

Add the hoptoad_notifier gem to your app. In config/environment.rb:

config.gem 'hoptoad_notifier'

Remove the plugin:

rm -rf vendor/plugins/hoptoad_notifier

Make sure the following line DOES NOT appear in your ApplicationController
file:

include HoptoadNotifier::Catcher

If it does, remove it. The new catcher is automatically included by the
gem version of Hoptoad.

Before running the hoptoad generator, you need to find your project's
API key. Log in to your account at hoptoadapp.com, and click on the
“Projects” button. Then, find your project in the list, and click on its
name. In the left-hand column, you'll see an “Edit this project”
button. Click on that to get your project's API. (If you accidentally
use your personal API auth_token, you won't be able to install the
gem.)

Then from your project's RAILS_ROOT, run:

rake gems:install
script/generate hoptoad --api-key your_key_here

Once installed, you should vendor the hoptoad_notifier gem.

rake gems:unpack GEM=hoptoad_notifier

As always, if you choose not to vendor the hoptoad_notifier gem, make sure
every server you deploy to has the gem installed or your application
won't start.

Upgrading from Earlier Versions of the Hoptoad Gem (with config.gem)

If you're currently using the gem version of the hoptoad_notifier and
have a version of Rails that uses config.gem (in the 2.x series), there is
a step or two that you need to do to upgrade. First, you need to remove the
old version of the gem from vendor/gems:

rm -rf vendor/gems/hoptoad_notifier-X.X.X

Then you must remove the hoptoad_notifier_tasks.rake file from lib:

rm lib/tasks/hoptoad_notifier_tasks.rake

You can them continue to install normally. If you don't remove the rake
file, you will be unable to unpack this gem (Rails will think it's part
of the framework).

Testing it out

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.

Rack

In order to use hoptoad_notifier in a non-Rails rack app, just load the
hoptoad_notifier, configure your API key, and use the HoptoadNotifier::Rack
middleware:

Sinatra

Using hoptoad_notifier in a Sinatra app is just like a Rack app, but you
have to disable Sinatra's error rescuing functionality:

require 'sinatra/base'
require 'hoptoad_notifier'
HoptoadNotifier.configure do |config|
config.api_key = 'my_api_key'
end
class MyApp < Sinatra::Default
use HoptoadNotifier::Rack
enable :raise_errors
get "/" do
raise "Sinatra has left the building"
end
end

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 gem), all errors will be rescued by the #rescue_action_in_public
provided by the gem.

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 gem, you need to add

require 'hoptoad_notifier/capistrano'

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.

Sending shell environment variables when “Going beyond exceptions”

One common request we see is to send shell environment variables along with
manual exception notification. We recommend sending them along with CGI
data or Rack environment (:cgi_data or :rack_env keys, respectively.)

See HoptoadNotifier::Notice#initialize in lib/hoptoad_notifier/notice.rb
for more details.

Filtering

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, not manual
notifications (when #notify is called directly).

Note that, when rescuing exceptions within an ActionController method,
hoptoad_notifier will reuse filters specified by #filter_parameter_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
def self.notify(thing)
# do nothing.
end
end

Proxy Support

The notifier supports using a proxy, if your server is not able to directly
reach the Hoptoad servers. To configure the proxy settings, added the
following information to your Hoptoad configuration block.