Skip to content
Newer
Older
100644 456 lines (312 sloc) 14.5 KB
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
1 HoptoadNotifier
2 ===============
3
4 This is the notifier gem for integrating apps with Hoptoad.
5
6 When an uncaught exception occurs, HoptoadNotifier will POST the relevant data
7 to the Hoptoad server specified in your environment.
8
9 Help
10 ----
11
12 For help with using Hoptoad and the Hoptoad notifier visit [our support site](http://help.hoptoadapp.com)
13
14 For discussion of Hoptoad notifier development check out the [mailing list](http://groups.google.com/group/hoptoad-notifier-dev)
15
16 Rails Installation
17 ------------------
18
19 ### Remove exception_notifier
20
21 in your ApplicationController, REMOVE this line:
22
23 include ExceptionNotifiable
24
25 In your config/environment* files, remove all references to ExceptionNotifier
26
27 Remove the vendor/plugins/exception_notifier directory.
28
29 ### Remove hoptoad_notifier plugin
30
31 Remove the vendor/plugins/hoptoad_notifier directory before installing the gem, or run:
32
33 script/plugin remove hoptoad_notifier
34
35 ### Rails 3.x
36
37 Add the hoptoad_notifier gem to your Gemfile. In Gemfile:
38
5dfa7fc Merge branch 'master' of github.com:thoughtbot/hoptoad_notifier
Chad Pytel authored
39 gem "hoptoad_notifier", "~> 2.3"
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
40
41 Then from your project's RAILS_ROOT, run:
42
43 bundle install
44 script/rails generate hoptoad --api-key your_key_here
45
46 That's it!
47
48 ### Rails 2.x
49
50 Add the hoptoad_notifier gem to your app. In config/environment.rb:
51
52 config.gem 'hoptoad_notifier'
53
54 Then from your project's RAILS_ROOT, run:
55
56 rake gems:install
57 rake gems:unpack GEM=hoptoad_notifier
58 script/generate hoptoad --api-key your_key_here
59
60 As always, if you choose not to vendor the hoptoad_notifier gem, make sure
61 every server you deploy to has the gem installed or your application won't start.
62
63 ### Rails 1.2.6
64
65 Install the hoptoad_notifier gem:
66
67 gem install hoptoad_notifier
68
69 Once installed, you should vendor the hoptoad_notifier gem:
70
71 mkdir vendor/gems
72 cd vendor/gems
73 gem unpack hoptoad_notifier
74
75 And then add the following to the Rails::Initializer.run do |config|
76 block in environment.rb so that the vendored gem is loaded.
77
78 # Add the vendor/gems/*/lib directories to the LOAD_PATH
79 config.load_paths += Dir.glob(File.join(RAILS_ROOT, 'vendor', 'gems', '*', 'lib'))
80
81 Next add something like this at the bottom of your config/environment.rb:
82
83 require 'hoptoad_notifier'
84 require 'hoptoad_notifier/rails'
85 HoptoadNotifier.configure do |config|
86 config.api_key = 'your_key_here'
87 end
88
89 You will also need to copy the hoptoad_notifier_tasks.rake file into your
90 RAILS_ROOT/lib/tasks directory in order for the rake hoptoad:test task to work:
91
92 cp vendor/gems/hoptoad_notifier-*/generators/hoptoad/templates/hoptoad_notifier_tasks.rake lib/tasks
93
94 As always, if you choose not to vendor the hoptoad_notifier gem, make sure
95 every server you deploy to has the gem installed or your application won't start.
96
97 ### Upgrading From Earlier Versions of Hoptoad
98
99 If you're currently using the plugin version (if you have a
100 vendor/plugins/hoptoad_notifier directory, you are), you'll need to perform a
101 few extra steps when upgrading to the gem version.
102
103 Add the hoptoad_notifier gem to your app. In config/environment.rb:
104
105 config.gem 'hoptoad_notifier'
106
107 Remove the plugin:
108
109 rm -rf vendor/plugins/hoptoad_notifier
110
111 Make sure the following line DOES NOT appear in your ApplicationController file:
112
113 include HoptoadNotifier::Catcher
114
115 If it does, remove it. The new catcher is automatically included by the gem
116 version of Hoptoad.
117
118 Before running the hoptoad generator, you need to find your project's API key.
119 Log in to your account at hoptoadapp.com, and click on the "Projects" button.
120 Then, find your project in the list, and click on its name. In the left-hand
121 column, you'll see an "Edit this project" button. Click on that to get your
122 project's API. (If you accidentally use your personal API auth_token, you won't
123 be able to install the gem.)
124
125 Then from your project's RAILS_ROOT, run:
126
127 rake gems:install
128 script/generate hoptoad --api-key your_key_here
129
130 Once installed, you should vendor the hoptoad_notifier gem.
131
132 rake gems:unpack GEM=hoptoad_notifier
133
134 As always, if you choose not to vendor the hoptoad_notifier gem, make sure
135 every server you deploy to has the gem installed or your application won't
136 start.
137
138 ### Upgrading from Earlier Versions of the Hoptoad Gem (with config.gem)
139
140 If you're currently using the gem version of the hoptoad_notifier and have
141 a version of Rails that uses config.gem (in the 2.x series), there is
142 a step or two that you need to do to upgrade. First, you need to remove
143 the old version of the gem from vendor/gems:
144
145 rm -rf vendor/gems/hoptoad_notifier-X.X.X
146
147 Then you must remove the hoptoad_notifier_tasks.rake file from lib:
148
149 rm lib/tasks/hoptoad_notifier_tasks.rake
150
151 You can them continue to install normally. If you don't remove the rake file,
152 you will be unable to unpack this gem (Rails will think it's part of the
153 framework).
154
155 ### Testing it out
156
157 You can test that Hoptoad is working in your production environment by using
158 this rake task (from RAILS_ROOT):
159
160 rake hoptoad:test
161
162 If everything is configured properly, that task will send a notice to Hoptoad
163 which will be visible immediately.
164
165 Rack
166 ----
167
168 In order to use hoptoad_notifier in a non-Rails rack app, just load the
169 hoptoad_notifier, configure your API key, and use the HoptoadNotifier::Rack
170 middleware:
171
172 require 'rack'
173 require 'hoptoad_notifier'
174
175 HoptoadNotifier.configure do |config|
176 config.api_key = 'my_api_key'
177 end
178
179 app = Rack::Builder.app do
180 use HoptoadNotifier::Rack
181 run lambda { |env| raise "Rack down" }
182 end
183
184 Sinatra
185 -------
186
187 Using hoptoad_notifier in a Sinatra app is just like a Rack app, but you have
188 to disable Sinatra's error rescuing functionality:
189
190 require 'sinatra/base'
191 require 'hoptoad_notifier'
192
193 HoptoadNotifier.configure do |config|
194 config.api_key = 'my_api_key'
195 end
196
197 class MyApp < Sinatra::Default
198 use HoptoadNotifier::Rack
199 enable :raise_errors
200
201 get "/" do
202 raise "Sinatra has left the building"
203 end
204 end
205
206 Usage
207 -----
208
209 For the most part, Hoptoad works for itself. Once you've included the notifier
210 in your ApplicationController (which is now done automatically by the gem),
211 all errors will be rescued by the #rescue_action_in_public provided by the gem.
212
213 If you want to log arbitrary things which you've rescued yourself from a
214 controller, you can do something like this:
215
216 ...
217 rescue => ex
218 notify_hoptoad(ex)
219 flash[:failure] = 'Encryptions could not be rerouted, try again.'
220 end
221 ...
222
223 The #notify_hoptoad call will send the notice over to Hoptoad for later
224 analysis. While in your controllers you use the notify_hoptoad method, anywhere
225 else in your code, use HoptoadNotifier.notify.
226
227 To perform custom error processing after Hoptoad has been notified, define the
228 instance method #rescue_action_in_public_without_hoptoad(exception) in your
229 controller.
230
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
231 Informing the User
232 ------------------
233
234 The Notifier gem is capable of telling the user information about the error that just happened
14fbdd6 @jyurek Change user_informer to user_information in README
jyurek authored
235 via the user_information option. They can give this error number in bug resports, for example.
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
236 By default, if your 500.html contains the text
237
238 <!-- HOPTOAD ERROR -->
239
240 then that comment will be replaced with the text "Hoptoad Error [errnum]". You can modify the text
14fbdd6 @jyurek Change user_informer to user_information in README
jyurek authored
241 of the informer by setting config.user_information. The Notifier will replace "{{ error_id }}" with the
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
242 ID of the error that is returned from Hoptoad.
243
244 HoptoadNotifier.configure do |config|
245 ...
14fbdd6 @jyurek Change user_informer to user_information in README
jyurek authored
246 config.user_information = "<p>Tell the devs that it was <strong>{{ error_id }}</strong>'s fault.</p>"
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
247 end
248
14fbdd6 @jyurek Change user_informer to user_information in README
jyurek authored
249 You can also turn the middleware completely off by setting config.user_information to false.
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
250
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
251 Tracking deployments in Hoptoad
252 -------------------------------
253
254 Paying Hoptoad plans support the ability to track deployments of your application in Hoptoad.
255 By notifying Hoptoad of your application deployments, all errors are resolved when a deploy occurs,
256 so that you'll be notified again about any errors that reoccur after a deployment.
257
258 Additionally, it's possible to review the errors in Hoptoad that occurred before and after a deploy.
259
260 When Hoptoad is installed as a gem, you need to add
261
262 require 'hoptoad_notifier/capistrano'
263
264 to your deploy.rb
265
7b3f346 @jasonm Add non-capistrano deploy instructions
jasonm authored
266 If you don't use Capistrano, then you can use the following rake task from your
267 deployment process to notify Hoptoad:
268
269 rake hoptoad:deploy TO=#{rails_env} REVISION=#{current_revision} REPO=#{repository} USER=#{local_user}
270
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
271 Going beyond exceptions
272 -----------------------
273
274 You can also pass a hash to notify_hoptoad method and store whatever you want,
275 not just an exception. And you can also use it anywhere, not just in
276 controllers:
277
278 begin
279 params = {
280 # params that you pass to a method that can throw an exception
281 }
282 my_unpredicable_method(params)
283 rescue => e
284 HoptoadNotifier.notify(
285 :error_class => "Special Error",
286 :error_message => "Special Error: #{e.message}",
287 :parameters => params
288 )
289 end
290
291 While in your controllers you use the notify_hoptoad method, anywhere else in
292 your code, use HoptoadNotifier.notify. Hoptoad will get all the information
293 about the error itself. As for a hash, these are the keys you should pass:
294
295 * :error_class - Use this to group similar errors together. When Hoptoad catches an exception it sends the class name of that exception object.
296 * :error_message - This is the title of the error you see in the errors list. For exceptions it is "#{exception.class.name}: #{exception.message}"
297 * :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.
298
299 Hoptoad merges the hash you pass with these default options:
300
301 {
302 :api_key => HoptoadNotifier.api_key,
303 :error_message => 'Notification',
304 :backtrace => caller,
305 :parameters => {},
306 :session => {}
307 }
308
309 You can override any of those parameters.
310
311 ### Sending shell environment variables when "Going beyond exceptions"
312
313 One common request we see is to send shell environment variables along with
314 manual exception notification. We recommend sending them along with CGI data
315 or Rack environment (:cgi_data or :rack_env keys, respectively.)
316
317 See HoptoadNotifier::Notice#initialize in lib/hoptoad_notifier/notice.rb for
318 more details.
319
320 Filtering
321 ---------
322
323 You can specify a whitelist of errors, that Hoptoad will not report on. Use
324 this feature when you are so apathetic to certain errors that you don't want
325 them even logged.
326
327 This filter will only be applied to automatic notifications, not manual
328 notifications (when #notify is called directly).
329
330 Hoptoad ignores the following exceptions by default:
331
5dfa7fc Merge branch 'master' of github.com:thoughtbot/hoptoad_notifier
Chad Pytel authored
332 AbstractController::ActionNotFound
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
333 ActiveRecord::RecordNotFound
334 ActionController::RoutingError
335 ActionController::InvalidAuthenticityToken
336 ActionController::UnknownAction
337 CGI::Session::CookieStore::TamperedWithCookie
338
339 To ignore errors in addition to those, specify their names in your Hoptoad
340 configuration block.
341
342 HoptoadNotifier.configure do |config|
343 config.api_key = '1234567890abcdef'
5dfa7fc Merge branch 'master' of github.com:thoughtbot/hoptoad_notifier
Chad Pytel authored
344 config.ignore << "ActiveRecord::IgnoreThisError"
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
345 end
346
347 To ignore *only* certain errors (and override the defaults), use the
348 #ignore_only attribute.
349
350 HoptoadNotifier.configure do |config|
351 config.api_key = '1234567890abcdef'
5dfa7fc Merge branch 'master' of github.com:thoughtbot/hoptoad_notifier
Chad Pytel authored
352 config.ignore_only = ["ActiveRecord::IgnoreThisError"]
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
353 end
354
355 To ignore certain user agents, add in the #ignore_user_agent attribute as a
356 string or regexp:
357
358 HoptoadNotifier.configure do |config|
359 config.api_key = '1234567890abcdef'
360 config.ignore_user_agent << /Ignored/
361 config.ignore_user_agent << 'IgnoredUserAgent'
362 end
363
364 To ignore exceptions based on other conditions, use #ignore_by_filter:
365
366 HoptoadNotifier.configure do |config|
367 config.api_key = '1234567890abcdef'
368 config.ignore_by_filter do |exception_data|
369 true if exception_data[:error_class] == "RuntimeError"
370 end
371 end
372
373 To replace sensitive information sent to the Hoptoad service with [FILTERED] use #params_filters:
374
375 HoptoadNotifier.configure do |config|
376 config.api_key = '1234567890abcdef'
377 config.params_filters << "credit_card_number"
378 end
379
380 Note that, when rescuing exceptions within an ActionController method,
381 hoptoad_notifier will reuse filters specified by #filter_parameter_logging.
382
383 Testing
384 -------
385
386 When you run your tests, you might notice that the Hoptoad service is recording
387 notices generated using #notify when you don't expect it to. You can
388 use code like this in your test_helper.rb to redefine that method so those
389 errors are not reported while running tests.
390
391 module HoptoadNotifier
392 def self.notify(thing)
393 # do nothing.
394 end
395 end
396
397 Proxy Support
398 -------------
399
400 The notifier supports using a proxy, if your server is not able to directly reach the Hoptoad servers. To configure the proxy settings, added the following information to your Hoptoad configuration block.
401
402 HoptoadNotifier.configure do |config|
403 config.proxy_host = ...
404 config.proxy_port = ...
405 config.proxy_user = ...
406 config.proxy_pass = ...
407
408 Supported Rails versions
409 ------------------------
410
411 See SUPPORTED_RAILS_VERSIONS for a list of official supported versions of
412 Rails.
413
414 Please open up a support ticket on Tender ( http://help.hoptoadapp.com ) if
415 you're using a version of Rails that is not listed above and the notifier is
416 not working properly.
417
418 Javascript Notifer
419 ------------------
420
a5163c7 @mjankowski first pass at changing JS html insertion into helper instead
mjankowski authored
421 To automatically include the Javascript node on every page, use this helper method from your layouts:
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
422
a5163c7 @mjankowski first pass at changing JS html insertion into helper instead
mjankowski authored
423 <%= hoptoad_javascript_notifier %>
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
424
a5163c7 @mjankowski first pass at changing JS html insertion into helper instead
mjankowski authored
425 It's important to insert this very high in the markup, above all other javascript. Example:
426
427 <!DOCTYPE html>
428 <html>
429 <head>
430 <meta charset="utf8">
431 <%= hoptoad_javascript_notifier %>
432 <!-- more javascript -->
433 </head>
434 <body>
435 ...
436 </body>
437 </html>
438
439 This helper will automatically use the API key, host, and port specified in the configuration.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
440
441 Credits
442 -------
443
444 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
445
446 HoptoadNotifier is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
447
b0abeed @mjankowski thank all contributors
mjankowski authored
448 Thank you to all [the contributors](https://github.com/thoughtbot/hoptoad_notifier/contributors)!
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
449
450 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
451
452 License
453 -------
454
455 HoptoadNotifier is Copyright © 2008-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
Something went wrong with that request. Please try again.