= ErrorNotNotifier

This is the notifier gem for integrating apps with your ErrorNot application

When an uncaught exception occurs, ErrorNotNotifier will POST the relevant data
to your errorNot application server specified in your environment.

== Rails 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 3.x

Add the errornot_notifier gem to your Gemfile.  In Gemfile:

  gem 'errornot_notifier'

Then from your project's RAILS_ROOT, run:

  bundle install
  script/rails generate errornot --api-key your_key_here --server your_host

That's it!

=== Rails 2.x

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

  config.gem 'errornot_notifier'

Then from your project's RAILS_ROOT, run:

  rake gems:install
  rake gems:unpack GEM=errornot_notifier
  script/generate errornot --api-key your_key_here --server your_host

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

=== Rails 1.2.6

Install the errornot_notifier gem:

  gem install errornot_notifier

Once installed, you should vendor the errornot_notifier gem:

  mkdir vendor/gems
  cd vendor/gems
  gem unpack errornot_notifier

And then add the following to the Rails::Initializer.run do |config|
block in environment.rb so that the vendored gem is loaded.

  # Add the vendor/gems/*/lib directories to the LOAD_PATH
  config.load_paths += Dir.glob(File.join(RAILS_ROOT, 'vendor', 'gems', '*', 'lib'))

Next add something like this at the bottom of your config/environment.rb:

  require 'errornot_notifier'
  require 'errornot_notifier/rails'
  ErrornotNotifier.configure do |config|
    config.api_key = 'your_key_here'
    config.host = 'host_of_your_errornot_instance'
  end

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

  cp vendor/gems/errornot_notifier-*/generators/errornot/templates/errornot_notifier_tasks.rake lib/tasks

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

=== Testing it out

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

  rake errornot:test

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

== Rack

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

  require 'rack'
  require 'errornot_notifier'

  ErrornotNotifier.configure do |config|
    config.api_key = 'my_api_key'
    config.host = 'host_of_your_errornot_instance'
  end

  app = Rack::Builder.app do
    use errornotNotifier::Rack
    run lambda { |env| raise "Rack down" }
  end

== Sinatra

Using errornot_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 'errornot_notifier'

  ErrornotNotifier.configure do |config|
    config.api_key = 'my_api_key'
    config.host =' host_of_your_errornot_instance'
  end

  class MyApp < Sinatra::Default
    use ErrornotNotifier::Rack
    enable :raise_errors

    get "/" do
      raise "Sinatra has left the building"
    end
  end

== Usage

For the most part, ErrorNot 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_errornot(ex)
    flash[:failure] = 'Encryptions could not be rerouted, try again.'
  end
  ...

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

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

== Tracking deployments in Errornot ( It's not implement in ErrorNot )

Paying Errornot plans support the ability to track deployments of your application in Errornot.
By notifying Errornot 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 Errornot that occurred before and after a deploy.

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

  require 'errornot_notifier/capistrano'

to your deploy.rb

== Going beyond exceptions

You can also pass a hash to notify_errornot 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
    ErrornotNotifier.notify(
      :error_class   => "Special Error",
      :error_message => "Special Error: #{e.message}",
      :parameters    => params
    )
  end

While in your controllers you use the notify_errornot method, anywhere else in
your code, use ErrornotNotifier.notify. Errornot 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 Errornot 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 Errornot, passing a Hash as :parameters as in the example above is the most common use case. When Errornot catches an exception in a controller, the actual HTTP client request parameters are sent using this key.

Errornot merges the hash you pass with these default options:

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

You can override any of those parameters.

=== 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 ErrornotNotifier::Notice#initialize in lib/errornot_notifier/notice.rb for
more details.

== Filtering

You can specify a whitelist of errors, that Errornot 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).

Errornot 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 Errornot
configuration block.

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

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

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

  ErrornotNotifier.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 Errornot service with [FILTERED] use #params_filters:

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

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

== Testing

When you run your tests, you might notice that the Errornot 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 ErrornotNotifier
    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 Errornot servers.  To configure the proxy settings, added the following information to your Errornot configuration block.

ErrornotNotifier.configure do |config|
    config.proxy_host = ...
    config.proxy_port = ...
    config.proxy_user = ...
    config.proxy_pass = ...

== Supported Rails versions

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

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

== Javascript Notifer

To automatically include the Javascript node on every page, set the
:js_notifier to true:

  ErrornotNotifier.configure do |config|
    config.js_notifier = true
  end

It automatically uses the API key, host, and port specified in the
configuration.

== Thanks

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

Thanks to thoughtbot, to create this gem before we updated it to use with errornot