Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 557 lines (387 sloc) 18.247 kb
1de4cf8 Update readme to reflect name change
Harold Giménez authored
1 Airbrake
2 ========
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
3
582dce9 @stuartchaney point towards airbrake.io
stuartchaney authored
4 This is the notifier gem for integrating apps with [Airbrake](http://airbrake.io).
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
5
1de4cf8 Update readme to reflect name change
Harold Giménez authored
6 When an uncaught exception occurs, Airbrake will POST the relevant data
7 to the Airbrake server specified in your environment.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
8
9 Help
10 ----
11
d071460 Crosslinked docs...
Jonathan Siegel authored
12 For help with using Airbrake and this notifier visit [our support site](http://help.airbrake.io).
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
13
506ac3d @stve Updated URL's in README
stve authored
14 For SSL verification see the [Resources](https://github.com/airbrake/airbrake/blob/master/resources/README.md).
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
15
16 Rails Installation
17 ------------------
18
19 ### Rails 3.x
20
1de4cf8 Update readme to reflect name change
Harold Giménez authored
21 Add the airbrake gem to your Gemfile. In Gemfile:
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
22
9752a88 Minor fix to Gemfile instructions on README
Harold Giménez authored
23 gem "airbrake"
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
24
bb9a51c Improve installation docs
Harold Giménez authored
25 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
26
27 bundle install
dc620a1 @dvdplm Documentation glitch
dvdplm authored
28 rails generate airbrake --api-key your_key_here
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
29
30 That's it!
31
1de4cf8 Update readme to reflect name change
Harold Giménez authored
32 The generator creates a file under `config/initializers/airbrake.rb` configuring Airbrake 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.
bb9a51c Improve installation docs
Harold Giménez authored
33
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
34 ### Rails 2.x
35
1de4cf8 Update readme to reflect name change
Harold Giménez authored
36 Add the airbrake gem to your app. In config/environment.rb:
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
37
1de4cf8 Update readme to reflect name change
Harold Giménez authored
38 config.gem 'airbrake'
73de36b @stuartchaney Updating README gem instructions for Rails 2.3 with bundler.
stuartchaney authored
39
40 or if you are using bundler:
41
42 gem 'airbrake', :require => 'airbrake/rails'
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
43
bb9a51c Improve installation docs
Harold Giménez authored
44 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
45
46 rake gems:install
1de4cf8 Update readme to reflect name change
Harold Giménez authored
47 rake gems:unpack GEM=airbrake
48 script/generate airbrake --api-key your_key_here
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
49
1de4cf8 Update readme to reflect name change
Harold Giménez authored
50 As always, if you choose not to vendor the airbrake gem, make sure
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
51 every server you deploy to has the gem installed or your application won't start.
52
1de4cf8 Update readme to reflect name change
Harold Giménez authored
53 The generator creates a file under `config/initializers/airbrake.rb` configuring Airbrake 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.
bb9a51c Improve installation docs
Harold Giménez authored
54
1de4cf8 Update readme to reflect name change
Harold Giménez authored
55 ### Upgrading From Earlier Versions of Airbrake
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
56
57 If you're currently using the plugin version (if you have a
58 vendor/plugins/hoptoad_notifier directory, you are), you'll need to perform a
59 few extra steps when upgrading to the gem version.
60
1de4cf8 Update readme to reflect name change
Harold Giménez authored
61 Add the airbrake gem to your app. In config/environment.rb:
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
62
1de4cf8 Update readme to reflect name change
Harold Giménez authored
63 config.gem 'airbrake'
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
64
65 Remove the plugin:
66
67 rm -rf vendor/plugins/hoptoad_notifier
68
69 Make sure the following line DOES NOT appear in your ApplicationController file:
70
71 include HoptoadNotifier::Catcher
72
73 If it does, remove it. The new catcher is automatically included by the gem
1de4cf8 Update readme to reflect name change
Harold Giménez authored
74 version of Airbrake.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
75
1de4cf8 Update readme to reflect name change
Harold Giménez authored
76 Before running the airbrake generator, you need to find your project's API key.
582dce9 @stuartchaney point towards airbrake.io
stuartchaney authored
77 Log in to your account at airbrake.io, and click on the "Projects" button.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
78 Then, find your project in the list, and click on its name. In the left-hand
79 column, you'll see an "Edit this project" button. Click on that to get your
1de4cf8 Update readme to reflect name change
Harold Giménez authored
80 project's API key. If you accidentally use your personal API auth_token,
81 you will get API key not found errors, and exceptions will not be stored
82 by the Airbrake service.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
83
84 Then from your project's RAILS_ROOT, run:
85
86 rake gems:install
1de4cf8 Update readme to reflect name change
Harold Giménez authored
87 script/generate airbrake --api-key your_key_here
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
88
1de4cf8 Update readme to reflect name change
Harold Giménez authored
89 Once installed, you should vendor the airbrake gem.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
90
1de4cf8 Update readme to reflect name change
Harold Giménez authored
91 rake gems:unpack GEM=airbrake
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
92
1de4cf8 Update readme to reflect name change
Harold Giménez authored
93 As always, if you choose not to vendor the airbrake gem, make sure
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
94 every server you deploy to has the gem installed or your application won't
95 start.
96
97 ### Upgrading from Earlier Versions of the Hoptoad Gem (with config.gem)
98
99 If you're currently using the gem version of the hoptoad_notifier and have
100 a version of Rails that uses config.gem (in the 2.x series), there is
101 a step or two that you need to do to upgrade. First, you need to remove
102 the old version of the gem from vendor/gems:
103
104 rm -rf vendor/gems/hoptoad_notifier-X.X.X
105
106 Then you must remove the hoptoad_notifier_tasks.rake file from lib:
107
108 rm lib/tasks/hoptoad_notifier_tasks.rake
109
1de4cf8 Update readme to reflect name change
Harold Giménez authored
110 You can then continue to install normally. If you don't remove the rake file,
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
111 you will be unable to unpack this gem (Rails will think it's part of the
112 framework).
113
0affe44 @dvdplm Documenting workaround for issue #39
dvdplm authored
114
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
115
1de4cf8 Update readme to reflect name change
Harold Giménez authored
116 You can test that Airbrake is working in your production environment by using
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
117 this rake task (from RAILS_ROOT):
118
1de4cf8 Update readme to reflect name change
Harold Giménez authored
119 rake airbrake:test
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
120
e61b1ca @bquorning README updated to reflect name change from Hoptoad to Airbrake
bquorning authored
121 If everything is configured properly, that task will send a notice to Airbrake
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
122 which will be visible immediately.
123
da3d5c0 Migrated to new api.airbrake.io endpoint.
Jonathan Siegel authored
124 ### Removing hoptoad_notifier
125
126 in your ApplicationController, REMOVE this line:
127
128 include HoptoadNotifiable
129
130 In your config/environment* files, remove all references to HoptoadNotifier
131
132 Remove the vendor/plugins/hoptoad_notifier directory.
133
134 ### Remove hoptoad_notifier plugin
135
136 Remove the vendor/plugins/hoptoad_notifier directory before installing the gem, or run:
137
138 script/plugin remove hoptoad_notifier
0affe44 @dvdplm Documenting workaround for issue #39
dvdplm authored
139
140 Non-rails apps using Bundler
141 ----------------------------
142 There is an undocumented dependency in `activesupport` where the `i18n` gem is
143 required only if the core classes extensions are used (`active_support/core_ext`).
144 This can lead to a confusing `LoadError` exception when using Airbrake. Until
145 this is fixed in `activesupport` the workaround is to add `i18n` to the Gemfile
146 for your Sinatra/Rack/pure ruby application:
147
148 gem 'i18n'
149 gem 'airbrake'
150
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
151 Rack
152 ----
153
1de4cf8 Update readme to reflect name change
Harold Giménez authored
154 In order to use airbrake in a non-Rails rack app, just load
155 airbrake, configure your API key, and use the Airbrake::Rack
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
156 middleware:
157
158 require 'rack'
1de4cf8 Update readme to reflect name change
Harold Giménez authored
159 require 'airbrake'
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
160
1de4cf8 Update readme to reflect name change
Harold Giménez authored
161 Airbrake.configure do |config|
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
162 config.api_key = 'my_api_key'
163 end
164
165 app = Rack::Builder.app do
166 run lambda { |env| raise "Rack down" }
167 end
2b6c0db @shime update rack example in readme
shime authored
168
169 use Airbrake::Rack
170 run app
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
171
172 Sinatra
173 -------
174
0affe44 @dvdplm Documenting workaround for issue #39
dvdplm authored
175 Using airbrake in a Sinatra app is just like a Rack app:
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
176
0affe44 @dvdplm Documenting workaround for issue #39
dvdplm authored
177 require 'sinatra'
1de4cf8 Update readme to reflect name change
Harold Giménez authored
178 require 'airbrake'
179
180 Airbrake.configure do |config|
0affe44 @dvdplm Documenting workaround for issue #39
dvdplm authored
181 config.api_key = 'my api key'
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
182 end
1de4cf8 Update readme to reflect name change
Harold Giménez authored
183
0affe44 @dvdplm Documenting workaround for issue #39
dvdplm authored
184 use Airbrake::Rack
1de4cf8 Update readme to reflect name change
Harold Giménez authored
185
0affe44 @dvdplm Documenting workaround for issue #39
dvdplm authored
186 get '/' do
187 raise "Sinatra has left the building"
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
188 end
189
190 Usage
191 -----
192
4ff45e9 @shime update explanation how we catch errors in readme
shime authored
193 For the most part, Airbrake works for itself.
194
195 It intercepts the exception middleware calls, sends notifications and continues the middleware call chain.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
196
197 If you want to log arbitrary things which you've rescued yourself from a
198 controller, you can do something like this:
199
200 ...
201 rescue => ex
1de4cf8 Update readme to reflect name change
Harold Giménez authored
202 notify_airbrake(ex)
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
203 flash[:failure] = 'Encryptions could not be rerouted, try again.'
204 end
205 ...
206
1de4cf8 Update readme to reflect name change
Harold Giménez authored
207 The `#notify_airbrake` call will send the notice over to Airbrake for later
208 analysis. While in your controllers you use the `notify_airbrake` method, anywhere
209 else in your code, use `Airbrake.notify`.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
210
1de4cf8 Update readme to reflect name change
Harold Giménez authored
211 To perform custom error processing after Airbrake has been notified, define the
212 instance method `#rescue_action_in_public_without_airbrake(exception)` in your
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
213 controller.
214
34c2513 @mmcdaris rake section added
mmcdaris authored
215 Rake Tasks
216 ----------
217 Do you want Airbrake to report exceptions that happen inside a rake task?
218
219 Airbrake.configure do |config|
220 ...
221 config.rescue_rake_exceptions = true
222 end
223
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
224 Informing the User
225 ------------------
226
1de4cf8 Update readme to reflect name change
Harold Giménez authored
227 The airbrake gem is capable of telling the user information about the error that just happened
ab813ee @usiegj00 Fixed typo.
usiegj00 authored
228 via the user_information option. They can give this error number in bug reports, for example.
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
229 By default, if your 500.html contains the text
230
1de4cf8 Update readme to reflect name change
Harold Giménez authored
231 <!-- AIRBRAKE ERROR -->
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
232
1de4cf8 Update readme to reflect name change
Harold Giménez authored
233 then that comment will be replaced with the text "Airbrake Error [errnum]". You can modify the text
234 of the informer by setting `config.user_information`. Airbrake will replace "{{ error_id }}" with the
235 ID of the error that is returned from Airbrake.
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
236
022f22a @shime fix formatting
shime authored
237 Airbrake.configure do |config|
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
238 ...
022f22a @shime fix formatting
shime authored
239 config.user_information = "<p>Tell the devs that it was <strong>{{ error_id }}</strong>'s fault.</p>"
240 end
beea218 @jyurek Don't rely on anything but Rack spec when modifying in the Informer
jyurek authored
241
1de4cf8 Update readme to reflect name change
Harold Giménez authored
242 You can also turn the middleware that handles this 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
243
7bb2a94 @shime add a note about informing the user
shime authored
244 Note that this feature is reading the error id from `env['airbrake.error_id']`. When the exception is caught
245 automatically in a controller, Airbrake sets that value. If you're, however, calling the Airbrake methods like
246 `Airbrake#notify` or `Airbrake#notify_or_ignore`, please make sure you set that value. So the proper way of calling the
247 "manual" methods would be `env['airbrake.error_id'] = Airbrake.notify_or_ignore(...)`.
248
85181e3 @shime send info about the current logged in user
shime authored
249 Current user information
250 ------------------------
251 Airbrake provides information about the current logged in user, so you
c3c0e3c @shime make collected user attributes customizable
shime authored
252 can easily determine the user who experienced the error in your app.
85181e3 @shime send info about the current logged in user
shime authored
253
254 It uses `current_user` and `current_member` to identify the
255 authenticated user, where `current_user` takes precendence.
256
257 If you use different naming, please add the following lines to your
258 controller:
259
260 alias_method :current_duck, :current_user
261 helper_method :current_duck
262
c3c0e3c @shime make collected user attributes customizable
shime authored
263 Voila! You'll get information about a duck that experienced a crash of
85181e3 @shime send info about the current logged in user
shime authored
264 your app.
265
c3c0e3c @shime make collected user attributes customizable
shime authored
266 By default Airbrake collects the following attributes:
267 * id
268 * name
269 * username
270 * email
271
272 You can also customize attributes that will be collected
273
274 Airbrake.configure do |config|
275 ...
276 # collect only user ids
277 config.user_attributes = [:id] # ["id"] also works
278 end
279
7ae3f7e @shime add async notifications
shime authored
280 Asynchronous notifications with Airbrake
281 ----------------------------------------
282 When your user experiences error using your application, it gets sent to
283 Airbrake server. This introduces a considerable latency in the response.
284
285 Asynchronous notification sending deals with this problem. Airbrake uses
286 [girl_friday](https://github.com/mperham/girl_friday) to achieve this
287 . (thanks Mike)
288
289 It's disabled by default and you can enable it in your Airbrake
290 configuration.
291
292 Airbrake.configure do |config|
293 ...
294 config.async = true
295 end
296
297 *Note that this feature is enabled with JRuby 1.6+, Rubinius 2.0+ and*
298 *Ruby 1.9+. It does not support Ruby 1.8 because of its poor threading*
299 *support.*
300
c5bd574 @shime stop converting notice to xml before passing it to sender
shime authored
301 For implementing custom asynchronous notice delivery, send a block to `config.async`. It
1111f11 @cris Simplify config.async to use only notice param
cris authored
302 receives `notice` param. Pass it to `Airbrake.sender.send_to_airbrake` method
303 to do actual delivery. In this way it's possible to move Airbrake notification
304 even in background worker(e.g. Resque or Sidekiq).
0940f2e @cris Refactor config.async to provide custom asynchronous delivery way
cris authored
305
1111f11 @cris Simplify config.async to use only notice param
cris authored
306 # Thread-based asynchronous send
0940f2e @cris Refactor config.async to provide custom asynchronous delivery way
cris authored
307 Airbrake.configure do |config|
308 ...
1111f11 @cris Simplify config.async to use only notice param
cris authored
309 config.async do |notice|
c5bd574 @shime stop converting notice to xml before passing it to sender
shime authored
310 Thread.new { Airbrake.sender.send_to_airbrake(notice) }
1111f11 @cris Simplify config.async to use only notice param
cris authored
311 end
0940f2e @cris Refactor config.async to provide custom asynchronous delivery way
cris authored
312 end
313
314 # Resque-like configuration
315 Airbrake.configure do |config|
316 ...
1111f11 @cris Simplify config.async to use only notice param
cris authored
317 config.async do |notice|
0940f2e @cris Refactor config.async to provide custom asynchronous delivery way
cris authored
318 Resque.enqueue(AirbrakeDeliveryWorker, notice)
319 end
320 end
85181e3 @shime send info about the current logged in user
shime authored
321
e61b1ca @bquorning README updated to reflect name change from Hoptoad to Airbrake
bquorning authored
322 Tracking deployments in Airbrake
323 --------------------------------
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
324
1de4cf8 Update readme to reflect name change
Harold Giménez authored
325 Paying Airbrake plans support the ability to track deployments of your application in Airbrake.
326 By notifying Airbrake of your application deployments, all errors are resolved when a deploy occurs,
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
327 so that you'll be notified again about any errors that reoccur after a deployment.
328
1de4cf8 Update readme to reflect name change
Harold Giménez authored
329 Additionally, it's possible to review the errors in Airbrake that occurred before and after a deploy.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
330
1de4cf8 Update readme to reflect name change
Harold Giménez authored
331 When Airbrake is installed as a gem, you need to add
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
332
1de4cf8 Update readme to reflect name change
Harold Giménez authored
333 require 'airbrake/capistrano'
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
334
335 to your deploy.rb
336
7b3f346 @jasonm Add non-capistrano deploy instructions
jasonm authored
337 If you don't use Capistrano, then you can use the following rake task from your
1de4cf8 Update readme to reflect name change
Harold Giménez authored
338 deployment process to notify Airbrake:
7b3f346 @jasonm Add non-capistrano deploy instructions
jasonm authored
339
1de4cf8 Update readme to reflect name change
Harold Giménez authored
340 rake airbrake:deploy TO=#{rails_env} REVISION=#{current_revision} REPO=#{repository} USER=#{local_user}
7b3f346 @jasonm Add non-capistrano deploy instructions
jasonm authored
341
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
342 Going beyond exceptions
343 -----------------------
344
1de4cf8 Update readme to reflect name change
Harold Giménez authored
345 You can also pass a hash to `Airbrake.notify` method and store whatever you want,
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
346 not just an exception. And you can also use it anywhere, not just in
347 controllers:
348
349 begin
350 params = {
351 # params that you pass to a method that can throw an exception
352 }
353 my_unpredicable_method(params)
354 rescue => e
d9a7067 @mmcdaris changed notify to notify_or_ignore
mmcdaris authored
355 Airbrake.notify_or_ignore(
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
356 :error_class => "Special Error",
357 :error_message => "Special Error: #{e.message}",
358 :parameters => params
359 )
360 end
361
1de4cf8 Update readme to reflect name change
Harold Giménez authored
362 While in your controllers you use the `notify_airbrake` method, anywhere else in
363 your code, use `Airbrake.notify`. Airbrake will get all the information
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
364 about the error itself. As for a hash, these are the keys you should pass:
365
e61b1ca @bquorning README updated to reflect name change from Hoptoad to Airbrake
bquorning authored
366 * `:error_class` - Use this to group similar errors together. When Airbrake catches an exception it sends the class name of that exception object.
1de4cf8 Update readme to reflect name change
Harold Giménez authored
367 * `:error_message` - This is the title of the error you see in the errors list. For exceptions it is "#{exception.class.name}: #{exception.message}"
368 * `:parameters` - While there are several ways to send additional data to Airbrake, passing a Hash as :parameters as in the example above is the most common use case. When Airbrake catches an exception in a controller, the actual HTTP client request parameters are sent using this key.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
369
1de4cf8 Update readme to reflect name change
Harold Giménez authored
370 Airbrake merges the hash you pass with these default options:
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
371
372 {
1de4cf8 Update readme to reflect name change
Harold Giménez authored
373 :api_key => Airbrake.api_key,
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
374 :error_message => 'Notification',
375 :backtrace => caller,
376 :parameters => {},
377 :session => {}
378 }
379
380 You can override any of those parameters.
381
382 ### Sending shell environment variables when "Going beyond exceptions"
383
384 One common request we see is to send shell environment variables along with
385 manual exception notification. We recommend sending them along with CGI data
386 or Rack environment (:cgi_data or :rack_env keys, respectively.)
387
1de4cf8 Update readme to reflect name change
Harold Giménez authored
388 See Airbrake::Notice#initialize in lib/airbrake/notice.rb for
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
389 more details.
390
391 Filtering
392 ---------
393
1de4cf8 Update readme to reflect name change
Harold Giménez authored
394 You can specify a whitelist of errors that Airbrake will not report on. Use
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
395 this feature when you are so apathetic to certain errors that you don't want
396 them even logged.
397
398 This filter will only be applied to automatic notifications, not manual
399 notifications (when #notify is called directly).
400
e61b1ca @bquorning README updated to reflect name change from Hoptoad to Airbrake
bquorning authored
401 Airbrake ignores the following exceptions by default:
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
402
403 ActiveRecord::RecordNotFound
404 ActionController::RoutingError
405 ActionController::InvalidAuthenticityToken
406 CGI::Session::CookieStore::TamperedWithCookie
d7d0b2a @shime Update ignored exceptions by default in readme
shime authored
407 ActionController::UnknownAction
408 AbstractController::ActionNotFound
409 Mongoid::Errors::DocumentNotFound
410
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
411
1de4cf8 Update readme to reflect name change
Harold Giménez authored
412 To ignore errors in addition to those, specify their names in your Airbrake
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
413 configuration block.
414
1de4cf8 Update readme to reflect name change
Harold Giménez authored
415 Airbrake.configure do |config|
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
416 config.api_key = '1234567890abcdef'
5dfa7fc Merge branch 'master' of github.com:thoughtbot/hoptoad_notifier
Chad Pytel authored
417 config.ignore << "ActiveRecord::IgnoreThisError"
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
418 end
419
0affe44 @dvdplm Documenting workaround for issue #39
dvdplm authored
420 To ignore *only* certain errors (and override the defaults), use the #ignore_only attribute.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
421
1de4cf8 Update readme to reflect name change
Harold Giménez authored
422 Airbrake.configure do |config|
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
423 config.api_key = '1234567890abcdef'
e6836aa @asanghi make it clear how to ignore no errors in readme.
asanghi authored
424 config.ignore_only = ["ActiveRecord::IgnoreThisError"] # or [] to ignore no exceptions.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
425 end
426
427 To ignore certain user agents, add in the #ignore_user_agent attribute as a
428 string or regexp:
429
1de4cf8 Update readme to reflect name change
Harold Giménez authored
430 Airbrake.configure do |config|
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
431 config.api_key = '1234567890abcdef'
432 config.ignore_user_agent << /Ignored/
433 config.ignore_user_agent << 'IgnoredUserAgent'
434 end
435
436 To ignore exceptions based on other conditions, use #ignore_by_filter:
437
1de4cf8 Update readme to reflect name change
Harold Giménez authored
438 Airbrake.configure do |config|
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
439 config.api_key = '1234567890abcdef'
440 config.ignore_by_filter do |exception_data|
441 true if exception_data[:error_class] == "RuntimeError"
442 end
443 end
444
e61b1ca @bquorning README updated to reflect name change from Hoptoad to Airbrake
bquorning authored
445 To replace sensitive information sent to the Airbrake service with [FILTERED] use #params_filters:
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
446
1de4cf8 Update readme to reflect name change
Harold Giménez authored
447 Airbrake.configure do |config|
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
448 config.api_key = '1234567890abcdef'
449 config.params_filters << "credit_card_number"
450 end
451
452 Note that, when rescuing exceptions within an ActionController method,
1de4cf8 Update readme to reflect name change
Harold Giménez authored
453 airbrake will reuse filters specified by #filter_parameter_logging.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
454
455 Testing
456 -------
457
1de4cf8 Update readme to reflect name change
Harold Giménez authored
458 When you run your tests, you might notice that the Airbrake service is recording
459 notices generated using #notify when you don't expect it to. You can
460 use code like this in your test_helper.rb or spec_helper.rb files to redefine
461 that method so those errors are not reported while running tests.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
462
1de4cf8 Update readme to reflect name change
Harold Giménez authored
463 module Airbrake
cd424ba Update stubbing example in README to match method signature
Greg Hurrell authored
464 def self.notify(exception, opts = {})
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
465 # do nothing.
466 end
467 end
468
469 Proxy Support
470 -------------
471
1de4cf8 Update readme to reflect name change
Harold Giménez authored
472 The notifier supports using a proxy, if your server is not able to directly reach the Airbrake servers. To configure the proxy settings, added the following information to your Airbrake configuration block.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
473
1de4cf8 Update readme to reflect name change
Harold Giménez authored
474 Airbrake.configure do |config|
d77114a @sgonyea Document proxy parameters; namely, that the proxy_host does not requi…
sgonyea authored
475 config.proxy_host = proxy.host.com
476 config.proxy_port = 4038
477 config.proxy_user = foo # optional
478 config.proxy_pass = bar # optional
ed3fcda @shime add info about logger
shime authored
479
480 Logging
481 ------------
482
483 Airbrake uses the logger from your Rails application by default, presumably STDOUT. If you don't like Airbrake scribbling to your
484 standard output, just pass another `Logger` instance inside your configuration:
485
486 Airbrake.configure do |config|
487 ...
488 config.logger = Logger.new("path/to/your/log/file")
489 end
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
490
491 Supported Rails versions
492 ------------------------
493
494 See SUPPORTED_RAILS_VERSIONS for a list of official supported versions of
495 Rails.
496
4ff45e9 @shime update explanation how we catch errors in readme
shime authored
497 Please open up a support ticket ( http://help.airbrake.io ) or submit a new github issue
498 if you're using a version of Rails that is listed above and the notifier is
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
499 not working properly.
500
501 Javascript Notifer
502 ------------------
503
a5163c7 @mjankowski first pass at changing JS html insertion into helper instead
mjankowski authored
504 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
505
1de4cf8 Update readme to reflect name change
Harold Giménez authored
506 <%= airbrake_javascript_notifier %>
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
507
a5163c7 @mjankowski first pass at changing JS html insertion into helper instead
mjankowski authored
508 It's important to insert this very high in the markup, above all other javascript. Example:
509
510 <!DOCTYPE html>
511 <html>
512 <head>
513 <meta charset="utf8">
1de4cf8 Update readme to reflect name change
Harold Giménez authored
514 <%= airbrake_javascript_notifier %>
a5163c7 @mjankowski first pass at changing JS html insertion into helper instead
mjankowski authored
515 <!-- more javascript -->
516 </head>
517 <body>
518 ...
519 </body>
520 </html>
521
522 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
523
c8a169d @leonid-shevtsov Feature: use a separate API key for Javascript notifications
leonid-shevtsov authored
524 The Javascript notifier tends to send much more notifications than the base Rails project.
525 If you want to receive them into a separate Airbrake project, specify its
526 API key in the `js_api_key` option.
527
528 config.js_api_key = 'another-projects-api-key'
529
bf0de5d @21croissants Update README.md
21croissants authored
530 To test the Javascript notifier in development environment, overwrite (temporarily) the development_environments option:
531
532 Airbrake.configure do |config|
533 # ...
534 config.development_environments = []
535 end
536
a66df64 @gabebw Mention TESTING.md in the README
gabebw authored
537 Development
538 -----------
539
540 See TESTING.md for instructions on how to run the tests.
541
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
542 Credits
543 -------
544
545 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
546
c5cd520 Updated copyright/trademarks
Jonathan Siegel authored
547 Airbrake is maintained and funded by [airbrake.io](http://airbrake.io)
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
548
506ac3d @stve Updated URL's in README
stve authored
549 Thank you to all [the contributors](https://github.com/airbrake/airbrake/contributors)!
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
550
c5cd520 Updated copyright/trademarks
Jonathan Siegel authored
551 The names and logos for Airbrake, thoughtbot are trademarks of their respective holders.
3078bdf iconvert readme to markdown and add credit and license info
Chad Pytel authored
552
553 License
554 -------
555
c5cd520 Updated copyright/trademarks
Jonathan Siegel authored
556 Airbrake is Copyright © 2008-2012 Airbrake. 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.