1+ = Exception Notifier Plugin for Rails, using Shooter
2+
3+ Shooter is a web application that allows creation of "Shooters". Each shooter
4+ can store a single payload, which can be set using a REST API. When the payload
5+ is set, the account owner is notified by email. Any further attempts to set
6+ the payload will be rejected until the current payload is "shot" away.
7+
8+ The concept is that:
9+ 1) Exceptions should never happen
10+ 2) Most of the time, only the most recent exception is of interest
11+ 3) Focus should be on clearing, or ignoring the current exception
12+
13+ The Exception Notifier plugin for Shooter provides a hook into the REST API
14+ and a default set of templates for sending notifications when errors occur in a Rails
15+ application. The plugin is configurable, allowing programmers to specify:
16+
17+ * the API key of the Shooter to notify
18+ * custom variables
19+
20+ The notification includes information about the current request, session, and
21+ environment, and also gives a backtrace of the exception.
22+
23+ == Usage
24+
25+ First, include the ExceptionNotifiable mixin in whichever controller you want
26+ to generate error emails (typically ApplicationController):
27+
28+ class ApplicationController < ActionController::Base
29+ include ExceptionNotifiable
30+ ...
31+ end
32+
33+ Then, specify your API key in your environment:
34+
35+ ExceptionNotifier.api_key = 'API_KEY'
36+
37+ And that's it! The defaults take care of the rest.
38+
39+ == Configuration
40+
41+ You can tweak other values to your liking, as well. In your environment file,
42+ just set any or all of the following values:
43+
44+ Notifications will only occur when the IP address is determined not to
45+ be local. You can specify certain addresses to always be local so that you'll
46+ get a detailed error instead of the generic error page. You do this in your
47+ controller (or even per-controller):
48+
49+ consider_local "64.72.18.143", "14.17.21.25"
50+
51+ You can specify subnet masks as well, so that all matching addresses are
52+ considered local:
53+
54+ consider_local "64.72.18.143/24"
55+
56+ The address "127.0.0.1" is always considered local. If you want to completely
57+ reset the list of all addresses (for instance, if you wanted "127.0.0.1" to
58+ NOT be considered local), you can simply do, somewhere in your controller:
59+
60+ local_addresses.clear
61+
62+ == Customization
63+
64+ By default, the notification email includes four parts: request, session,
65+ environment, and backtrace (in that order). You can customize how each of those
66+ sections are rendered by placing a partial named for that part in your
67+ app/views/exception_notifier directory (e.g., _session.rhtml). Each partial has
68+ access to the following variables:
69+
70+ * @controller: the controller that caused the error
71+ * @request: the current request object
72+ * @exception: the exception that was raised
73+ * @host: the name of the host that made the request
74+ * @backtrace: a sanitized version of the exception's backtrace
75+ * @rails_root: a sanitized version of RAILS_ROOT
76+ * @data: a hash of optional data values that were passed to the notifier
77+ * @sections: the array of sections to include in the email
78+
79+ You can reorder the sections, or exclude sections completely, by altering the
80+ ExceptionNotifier.sections variable. You can even add new sections that
81+ describe application-specific data--just add the section's name to the list
82+ (whereever you'd like), and define the corresponding partial. Then, if your
83+ new section requires information that isn't available by default, make sure
84+ it is made available to the email using the exception_data macro:
85+
86+ class ApplicationController < ActionController::Base
87+ ...
88+ protected
89+ exception_data :additional_data
90+
91+ def additional_data
92+ { :document => @document,
93+ :person => @person }
94+ end
95+ ...
96+ end
97+
98+ In the above case, @document and @person would be made available to the email
99+ renderer, allowing your new section(s) to access and display them. See the
100+ existing sections defined by the plugin for examples of how to write your own.
101+
102+ == Advanced Customization
103+
104+ By default, the email notifier will only notify on critical errors. For
105+ ActiveRecord::RecordNotFound and ActionController::UnknownAction, it will
106+ simply render the contents of your public/404.html file. Other exceptions
107+ will render public/500.html and will send the email notification. If you want
108+ to use different rules for the notification, you will need to implement your
109+ own rescue_action_in_public method. You can look at the default implementation
110+ in ExceptionNotifiable for an example of how to go about that.
111+
112+
113+ Copyright (c) 2005 Jamis Buck, released under the MIT license
0 commit comments