Skip to content

Latest commit

 

History

History
221 lines (154 loc) · 7.06 KB

README.rdoc

File metadata and controls

221 lines (154 loc) · 7.06 KB
Raw

HoptoadNotifier ↑

This is the notifier gem for integrating apps with Hoptoad.

When an uncaught exception occurs, HoptoadNotifier will POST the relevant data to the Hoptoad server specified in your environment.

Help ↑

Installation ↑

Remove exception_notifier ↑

in your ApplicationController, REMOVE this line:

include ExceptionNotifiable

In your config/environment* files, remove all references to ExceptionNotifier

Remove the vendor/plugins/exception_notifier directory.

Rails 2.x ↑

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

config.gem 'hoptoad_notifier'

Then from your project’s RAILS_ROOT, run:

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

Rails 1.2.6 ↑

Install the hoptoad_notifier Gem, and then add something like this at the bottom of your config/environment.rb:

HoptoadNotifier.configure do |config|
  config.api_key = 'your_key_here'
end

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.

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.

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:

...
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. 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/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:

begin
  params = {
    # params that you pass to a method that can throw an exception
  }
  my_unpredicable_method(params)
rescue => e
  HoptoadNotifier.notify(
    :error_class   => "Special Error",
    :error_message => "Special Error: #{e.message}",
    :parameters    => params
  )
end

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.

Hoptoad merges the hash you pass with these default options:

{
  :api_key       => HoptoadNotifier.api_key,
  :error_message => 'Notification',
  :backtrace     => caller,
  :parameters    => {},
  :session       => {}
}

You can override any of those parameters.

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).

Hoptoad ignores the following exceptions by default:

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

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

HoptoadNotifier.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.

HoptoadNotifier.configure do |config|
  config.api_key      = '1234567890abcdef'
  config.ignore_only  = [ActiveRecord::IgnoreThisError]
end

To ignore certain user agents, add in the #ignore_user_agent attribute as a string or regexp:

HoptoadNotifier.configure do |config|
  config.api_key      = '1234567890abcdef'
  config.ignore_user_agent  << /Ignored/
  config.ignore_user_agent << 'IgnoredUserAgent'
end

To ignore exceptions based on other conditions, use #ignore_by_filter:

HoptoadNotifier.configure do |config|
  config.api_key      = '1234567890abcdef'
  config.ignore_by_filter do |exception_data|
    true if exception_data[:error_class] == "RuntimeError"
  end
end

To replace sensitive information sent to the Hoptoad service with [FILTERED] use #params_filters:

HoptoadNotifier.configure do |config|
  config.api_key      = '1234567890abcdef'
  config.params_filters << "credit_card_number"
end

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

Supported Rails versions ↑

See SUPPORTED_RAILS_VERSIONS for a list of official supported versions of Rails.

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.