Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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