Whoopsie

Version: 0.0.2

A wrapper for ExceptionNotifier and TraceKit, especially suited for Rails apps.

This Rails engine was originally written by Wojtek Kruszewski.

RSpec tests, minimal documentation (below), and some cleanup by Midwire

Whoopsie wraps ExceptionNotification to handle notifications for JavaScript errors as well as back-end errors.

Installation

Add this line to your application's Gemfile:

gem 'whoopsie'

And then execute:

$ bundle

Or install it yourself as:

$ gem install whoopsie

Usage

Rails Usage

Configuration

Enable it in config/application.rb:

config.whoopsie.enable        = true
config.whoopsie.email_prefix  = '[ERROR] ' # optional
config.whoopsie.recipients    = ['me@example.com', 'you@example.com']
config.whoopsie.sender        = 'notifications@example.com'
config.ignored_exceptions += %w{ActionView::TemplateError CustomError} # optional

...or in any initializer (example: config/initializers/whoopsie.rb):

Rails.application.config.whoopsie.enable        = true
Rails.application.config.whoopsie.email_prefix  = '[ERROR] ' # optional
Rails.application.config.whoopsie.recipients    = ['me@example.com', 'you@example.com']
Rails.application.config.whoopsie.sender        = 'notifications@example.com'
Rails.application.config.ignored_exceptions += %w{ActionView::TemplateError CustomError} # optional

You can ignore certain exceptions if you don't want to be notified for them.

config.ignored_exceptions += %w{ActionView::TemplateError CustomError}

ActiveRecord::RecordNotFound, AbstractController::ActionNotFound and ActionController::RoutingError are ignored by default.

Add a condition to determine when an exception must be ignored or not. The ignore_if method can be invoked multiple times to add extra conditions.

config.ignore_if do |exception, options|
  ! Rails.application.config.whoopsie.enable
end

Additional Notifiers

The Email notifier is configured automatically when you configure Whoopsie as above.

Add additional notifiers just like you normally would for ExceptionNotification. For example, to add a Slack channel notification:

Rails.application.config.middleware.use(
  ExceptionNotification::Rack,
  :slack => {
    :webhook_url => 'YOUR_SLACK_WEBHOOK_URL_GOES_HERE',
    :channel => '#my_app_channel',
    :additional_parameters => {
      :icon_url => 'https://myapp.com/assets/logo-square.png',
      :mrkdwn => true
    }
  }
)

Usage

Exceptions will be automatically caught and notifications sent using the configured notifiers. You can also handle exceptions explicitly:

def my_method
  raise 'oh noes!'
rescue SomeError => err
  Whoopsie.handle_exception(
    err,
    data: {
      id: 'whatever',
      another_thing: 'something else',
      errors: %w(array of things)
    }
  )
end

Wrap code for protection:

Whoopsie.report_and_swallow do
  # Do something risky...
end

Javascript Usage

Require it in your JS

# assets/javascripts/application.js
//= require whoopsie

Add the config helper to your layout:

<%= whoopsie_config %>

or for HAML

= whoopsie_config

Wrap any JS that you want to be protected with TraceKit:

Whoopsie.wrap(function($){
  $(document).on('click', 'button[data-dismiss-hint]', function(event){
    alert("All is well.")
  });      
});

or wrap long methods by name:

$(document).ready(Whoopsie.wrap(myFunction));

Coffeescript Usage

TODO

Bugs

Please report any bugs or issues using GitHub Issue Tracker.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/midwire/whoopsie.

Please use feature branches and follow the Git Flow paradigm.