Exception Notifier Plugin for Rails¶ ↑

The Exception Notifier plugin provides a mailer object and a default set of templates for sending email notifications when errors occur in a Rails application. The plugin is configurable, allowing programmers to specify:

• the sender address of the email

• the recipient addresses

• the text used to prefix the subject line

The email includes information about the current request, session, and environment, and also gives a backtrace of the exception.

About this fork¶ ↑

This fork, apart from some other minor tweaks, adds another notifier which allows you to deliver any exception from any Ruby object by calling ‘report_exception(err)`:

class Foo
  def bar
    raise "something went wrong"
  rescue => err
    report_exception(err)
    raise err
  end
end

You can also specify additional sections via the optional second argument, which is expected to be a hash in the format ‘“Section title” => “Additonal data as a string”. Those will be included in the mail below the stacktrace.

Usage¶ ↑

First, include the ExceptionNotifiable mixin in whichever controller you want to generate error emails (typically ApplicationController):

class ApplicationController < ActionController::Base
  include ExceptionNotification::Notifiable
  ...
end

Then, specify the email recipients in your environment:

ExceptionNotification::Notifier.exception_recipients = %w([email protected] [email protected])

And that’s it! The defaults take care of the rest.

Configuration¶ ↑

You can tweak other values to your liking, as well. In your environment file, just set any or all of the following values:

# defaults to [email protected]
ExceptionNotification::Notifier.sender_address =
  %("Application Error" <[email protected]>)

# defaults to "[ERROR] "
ExceptionNotification::Notifier.email_prefix = "[APP] "

Even if you have mixed into ApplicationController you can skip notification in some controllers by

class MyController  < ApplicationController
  skip_exception_notifications
end

Deprecated local_request? overriding¶ ↑

Email notifications will only occur when the IP address is determined not to be local. You can specify certain addresses to always be local so that you’ll get a detailed error instead of the generic error page. You do this in your controller (or even per-controller):

consider_local "64.72.18.143", "14.17.21.25"

You can specify subnet masks as well, so that all matching addresses are considered local:

consider_local "64.72.18.143/24"

The address “127.0.0.1” is always considered local. If you want to completely reset the list of all addresses (for instance, if you wanted “127.0.0.1” to NOT be considered local), you can simply do, somewhere in your controller:

local_addresses.clear

NOTE: The above functionality has has been pulled out to consider_local.rb, as interfering with rails local determination is orthogonal to notification, unnecessarily clutters backtraces, and even occasionally errs on odd ip or requests bugs. To return original functionality add an initializer with:

ActionController::Base.send :include, ConsiderLocal

or just include it per controller that wants it

class MyController  < ApplicationController
  include ExceptionNotification::ConsiderLocal
end

Customization¶ ↑

By default, the notification email includes four parts: request, session, environment, and backtrace (in that order). You can customize how each of those sections are rendered by placing a partial named for that part in your app/views/exception_notifier directory (e.g., _session.rhtml). Each partial has access to the following variables:

• @controller: the controller that caused the error

• @request: the current request object

• @exception: the exception that was raised

• @host: the name of the host that made the request

• @backtrace: a sanitized version of the exception’s backtrace

• @rails_root: a sanitized version of RAILS_ROOT

• @data: a hash of optional data values that were passed to the notifier

• @sections: the array of sections to include in the email

You can reorder the sections, or exclude sections completely, by altering the ExceptionNotification::Notifier.sections variable. You can even add new sections that describe application-specific data–just add the section’s name to the list (whereever you’d like), and define the corresponding partial. Then, if your new section requires information that isn’t available by default, make sure it is made available to the email using the exception_data macro:

class ApplicationController < ActionController::Base
  ...
  protected
    exception_data :additional_data

    def additional_data
      { :document => @document,
        :person => @person }
    end
  ...
end

In the above case, @document and @person would be made available to the email renderer, allowing your new section(s) to access and display them. See the existing sections defined by the plugin for examples of how to write your own.

404s errors¶ ↑

Notification is skipped if you return a 404 status, which happens by default for an ActiveRecord::RecordNotFound or ActionController::UnknownAction error.

Manually notifying of error in a rescue block¶ ↑

If your controller action manually handles an error, the notifier will never be run. To manually notify of an error call notify_about_exception from within the rescue block

def index
  #risky operation here
rescue StandardError => error
  #custom error handling here
  notify_about_exception(error)
end

Support and tickets¶ ↑

rails.lighthouseapp.com/projects/8995-rails-plugins

Copyright © 2005 Jamis Buck, released under the MIT license