Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 228 lines (157 sloc) 8.007 kB
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
1 = HoptoadNotifier
34a3106 Added hoptoad_notifier
jyurek authored
2
19e1cfe documentation changes
mjankowski authored
3 This is the notifier plugin for integrating apps with Hoptoad.
4
8394e20 update to docs
mjankowski authored
5 When an uncaught exception occurs, HoptoadNotifier will POST the relevant data
6 to the Hoptoad server specified in your environment.
19e1cfe documentation changes
mjankowski authored
7
ed12d59 @croaky adding mailing list, IRC links
croaky authored
8 == Help
9
10 * {IRC}[irc://irc.freenode.net/thoughtbot]
11 * {mailing list}[http://groups.google.com/group/hoptoad-notifier-dev]
12
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
13 == Installation
cee2e9b @jyurek Updated the README and INSTALL to inform people to remove ExceptionNo…
jyurek authored
14
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
15 === Remove exception_notifier
cee2e9b @jyurek Updated the README and INSTALL to inform people to remove ExceptionNo…
jyurek authored
16
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
17 in your ApplicationController, REMOVE this line:
cee2e9b @jyurek Updated the README and INSTALL to inform people to remove ExceptionNo…
jyurek authored
18
19 include ExceptionNotifiable
20
21 In your config/environment* files, remove all references to ExceptionNotifier
22
23 Remove the vendor/plugins/exception_notifier directory.
24
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
25 === Install hoptoad_notifier
8394e20 update to docs
mjankowski authored
26
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
27 from your project's RAILS_ROOT, run:
8394e20 update to docs
mjankowski authored
28
bf10c56 @mjankowski doc update to force update
mjankowski authored
29 script/plugin install -f git://github.com/thoughtbot/hoptoad_notifier.git
8394e20 update to docs
mjankowski authored
30
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
31 === Configuration
8394e20 update to docs
mjankowski authored
32
6c000e7 @jyurek Added INSTALL to display config info when the plugin is installed.
jyurek authored
33 You should have something like this in config/initializers/hoptoad.rb.
34a3106 Added hoptoad_notifier
jyurek authored
34
ece0105 Updated README to have the right config example.
jyurek authored
35 HoptoadNotifier.configure do |config|
425dcf5 @jyurek README/INSTALL changes to tighten things up.
jyurek authored
36 config.api_key = '1234567890abcdef'
ece0105 Updated README to have the right config example.
jyurek authored
37 end
6a12bbe @qrush Auto-including the Catcher into ApplicationController::Base, updated …
qrush authored
38
a11bd68 @jyurek More README work, to take out references to pre-Rails 2 and to take o…
jyurek authored
39 (Please note that this configuration should be in a global configuration, and
6a12bbe @qrush Auto-including the Catcher into ApplicationController::Base, updated …
qrush authored
40 is *not* environment-specific. Hoptoad is smart enough to know what errors are
a11bd68 @jyurek More README work, to take out references to pre-Rails 2 and to take o…
jyurek authored
41 caused by what environments, so your staging errors don't get mixed in with
42 your production errors.)
43
6df61b3 @mike-burns From http://help.hoptoadapp.com/discussions/suggestions/94 - mention …
mike-burns authored
44 After adding to your config/initializers like this you must restart your
45 server. This will not affect the rake task but it bears stating.
46
6a12bbe @qrush Auto-including the Catcher into ApplicationController::Base, updated …
qrush authored
47 That should be it! Now all exceptions will be logged to Hoptoad where they can
48 be aggregated, filtered, sorted, analyzed, massaged, and searched. In previous
49 releases you had to include HoptoadNotifier::Catcher into your
50 ApplicationController, but the plugin takes care of that now.
19e1cfe documentation changes
mjankowski authored
51
300ef18 minor doc updates
Chad Pytel authored
52 You can test that Hoptoad is working in your production environment by using
8394e20 update to docs
mjankowski authored
53 this rake task (from RAILS_ROOT):
24db748 documentation
tsaleh authored
54
a11bd68 @jyurek More README work, to take out references to pre-Rails 2 and to take o…
jyurek authored
55 rake hoptoad:test
24db748 documentation
tsaleh authored
56
300ef18 minor doc updates
Chad Pytel authored
57 If everything is configured properly, that task will send a notice to Hoptoad
a11bd68 @jyurek More README work, to take out references to pre-Rails 2 and to take o…
jyurek authored
58 which will be visible immediately.
8394e20 update to docs
mjankowski authored
59
300ef18 minor doc updates
Chad Pytel authored
60 === NOTE FOR RAILS 1.2.* USERS:
61
62 You will need to copy the hoptoad_notifier_tasks.rake file into your
63 RAILS_ROOT/lib/tasks directory in order for the rake hoptoad:test task to work.
64
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
65 == Usage
8394e20 update to docs
mjankowski authored
66
300ef18 minor doc updates
Chad Pytel authored
67 for the most part, Hoptoad works for itself. Once you've included the notifier
9f46de7 @qrush Removing application_controller requirement and updating the docs
qrush authored
68 in your ApplicationController (which is now done automatically by the plugin),
69 all errors will be rescued by the #rescue_action_in_public provided by the plugin.
8394e20 update to docs
mjankowski authored
70
71 If you want to log arbitrary things which you've rescued yourself from a
72 controller, you can do something like this:
73
1145705 Added ability to whitelist exceptions from being sent to the Hoptoad …
emill authored
74 ...
75 rescue => ex
a4a44fc README updates for correct syntax
jyurek authored
76 notify_hoptoad(ex)
1145705 Added ability to whitelist exceptions from being sent to the Hoptoad …
emill authored
77 flash[:failure] = 'Encryptions could not be rerouted, try again.'
78 end
79 ...
8394e20 update to docs
mjankowski authored
80
300ef18 minor doc updates
Chad Pytel authored
81 The #notify_hoptoad call will send the notice over to Hoptoad for later analysis. While in your controllers you use the notify_hoptoad method, anywhere else in your code, use HoptoadNotifier.notify.
8394e20 update to docs
mjankowski authored
82
5813f5d added documentation for controller custom error processing
Jared Carroll authored
83 To perform custom error processing after Hoptoad has been notified, define the instance method #rescue_action_in_public_without_hoptoad(exception) in your controller.
84
300ef18 minor doc updates
Chad Pytel authored
85 == Tracking deployments in Hoptoad
0babd4f deploy tracking documentation
Chad Pytel authored
86
300ef18 minor doc updates
Chad Pytel authored
87 Paying Hoptoad plans support the ability to track deployments of your application in Hoptoad.
85945ed @webmat Fix typo
webmat authored
88 By notifying Hoptoad of your application deployments, all errors are resolved when a deploy occurs,
0babd4f deploy tracking documentation
Chad Pytel authored
89 so that you'll be notified again about any errors that reoccur after a deployment.
90
91 Additionally, it's possible to review the errors in Hoptoad that occurred before and after a deploy.
92
93 When Hoptoad is installed as a plugin this functionality is loaded automatically (if you have Capistrano version 2.0.0 or greater).
94
300ef18 minor doc updates
Chad Pytel authored
95 When Hoptoad is installed as a gem, you need to add
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
96
0babd4f deploy tracking documentation
Chad Pytel authored
97 require 'hoptoad_notifier/recipes/hoptoad'
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
98
0babd4f deploy tracking documentation
Chad Pytel authored
99 to your deploy.rb
100
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
101 == Going beyond exceptions
99b34a2 @croaky adding GOING BEYOND EXCEPTIONS section, courtesy of Eugene Bolshakov
croaky authored
102
103 You can also pass a hash to notify_hoptoad method and store whatever you want, not just an exception. And you can also use it anywhere, not just in controllers:
104
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
105 begin
106 params = {
eb8db44 @croaky integrating feedback from Eugene
croaky authored
107 # params that you pass to a method that can throw an exception
108 }
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
109 my_unpredicable_method(params)
99b34a2 @croaky adding GOING BEYOND EXCEPTIONS section, courtesy of Eugene Bolshakov
croaky authored
110 rescue => e
111 HoptoadNotifier.notify(
8d69e4a Updated notifier documentation on manually sending notifications
Joe Ferris authored
112 :error_class => "Special Error",
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
113 :error_message => "Special Error: #{e.message}",
8d69e4a Updated notifier documentation on manually sending notifications
Joe Ferris authored
114 :parameters => params
99b34a2 @croaky adding GOING BEYOND EXCEPTIONS section, courtesy of Eugene Bolshakov
croaky authored
115 )
116 end
117
118 While in your controllers you use the notify_hoptoad method, anywhere else in your code, use HoptoadNotifier.notify. Hoptoad will get all the information about the error itself. As for a hash, these are the keys you should pass:
119
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
120 * :error_class – Use this to group similar errors together. When Hoptoad catches an exception it sends the class name of that exception object.
121 * :error_message – This is the title of the error you see in the errors list. For exceptions it is "#{exception.class.name}: #{exception.message}"
8d69e4a Updated notifier documentation on manually sending notifications
Joe Ferris authored
122 * :parameters – While there are several ways to send additional data to Hoptoad, passing a Hash as :parameters as in the example above is the most common use case. When Hoptoad catches an exception in a controller, the actual HTTP client request parameters are sent using this key.
99b34a2 @croaky adding GOING BEYOND EXCEPTIONS section, courtesy of Eugene Bolshakov
croaky authored
123
124 Hoptoad merges the hash you pass with these default options:
125
8d69e4a Updated notifier documentation on manually sending notifications
Joe Ferris authored
126 {
127 :api_key => HoptoadNotifier.api_key,
128 :error_message => 'Notification',
129 :backtrace => caller,
130 :parameters => {},
131 :session => {}
132 }
99b34a2 @croaky adding GOING BEYOND EXCEPTIONS section, courtesy of Eugene Bolshakov
croaky authored
133
134 You can override any of those parameters.
8394e20 update to docs
mjankowski authored
135
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
136 == Filtering
1145705 Added ability to whitelist exceptions from being sent to the Hoptoad …
emill authored
137
65e18b3 Updated name of #inform_hoptoad to #notify in README and formatted li…
emill authored
138 You can specify a whitelist of errors, that Hoptoad will not report on. Use
139 this feature when you are so apathetic to certain errors that you don't want
3646726 @jyurek More README/INSTALL fixes.
jyurek authored
140 them even logged.
65e18b3 Updated name of #inform_hoptoad to #notify in README and formatted li…
emill authored
141
142 This filter will only be applied to automatic notifications, not manual
143 notifications (when #notify is called directly).
1145705 Added ability to whitelist exceptions from being sent to the Hoptoad …
emill authored
144
145 Hoptoad ignores the following exceptions by default:
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
146
1145705 Added ability to whitelist exceptions from being sent to the Hoptoad …
emill authored
147 ActiveRecord::RecordNotFound
a4a44fc README updates for correct syntax
jyurek authored
148 ActionController::RoutingError
d6ca96c Fixed bug related to refactoring of #ignore=, added InvalidAuthentici…
emill authored
149 ActionController::InvalidAuthenticityToken
b04d54d @qrush Adding ActionController::UnknownAction to the readme list of default …
qrush authored
150 ActionController::UnknownAction
a4a44fc README updates for correct syntax
jyurek authored
151 CGI::Session::CookieStore::TamperedWithCookie
853aa35 @croaky adding information about environment filters to the README
croaky authored
152
65e18b3 Updated name of #inform_hoptoad to #notify in README and formatted li…
emill authored
153 To ignore errors in addition to those, specify their names in your Hoptoad
154 configuration block.
1145705 Added ability to whitelist exceptions from being sent to the Hoptoad …
emill authored
155
156 HoptoadNotifier.configure do |config|
a6f405b Changed project_name to api_key
jyurek authored
157 config.api_key = '1234567890abcdef'
a4a44fc README updates for correct syntax
jyurek authored
158 config.ignore << ActiveRecord::IgnoreThisError
1145705 Added ability to whitelist exceptions from being sent to the Hoptoad …
emill authored
159 end
160
65e18b3 Updated name of #inform_hoptoad to #notify in README and formatted li…
emill authored
161 To ignore *only* certain errors (and override the defaults), use the
162 #ignore_only attribute.
1145705 Added ability to whitelist exceptions from being sent to the Hoptoad …
emill authored
163
164 HoptoadNotifier.configure do |config|
a6f405b Changed project_name to api_key
jyurek authored
165 config.api_key = '1234567890abcdef'
a4a44fc README updates for correct syntax
jyurek authored
166 config.ignore_only = [ActiveRecord::IgnoreThisError]
1145705 Added ability to whitelist exceptions from being sent to the Hoptoad …
emill authored
167 end
168
2e08e44 @qrush Adding in ignore_user_agent, patch contributed by phillip on tender.
qrush authored
169 To ignore certain user agents, add in the #ignore_user_agent attribute as a
170 string or regexp:
171
172 HoptoadNotifier.configure do |config|
173 config.api_key = '1234567890abcdef'
174 config.ignore_user_agent << /Ignored/
175 config.ignore_user_agent << 'IgnoredUserAgent'
176 end
177
05199de @qrush Merging in Kevin Menard's ignore_by_filter patch and updating README …
qrush authored
178 To ignore exceptions based on other conditions, use #ignore_by_filter:
179
180 HoptoadNotifier.configure do |config|
181 config.api_key = '1234567890abcdef'
182 config.ignore_by_filter do |exception_data|
183 true if exception_data[:error_class] == "RuntimeError"
184 end
185 end
186
300ef18 minor doc updates
Chad Pytel authored
187 To replace sensitive information sent to the Hoptoad service with [FILTERED] use #params_filters:
853aa35 @croaky adding information about environment filters to the README
croaky authored
188
189 HoptoadNotifier.configure do |config|
190 config.api_key = '1234567890abcdef'
7be8dce @qrush Adding information about filtering out custom params to the readme
qrush authored
191 config.params_filters << "credit_card_number"
853aa35 @croaky adding information about environment filters to the README
croaky authored
192 end
193
1ff0714 Updated the readme
Joe Ferris authored
194 Note that, when rescuing exceptions within an ActionController method,
195 hoptoad_notifier will reuse filters specified by #filter_params_logging.
196
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
197 == Testing
8394e20 update to docs
mjankowski authored
198
300ef18 minor doc updates
Chad Pytel authored
199 When you run your tests, you might notice that the Hoptoad service is recording
65e18b3 Updated name of #inform_hoptoad to #notify in README and formatted li…
emill authored
200 notices generated using #notify when you don't expect it to. You can
8394e20 update to docs
mjankowski authored
201 use code like this in your test_helper.rb to redefine that method so those
202 errors are not reported while running tests.
203
65e18b3 Updated name of #inform_hoptoad to #notify in README and formatted li…
emill authored
204 module HoptoadNotifier::Catcher
205 def notify(thing)
206 # do nothing.
207 end
208 end
99b34a2 @croaky adding GOING BEYOND EXCEPTIONS section, courtesy of Eugene Bolshakov
croaky authored
209
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
210 == Supported rails versions
ab991c8 @qrush Updating README with supported versions of Rails
qrush authored
211
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
212 the notifier currently supports the following versions of Rails:
ab991c8 @qrush Updating README with supported versions of Rails
qrush authored
213
214 * 1.2.6
215 * 2.0.2
f07d056 @jasonm Support Rails 2.1.0
jasonm authored
216 * 2.1.0
ab991c8 @qrush Updating README with supported versions of Rails
qrush authored
217 * 2.1.2
218 * 2.2.2
219 * 2.3.2
3963e93 @joshuaclayton Add version 2.3.3 to the list of supported versions of Rails
joshuaclayton authored
220 * 2.3.3
e24ffbe @croaky Rails 2.3.4 is supported. Rails 2.3.3 is not.
croaky authored
221 * 2.3.4
ab991c8 @qrush Updating README with supported versions of Rails
qrush authored
222
223 Please open up a support ticket on Tender ( http://help.hoptoadapp.com ) if you're using a version of Rails that is not listed above and the notifier is not working properly.
224
c4e26cb @qrush Starting YARD'ing up the plugin
qrush authored
225 == Thanks
99b34a2 @croaky adding GOING BEYOND EXCEPTIONS section, courtesy of Eugene Bolshakov
croaky authored
226
227 Thanks to Eugene Bolshakov for the excellent write-up on GOING BEYOND EXCEPTIONS, which we have included above.
Something went wrong with that request. Please try again.