Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Update README.md pointing developers at new repo.

  • Loading branch information...
commit bdd920243a1ca7676433501ce6acffa717ace06e 1 parent 28cc8cd
authored October 17, 2011

Showing 1 changed file with 3 additions and 430 deletions. Show diff stats Hide diff stats

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

0 notes on commit bdd9202

Please sign in to comment.
Something went wrong with that request. Please try again.