rails / exception_notification
watch download tarball
public
Forks68Right
Watchers556Right
Description: Exception Notifier Plugin for Rails
Homepage: http://rubyonrails.org
Clone URL: git://github.com/rails/exception_notification.git
raw normal view history
da054069 » dhh 2005-10-29 Added ExceptionNotification... 1 = Exception Notifier Plugin for Rails
2
3 The Exception Notifier plugin provides a mailer object and a default set of
4 templates for sending email notifications when errors occur in a Rails
5 application. The plugin is configurable, allowing programmers to specify:
6
7 * the sender address of the email
8 * the recipient addresses
9 * the text used to prefix the subject line
10
11 The email includes information about the current request, session, and
12 environment, and also gives a backtrace of the exception.
13
14 == Usage
15
16 First, include the ExceptionNotifiable mixin in whichever controller you want
17 to generate error emails (typically ApplicationController):
18
19 class ApplicationController < ActionController::Base
20 include ExceptionNotifiable
21 ...
22 end
23
24 Then, specify the email recipients in your environment:
25
26 ExceptionNotifier.exception_recipients = %w(joe@schmoe.com bill@schmoe.com)
27
28 And that's it! The defaults take care of the rest.
29
30 == Configuration
31
32 You can tweak other values to your liking, as well. In your environment file,
33 just set any or all of the following values:
34
35 # defaults to exception.notifier@default.com
36 ExceptionNotifier.sender_address =
37 %("Application Error" <app.error@myapp.com>)
38
39 # defaults to "[ERROR] "
40 ExceptionNotifier.email_prefix = "[APP] "
41
f1d0ce12 » jamis 2005-10-29 Correct error in documentation 42 Email notifications will only occur when the IP address is determined not to
43 be local. You can specify certain addresses to always be local so that you'll
44 get a detailed error instead of the generic error page. You do this in your
da054069 » dhh 2005-10-29 Added ExceptionNotification... 45 controller (or even per-controller):
46
47 consider_local "64.72.18.143", "14.17.21.25"
48
49 You can specify subnet masks as well, so that all matching addresses are
50 considered local:
51
52 consider_local "64.72.18.143/24"
53
54 The address "127.0.0.1" is always considered local. If you want to completely
55 reset the list of all addresses (for instance, if you wanted "127.0.0.1" to
56 NOT be considered local), you can simply do, somewhere in your controller:
57
58 local_addresses.clear
59
60 == Customization
61
62 By default, the notification email includes four parts: request, session,
63 environment, and backtrace (in that order). You can customize how each of those
64 sections are rendered by placing a partial named for that part in your
65 app/views/exception_notifier directory (e.g., _session.rhtml). Each partial has
66 access to the following variables:
67
68 * @controller: the controller that caused the error
69 * @request: the current request object
70 * @exception: the exception that was raised
71 * @host: the name of the host that made the request
72 * @backtrace: a sanitized version of the exception's backtrace
73 * @rails_root: a sanitized version of RAILS_ROOT
74 * @data: a hash of optional data values that were passed to the notifier
75 * @sections: the array of sections to include in the email
76
77 You can reorder the sections, or exclude sections completely, by altering the
78 ExceptionNotifier.sections variable. You can even add new sections that
79 describe application-specific data--just add the section's name to the list
80 (whereever you'd like), and define the corresponding partial. Then, if your
81 new section requires information that isn't available by default, make sure
82 it is made available to the email using the exception_data macro:
83
84 class ApplicationController < ActionController::Base
85 ...
86 protected
87 exception_data :additional_data
88
89 def additional_data
90 { :document => @document,
91 :person => @person }
92 end
93 ...
94 end
95
96 In the above case, @document and @person would be made available to the email
97 renderer, allowing your new section(s) to access and display them. See the
98 existing sections defined by the plugin for examples of how to write your own.
99
100 == Advanced Customization
101
102 By default, the email notifier will only notify on critical errors. For
103 ActiveRecord::RecordNotFound and ActionController::UnknownAction, it will
104 simply render the contents of your public/404.html file. Other exceptions
105 will render public/500.html and will send the email notification. If you want
106 to use different rules for the notification, you will need to implement your
107 own rescue_action_in_public method. You can look at the default implementation
108 in ExceptionNotifiable for an example of how to go about that.
109
110
111 Copyright (c) 2005 Jamis Buck, released under the MIT license