projectlocker_errata 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. data/CHANGELOG +908 -0
  2. data/Gemfile +3 -0
  3. data/Guardfile +6 -0
  4. data/INSTALL +20 -0
  5. data/MIT-LICENSE +23 -0
  6. data/README.md +460 -0
  7. data/README_FOR_HEROKU_ADDON.md +94 -0
  8. data/Rakefile +223 -0
  9. data/SUPPORTED_RAILS_VERSIONS +38 -0
  10. data/TESTING.md +41 -0
  11. data/features/metal.feature +18 -0
  12. data/features/rack.feature +60 -0
  13. data/features/rails.feature +272 -0
  14. data/features/rails_with_js_notifier.feature +97 -0
  15. data/features/rake.feature +27 -0
  16. data/features/sinatra.feature +29 -0
  17. data/features/step_definitions/file_steps.rb +10 -0
  18. data/features/step_definitions/metal_steps.rb +23 -0
  19. data/features/step_definitions/rack_steps.rb +23 -0
  20. data/features/step_definitions/rails_application_steps.rb +478 -0
  21. data/features/step_definitions/rake_steps.rb +17 -0
  22. data/features/support/env.rb +18 -0
  23. data/features/support/matchers.rb +35 -0
  24. data/features/support/projectlocker_errata_shim.rb.template +16 -0
  25. data/features/support/rails.rb +201 -0
  26. data/features/support/rake/Rakefile +68 -0
  27. data/features/support/terminal.rb +107 -0
  28. data/features/user_informer.feature +63 -0
  29. data/generators/projectlocker_errata/lib/insert_commands.rb +34 -0
  30. data/generators/projectlocker_errata/lib/rake_commands.rb +24 -0
  31. data/generators/projectlocker_errata/projectlocker_errata_generator.rb +94 -0
  32. data/generators/projectlocker_errata/templates/capistrano_hook.rb +6 -0
  33. data/generators/projectlocker_errata/templates/initializer.rb +6 -0
  34. data/generators/projectlocker_errata/templates/projectlocker_errata_tasks.rake +25 -0
  35. data/install.rb +1 -0
  36. data/lib/projectlocker_errata/backtrace.rb +108 -0
  37. data/lib/projectlocker_errata/capistrano.rb +43 -0
  38. data/lib/projectlocker_errata/configuration.rb +305 -0
  39. data/lib/projectlocker_errata/notice.rb +390 -0
  40. data/lib/projectlocker_errata/rack.rb +54 -0
  41. data/lib/projectlocker_errata/rails/action_controller_catcher.rb +30 -0
  42. data/lib/projectlocker_errata/rails/controller_methods.rb +85 -0
  43. data/lib/projectlocker_errata/rails/error_lookup.rb +33 -0
  44. data/lib/projectlocker_errata/rails/javascript_notifier.rb +47 -0
  45. data/lib/projectlocker_errata/rails/middleware/exceptions_catcher.rb +33 -0
  46. data/lib/projectlocker_errata/rails.rb +40 -0
  47. data/lib/projectlocker_errata/rails3_tasks.rb +98 -0
  48. data/lib/projectlocker_errata/railtie.rb +48 -0
  49. data/lib/projectlocker_errata/rake_handler.rb +65 -0
  50. data/lib/projectlocker_errata/sender.rb +128 -0
  51. data/lib/projectlocker_errata/shared_tasks.rb +47 -0
  52. data/lib/projectlocker_errata/tasks.rb +83 -0
  53. data/lib/projectlocker_errata/user_informer.rb +27 -0
  54. data/lib/projectlocker_errata/utils/blank.rb +53 -0
  55. data/lib/projectlocker_errata/version.rb +3 -0
  56. data/lib/projectlocker_errata.rb +159 -0
  57. data/lib/projectlocker_errata_tasks.rb +64 -0
  58. data/lib/rails/generators/projectlocker_errata/projectlocker_errata_generator.rb +100 -0
  59. data/lib/templates/javascript_notifier.erb +15 -0
  60. data/lib/templates/rescue.erb +91 -0
  61. data/projectlocker_errata.gemspec +39 -0
  62. data/rails/init.rb +1 -0
  63. data/resources/README.md +34 -0
  64. data/resources/ca-bundle.crt +3376 -0
  65. data/script/integration_test.rb +38 -0
  66. data/test/airbrake_2_3.xsd +88 -0
  67. data/test/backtrace_test.rb +162 -0
  68. data/test/capistrano_test.rb +34 -0
  69. data/test/catcher_test.rb +333 -0
  70. data/test/configuration_test.rb +236 -0
  71. data/test/helper.rb +263 -0
  72. data/test/javascript_notifier_test.rb +51 -0
  73. data/test/logger_test.rb +79 -0
  74. data/test/notice_test.rb +490 -0
  75. data/test/notifier_test.rb +276 -0
  76. data/test/projectlocker_errata_tasks_test.rb +170 -0
  77. data/test/rack_test.rb +58 -0
  78. data/test/rails_initializer_test.rb +36 -0
  79. data/test/recursion_test.rb +10 -0
  80. data/test/sender_test.rb +288 -0
  81. data/test/user_informer_test.rb +29 -0
  82. metadata +440 -0
data/Gemfile ADDED
@@ -0,0 +1,3 @@
1
+ source "http://rubygems.org"
2
+
3
+ gemspec
data/Guardfile ADDED
@@ -0,0 +1,6 @@
1
+ guard :test do
2
+ watch(%r{^lib/(.+)\.rb$}) { |m| "test/#{m[1]}_test.rb" }
3
+ watch(%r{^test/.+_test\.rb$})
4
+ watch('test/helper.rb') { "test" }
5
+ end
6
+
data/INSTALL ADDED
@@ -0,0 +1,20 @@
1
+ === Configuration
2
+
3
+ You should have something like this in config/initializers/projectlocker_errata.rb.
4
+
5
+ ProjectlockerErrata.configure do |config|
6
+ config.api_key = '1234567890abcdef'
7
+ end
8
+
9
+ (Please note that this configuration should be in a global configuration, and
10
+ is *not* environment-specific. ProjectlockerErrata is smart enough to know what errors are
11
+ caused by what environments, so your staging errors don't get mixed in with
12
+ your production errors.)
13
+
14
+ You can test that ProjectlockerErrata is working in your production environment by using
15
+ this rake task (from RAILS_ROOT):
16
+
17
+ rake projectlocker_errata:test
18
+
19
+ If everything is configured properly, that task will send a notice to ProjectlockerErrata
20
+ which will be visible immediately.
data/MIT-LICENSE ADDED
@@ -0,0 +1,23 @@
1
+ Copyright (c) 2012, ProjectLocker
2
+ Airbrake Gem Copyright (c) 2007 - 2012, Exceptional DBA Airbrake.io
3
+
4
+ Permission is hereby granted, free of charge, to any person
5
+ obtaining a copy of this software and associated documentation
6
+ files (the "Software"), to deal in the Software without
7
+ restriction, including without limitation the rights to use,
8
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the
10
+ Software is furnished to do so, subject to the following
11
+ conditions:
12
+
13
+ The above copyright notice and this permission notice shall be
14
+ included in all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
18
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
20
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
21
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
23
+ OTHER DEALINGS IN THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,460 @@
1
+ ProjectLocker Exception Reporting
2
+ ========
3
+
4
+ This is the notifier gem for integrating apps with [ProjectLocker Exception Reporting](http://www.projectlocker.com).
5
+
6
+ When an uncaught exception occurs, Errata will POST the relevant data
7
+ to the Errata server specified in your environment.
8
+
9
+ Help
10
+ ----
11
+
12
+ For help with using Errata and this notifier visit [our support site](https://portal.projectlocker.com/support_faq).
13
+
14
+ For SSL verification see the [Resources](https://github.com/airbrake/airbrake/blob/master/resources/README.md).
15
+
16
+ Rails Installation
17
+ ------------------
18
+
19
+ ### Rails 3.x
20
+
21
+ Add the projectlocker_errata gem to your Gemfile. In Gemfile:
22
+
23
+ gem "projectlocker_errata"
24
+
25
+ Then from your project's RAILS_ROOT, and in your development environment, run:
26
+
27
+ bundle install
28
+ rails generate projectlocker_errata --api-key your_key_here
29
+
30
+ That's it!
31
+
32
+ The generator creates a file under `config/initializers/projectlocker_errata.rb` configuring Errata 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.
33
+
34
+ ### Rails 2.x
35
+
36
+ Add the projectlocker_errata gem to your app. In config/environment.rb:
37
+
38
+ config.gem 'projectlocker_errata'
39
+
40
+ or if you are using bundler:
41
+
42
+ gem 'projectlocker_errata', :require => 'projectlocker_errata/rails'
43
+
44
+ Then from your project's RAILS_ROOT, and in your development environment, run:
45
+
46
+ rake gems:install
47
+ rake gems:unpack GEM=projectlocker_errata
48
+ script/generate projectlocker_errata --api-key your_key_here
49
+
50
+ As always, if you choose not to vendor the projectlocker_errata gem, make sure
51
+ every server you deploy to has the gem installed or your application won't start.
52
+
53
+ The generator creates a file under `config/initializers/projectlocker_errata.rb` configuring Errata 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.
54
+
55
+ ### Removing hoptoad_notifier
56
+
57
+ in your ApplicationController, REMOVE this line:
58
+
59
+ include HoptoadNotifiable
60
+
61
+ In your config/environment* files, remove all references to HoptoadNotifier
62
+
63
+ Remove the vendor/plugins/hoptoad_notifier directory.
64
+
65
+ ### Remove hoptoad_notifier plugin
66
+
67
+ Remove the vendor/plugins/hoptoad_notifier directory before installing the gem, or run:
68
+
69
+ script/plugin remove hoptoad_notifier
70
+
71
+ Non-rails apps using Bundler
72
+ ----------------------------
73
+ There is an undocumented dependency in `activesupport` where the `i18n` gem is
74
+ required only if the core classes extensions are used (`active_support/core_ext`).
75
+ This can lead to a confusing `LoadError` exception when using Errata. Until
76
+ this is fixed in `activesupport` the workaround is to add `i18n` to the Gemfile
77
+ for your Sinatra/Rack/pure ruby application:
78
+
79
+ gem 'i18n'
80
+ gem 'projectlocker_errata'
81
+
82
+ Rack
83
+ ----
84
+
85
+ In order to use projectlocker_errata in a non-Rails rack app, just load
86
+ projectlocker_errata, configure your API key, and use the ProjectlockerErrata::Rack
87
+ middleware:
88
+
89
+ require 'rack'
90
+ require 'projectlocker_errata'
91
+
92
+ Airbrake.configure do |config|
93
+ config.api_key = 'my_api_key'
94
+ end
95
+
96
+ app = Rack::Builder.app do
97
+ run lambda { |env| raise "Rack down" }
98
+ end
99
+
100
+ use ProjectlockerErrata::Rack
101
+ run app
102
+
103
+ Sinatra
104
+ -------
105
+
106
+ Using projectlocker_errata in a Sinatra app is just like a Rack app:
107
+
108
+ require 'sinatra'
109
+ require 'projectlocker_errata'
110
+
111
+ ProjectlockerErrata.configure do |config|
112
+ config.api_key = 'my api key'
113
+ end
114
+
115
+ use ProjectlockerErrata::Rack
116
+
117
+ get '/' do
118
+ raise "Sinatra has left the building"
119
+ end
120
+
121
+ Usage
122
+ -----
123
+
124
+ For the most part, Errata works for itself.
125
+
126
+ It intercepts the exception middleware calls, sends notifications and continues the middleware call chain.
127
+
128
+ If you want to log arbitrary things which you've rescued yourself from a
129
+ controller, you can do something like this:
130
+
131
+ ...
132
+ rescue => ex
133
+ notify_projectlocker_errata(ex)
134
+ flash[:failure] = 'Encryptions could not be rerouted, try again.'
135
+ end
136
+ ...
137
+
138
+ The `#notify_projectlocker_errata` call will send the notice over to Errata for later
139
+ analysis. While in your controllers you use the `notify_projectlocker_errata` method, anywhere
140
+ else in your code, use `ProjectlockerErrata.notify`.
141
+
142
+ To perform custom error processing after Errata has been notified, define the
143
+ instance method `#rescue_action_in_public_without_projectlocker_errata(exception)` in your
144
+ controller.
145
+
146
+ Informing the User
147
+ ------------------
148
+
149
+ The projectlocker_errata gem is capable of telling the user information about the error that just happened
150
+ via the user_information option. They can give this error number in bug reports, for example.
151
+ By default, if your 500.html contains the text
152
+
153
+ <!-- PROJECTLOCKER_ERRATA ERROR -->
154
+
155
+ then that comment will be replaced with the text "ProjectlockerErrata Error [errnum]". You can modify the text
156
+ of the informer by setting `config.user_information`. Errata will replace "{{ error_id }}" with the
157
+ ID of the error that is returned from Errata.
158
+
159
+ ProjectlockerErrata.configure do |config|
160
+ ...
161
+ config.user_information = "<p>Tell the devs that it was <strong>{{ error_id }}</strong>'s fault.</p>"
162
+ end
163
+
164
+ You can also turn the middleware that handles this completely off by setting `config.user_information` to false.
165
+
166
+ Note that this feature is reading the error id from `env['projectlocker_errata.error_id']`. When the exception is caught automatically in a controller, Errata sets that value. If you're, however, calling the Errata methods like `ProjectlockerErrata#notify` or `ProjectlockerErrata#notify_or_ignore`, please make sure you set that value. So the proper way of calling the
167
+ "manual" methods would be `env['projectlocker_errata.error_id'] = ProjectlockerErrata.notify_or_ignore(...)`.
168
+
169
+ Current user information
170
+ ------------------------
171
+ Errata provides information about the current logged in user, so you
172
+ could easily determine the user who experienced the error in your app.
173
+
174
+ It uses `current_user` and `current_member` to identify the
175
+ authenticated user, where `current_user` takes precedence.
176
+
177
+ If you use different naming, please add the following lines to your
178
+ controller:
179
+
180
+ alias_method :current_duck, :current_user
181
+ helper_method :current_duck
182
+
183
+ Voila! You'll get information about a duck that experienced crash about
184
+ your app.
185
+
186
+ Asynchronous notifications with Errata
187
+ ----------------------------------------
188
+ When your user experiences error using your application, it gets sent to
189
+ Errata server. This introduces a considerable latency in the response.
190
+
191
+ Asynchronous notification sending deals with this problem. Errata uses
192
+ [girl_friday](https://github.com/mperham/girl_friday) to achieve this
193
+ . (thanks Mike)
194
+
195
+ It's disabled by default and you can enable it in your Errata
196
+ configuration.
197
+
198
+ ProjectlockerErrata.configure do |config|
199
+ ...
200
+ config.async = true
201
+ end
202
+
203
+ *Note that this feature is enabled with JRuby 1.6+, Rubinius 2.0+ and*
204
+ *Ruby 1.9+. It does not support Ruby 1.8 because of its poor threading*
205
+ *support.*
206
+
207
+ For implementing custom asynchronous notice delivery, send a block to `config.async`. It
208
+ receives `notice` param. Pass it to `ProjectlockerErrata.sender.send_to_projectlocker_errata` method
209
+ to do actual delivery. In this way it's possible to move Errata notification
210
+ even in background worker(e.g. Resque or Sidekiq).
211
+
212
+ # Thread-based asynchronous send
213
+ ProjectlockerErrata.configure do |config|
214
+ ...
215
+ config.async do |notice|
216
+ Thread.new { ProjectlockerErrata.sender.send_to_projectlocker_errata(notice) }
217
+ end
218
+ end
219
+
220
+ # Resque-like configuration
221
+ ProjectlockerErrata.configure do |config|
222
+ ...
223
+ config.async do |notice|
224
+ Resque.enqueue(ProjectlockerErrataDeliveryWorker, notice)
225
+ end
226
+ end
227
+
228
+ Tracking deployments in Errata
229
+ --------------------------------
230
+
231
+ Errata supports the ability to track deployments of your application in Errata.
232
+ By notifying Errata of your application deployments, all errors are resolved when a deploy occurs,
233
+ so that you'll be notified again about any errors that reoccur after a deployment.
234
+
235
+ Additionally, it's possible to review the errors in Errata that occurred before and after a deploy.
236
+
237
+ When Errata is installed as a gem, you need to add
238
+
239
+ require 'projectlocker_errata/capistrano'
240
+
241
+ to your deploy.rb
242
+
243
+ If you don't use Capistrano, then you can use the following rake task from your
244
+ deployment process to notify Errata:
245
+
246
+ rake projectlocker_errata:deploy TO=#{rails_env} REVISION=#{current_revision} REPO=#{repository} USER=#{local_user}
247
+
248
+ Going beyond exceptions
249
+ -----------------------
250
+
251
+ You can also pass a hash to `ProjectlockerErrata.notify` method and store whatever you want,
252
+ not just an exception. And you can also use it anywhere, not just in
253
+ controllers:
254
+
255
+ begin
256
+ params = {
257
+ # params that you pass to a method that can throw an exception
258
+ }
259
+ my_unpredicable_method(params)
260
+ rescue => e
261
+ ProjectlockerErrata.notify_or_ignore(
262
+ :error_class => "Special Error",
263
+ :error_message => "Special Error: #{e.message}",
264
+ :parameters => params
265
+ )
266
+ end
267
+
268
+ While in your controllers you use the `notify_projectlocker_errata` method, anywhere else in
269
+ your code, use `ProjectlockerErrata.notify`. Errata will get all the information
270
+ about the error itself. As for a hash, these are the keys you should pass:
271
+
272
+ * `:error_class` - Use this to group similar errors together. When Errata catches an exception it sends the class name of that exception object.
273
+ * `:error_message` - This is the title of the error you see in the errors list. For exceptions it is "#{exception.class.name}: #{exception.message}"
274
+ * `:parameters` - While there are several ways to send additional data to Errata, passing a Hash as :parameters as in the example above is the most common use case. When Errata catches an exception in a controller, the actual HTTP client request parameters are sent using this key.
275
+
276
+ Errata merges the hash you pass with these default options:
277
+
278
+ {
279
+ :api_key => ProjectlockerErrata.api_key,
280
+ :error_message => 'Notification',
281
+ :backtrace => caller,
282
+ :parameters => {},
283
+ :session => {}
284
+ }
285
+
286
+ You can override any of those parameters.
287
+
288
+ ### Sending shell environment variables when "Going beyond exceptions"
289
+
290
+ One common request we see is to send shell environment variables along with
291
+ manual exception notification. We recommend sending them along with CGI data
292
+ or Rack environment (:cgi_data or :rack_env keys, respectively.)
293
+
294
+ See ProjectlockerErrata::Notice#initialize in lib/projectlocker_errata/notice.rb for
295
+ more details.
296
+
297
+ Filtering
298
+ ---------
299
+
300
+ You can specify a whitelist of errors that ProjectlockerErrata will not report on. Use
301
+ this feature when you are so apathetic to certain errors that you don't want
302
+ them even logged.
303
+
304
+ This filter will only be applied to automatic notifications, not manual
305
+ notifications (when #notify is called directly).
306
+
307
+ Errata ignores the following exceptions by default:
308
+
309
+ ActiveRecord::RecordNotFound
310
+ ActionController::RoutingError
311
+ ActionController::InvalidAuthenticityToken
312
+ CGI::Session::CookieStore::TamperedWithCookie
313
+ ActionController::UnknownAction
314
+ AbstractController::ActionNotFound
315
+ Mongoid::Errors::DocumentNotFound
316
+
317
+
318
+ To ignore errors in addition to those, specify their names in your Errata
319
+ configuration block.
320
+
321
+ ProjectlockerErrata.configure do |config|
322
+ config.api_key = '1234567890abcdef'
323
+ config.ignore << "ActiveRecord::IgnoreThisError"
324
+ end
325
+
326
+ To ignore *only* certain errors (and override the defaults), use the #ignore_only attribute.
327
+
328
+ ProjectlockerErrata.configure do |config|
329
+ config.api_key = '1234567890abcdef'
330
+ config.ignore_only = ["ActiveRecord::IgnoreThisError"] # or [] to ignore no exceptions.
331
+ end
332
+
333
+ To ignore certain user agents, add in the #ignore_user_agent attribute as a
334
+ string or regexp:
335
+
336
+ ProjectlockerErrata.configure do |config|
337
+ config.api_key = '1234567890abcdef'
338
+ config.ignore_user_agent << /Ignored/
339
+ config.ignore_user_agent << 'IgnoredUserAgent'
340
+ end
341
+
342
+ To ignore exceptions based on other conditions, use #ignore_by_filter:
343
+
344
+ ProjectlockerErrata.configure do |config|
345
+ config.api_key = '1234567890abcdef'
346
+ config.ignore_by_filter do |exception_data|
347
+ true if exception_data[:error_class] == "RuntimeError"
348
+ end
349
+ end
350
+
351
+ To replace sensitive information sent to the ProjectlockerErrata service with [FILTERED] use #params_filters:
352
+
353
+ ProjectlockerErrata.configure do |config|
354
+ config.api_key = '1234567890abcdef'
355
+ config.params_filters << "credit_card_number"
356
+ end
357
+
358
+ Note that, when rescuing exceptions within an ActionController method,
359
+ Errata will reuse filters specified by #filter_parameter_logging.
360
+
361
+ Testing
362
+ -------
363
+
364
+ When you run your tests, you might notice that the Errata service is recording
365
+ notices generated using #notify when you don't expect it to. You can
366
+ use code like this in your test_helper.rb or spec_helper.rb files to redefine
367
+ that method so those errors are not reported while running tests.
368
+
369
+ module ProjectlockerErrata
370
+ def self.notify(exception, opts = {})
371
+ # do nothing.
372
+ end
373
+ end
374
+
375
+ Proxy Support
376
+ -------------
377
+
378
+ The notifier supports using a proxy, if your server is not able to directly reach the Errata servers. To configure the proxy settings, added the following information to your Errata configuration block.
379
+
380
+ ProjectlockerErrata.configure do |config|
381
+ config.proxy_host = proxy.host.com
382
+ config.proxy_port = 4038
383
+ config.proxy_user = foo # optional
384
+ config.proxy_pass = bar # optional
385
+
386
+ Logging
387
+ ------------
388
+
389
+ Errata uses the logger from your Rails application by default, presumably STDOUT. If you don't like Errata scribbling to your standard output, just pass another `Logger` instance inside your configuration:
390
+
391
+ ProjectlockerErrata.configure do |config|
392
+ ...
393
+ config.logger = Logger.new("path/to/your/log/file")
394
+ end
395
+
396
+ Supported Rails versions
397
+ ------------------------
398
+
399
+ See SUPPORTED_RAILS_VERSIONS for a list of official supported versions of
400
+ Rails.
401
+
402
+ Please open up a support ticket ( http://portal.projectlocker.com/support/new_ticket)
403
+ if you're using a version of Rails that is listed above and the notifier is
404
+ not working properly.
405
+
406
+ Javascript Notifier
407
+ ------------------
408
+
409
+ To automatically include the Javascript node on every page, use this helper method from your layouts:
410
+
411
+ <%= projectlocker_errata_javascript_notifier %>
412
+
413
+ It's important to insert this very high in the markup, above all other javascript. Example:
414
+
415
+ <!DOCTYPE html>
416
+ <html>
417
+ <head>
418
+ <meta charset="utf8">
419
+ <%= projectlocker_errata_javascript_notifier %>
420
+ <!-- more javascript -->
421
+ </head>
422
+ <body>
423
+ ...
424
+ </body>
425
+ </html>
426
+
427
+ This helper will automatically use the API key, host, and port specified in the configuration.
428
+
429
+ The Javascript notifier tends to send much more notifications than the base Rails project.
430
+ If you want to receive them into a separate Errata project, specify its
431
+ API key in the `js_api_key` option.
432
+
433
+ config.js_api_key = 'another-projects-api-key'
434
+
435
+ To test the Javascript notifier in development environment, overwrite (temporarily) the development_environments option:
436
+
437
+ ProjectlockerErrata.configure do |config|
438
+ # ...
439
+ config.development_environments = []
440
+ end
441
+
442
+ Development
443
+ -----------
444
+
445
+ See TESTING.md for instructions on how to run the tests.
446
+
447
+ Credits
448
+ -------
449
+ ![ProjectLocker](http://www.projectlocker.com/images/projectlocker_logo_244x30.png)
450
+
451
+ Special thanks to ![thoughtbot](http://thoughtbot.com/images/tm/logo.png) and Airbrake as creators of the Airbrake gem upon which this is based.
452
+
453
+ Errata is maintained and funded by [ProjectLocker](http://www.projectlocker.com)
454
+
455
+ The names and logos for ProjectLocker, Airbrake, and thoughtbot are trademarks of their respective holders.
456
+
457
+ License
458
+ -------
459
+
460
+ Errata is Copyright © 2012 ProjectLocker. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
@@ -0,0 +1,94 @@
1
+ ProjectlockerErrata on Heroku
2
+ ==================
3
+
4
+ Send your application errors to our hosted service and reclaim your inbox.
5
+
6
+ 1. Installing the Heroku add-on
7
+ ----------------------------
8
+ To use ProjectlockerErrata on Heroku, install the ProjectlockerErrata add-on:
9
+
10
+ $ heroku addons:add projectlocker_errata:basic # This adds the the basic plan.
11
+ # If you'd like another plan, specify that instead.
12
+
13
+ 2. Including the ProjectlockerErrata notifier in your application
14
+ --------------------------------------------------
15
+ After adding the ProjectlockerErrata add-on, you will need to install and configure the ProjectlockerErrata notifier.
16
+
17
+ Your application connects to ProjectlockerErrata with an API key. On Heroku, this is automatically provided to your
18
+ application in `ENV['HOPTOAD_API_KEY']`, so installation should be a snap! (Hoptoad is ProjectlockerErrata's old name.)
19
+
20
+ ### Rails 3.x
21
+
22
+ Add the projectlocker_errata and heroku gems to your Gemfile. In Gemfile:
23
+
24
+ gem 'projectlocker_errata'
25
+ gem 'heroku'
26
+
27
+ Then from your project's RAILS_ROOT, run:
28
+
29
+ $ bundle install
30
+ $ script/rails generate projectlocker_errata --heroku
31
+
32
+ ### Rails 2.x
33
+
34
+ Install the heroku gem if you haven't already:
35
+
36
+ gem install heroku
37
+
38
+ Add the projectlocker_errata gem to your app. In config/environment.rb:
39
+
40
+ config.gem 'projectlocker_errata'
41
+
42
+ Then from your project's RAILS_ROOT, run:
43
+
44
+ $ rake gems:install
45
+ $ rake gems:unpack GEM=projectlocker_errata
46
+ $ script/generate projectlocker_errata --heroku
47
+
48
+ As always, if you choose not to vendor the projectlocker_errata gem, make sure
49
+ every server you deploy to has the gem installed or your application won't start.
50
+
51
+ ### Rack applications
52
+
53
+ In order to use projectlocker_errata in a non-Rails rack app, just load the projectlocker_errata, configure your API key, and use the ProjectlockerErrata::Rack middleware:
54
+
55
+ require 'rubygems'
56
+ require 'rack'
57
+ require 'projectlocker_errata'
58
+
59
+ ProjectlockerErrata.configure do |config|
60
+ config.api_key = `ENV['HOPTOAD_API_KEY']`
61
+ end
62
+
63
+ app = Rack::Builder.app do
64
+ use ProjectlockerErrata::Rack
65
+ run lambda { |env| raise "Rack down" }
66
+ end
67
+
68
+ ### Rails 1.x
69
+
70
+ For Rails 1.x, visit the [ProjectlockerErrata notifier's README on GitHub](http://github.com/thoughtbot/projectlocker_errata),
71
+ and be sure to use `ENV['HOPTOAD_API_KEY']` where your API key is required in configuration code.
72
+
73
+ 3. Configure your notification settings (important!)
74
+ ---------------------------------------------------
75
+
76
+ Once you have included and configured the notifier in your application,
77
+ you will want to configure your notification settings.
78
+
79
+ This is important - without setting your email address, you won't receive notification emails.
80
+
81
+ ProjectlockerErrata can deliver exception notifications to your email inbox. To configure these delivery settings:
82
+
83
+ 1. Visit your applications resources page, like [ http://api.heroku.com/myapps/my-great-app/resources ](http://api.heroku.com/myapps/my-great-app/resources).
84
+ 2. Click the name of your ProjectlockerErrata addon. (It may still be called Hoptoad.)
85
+ 3. Click "Settings" to configure the Hoptoad Add-on.
86
+
87
+ 4. Optionally: Set up deploy notification
88
+ -----------------------------------------
89
+
90
+ If your ProjectlockerErrata plan supports deploy notification, set it up for your Heroku application like this:
91
+
92
+ rake projectlocker_errata:heroku:add_deploy_notification
93
+
94
+ This will install a Heroku [HTTP Deploy Hook](http://docs.heroku.com/deploy-hooks) to notify ProjectlockerErrata of the deploy.