bugsnag-maglev- 2.8.12
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.document +5 -0
- data/.gitignore +52 -0
- data/.rspec +3 -0
- data/.travis.yml +15 -0
- data/CHANGELOG.md +425 -0
- data/CONTRIBUTING.md +43 -0
- data/Gemfile +2 -0
- data/LICENSE.txt +20 -0
- data/README.md +804 -0
- data/Rakefile +29 -0
- data/VERSION +1 -0
- data/bugsnag.gemspec +32 -0
- data/lib/bugsnag.rb +129 -0
- data/lib/bugsnag/capistrano.rb +7 -0
- data/lib/bugsnag/capistrano2.rb +32 -0
- data/lib/bugsnag/configuration.rb +129 -0
- data/lib/bugsnag/delay/resque.rb +21 -0
- data/lib/bugsnag/delayed_job.rb +57 -0
- data/lib/bugsnag/delivery.rb +18 -0
- data/lib/bugsnag/delivery/synchronous.rb +51 -0
- data/lib/bugsnag/delivery/thread_queue.rb +53 -0
- data/lib/bugsnag/deploy.rb +35 -0
- data/lib/bugsnag/helpers.rb +127 -0
- data/lib/bugsnag/mailman.rb +28 -0
- data/lib/bugsnag/meta_data.rb +7 -0
- data/lib/bugsnag/middleware/callbacks.rb +19 -0
- data/lib/bugsnag/middleware/mailman.rb +13 -0
- data/lib/bugsnag/middleware/rack_request.rb +72 -0
- data/lib/bugsnag/middleware/rails2_request.rb +52 -0
- data/lib/bugsnag/middleware/rails3_request.rb +42 -0
- data/lib/bugsnag/middleware/rake.rb +23 -0
- data/lib/bugsnag/middleware/sidekiq.rb +13 -0
- data/lib/bugsnag/middleware/warden_user.rb +39 -0
- data/lib/bugsnag/middleware_stack.rb +98 -0
- data/lib/bugsnag/notification.rb +452 -0
- data/lib/bugsnag/rack.rb +53 -0
- data/lib/bugsnag/rails.rb +66 -0
- data/lib/bugsnag/rails/action_controller_rescue.rb +62 -0
- data/lib/bugsnag/rails/active_record_rescue.rb +20 -0
- data/lib/bugsnag/rails/controller_methods.rb +44 -0
- data/lib/bugsnag/railtie.rb +78 -0
- data/lib/bugsnag/rake.rb +25 -0
- data/lib/bugsnag/resque.rb +40 -0
- data/lib/bugsnag/sidekiq.rb +38 -0
- data/lib/bugsnag/tasks.rb +3 -0
- data/lib/bugsnag/tasks/bugsnag.cap +48 -0
- data/lib/bugsnag/tasks/bugsnag.rake +89 -0
- data/lib/bugsnag/version.rb +3 -0
- data/lib/generators/bugsnag/bugsnag_generator.rb +24 -0
- data/rails/init.rb +3 -0
- data/spec/code_spec.rb +86 -0
- data/spec/fixtures/crashes/end_of_file.rb +9 -0
- data/spec/fixtures/crashes/short_file.rb +1 -0
- data/spec/fixtures/crashes/start_of_file.rb +9 -0
- data/spec/fixtures/middleware/internal_info_setter.rb +11 -0
- data/spec/fixtures/middleware/public_info_setter.rb +11 -0
- data/spec/fixtures/tasks/Rakefile +15 -0
- data/spec/helper_spec.rb +144 -0
- data/spec/integration_spec.rb +110 -0
- data/spec/middleware_spec.rb +181 -0
- data/spec/notification_spec.rb +822 -0
- data/spec/rack_spec.rb +56 -0
- data/spec/spec_helper.rb +53 -0
- metadata +198 -0
data/CONTRIBUTING.md
ADDED
@@ -0,0 +1,43 @@
|
|
1
|
+
|
2
|
+
## How to contribute
|
3
|
+
|
4
|
+
- [Fork](https://help.github.com/articles/fork-a-repo) the [notifier on github](https://github.com/bugsnag/bugsnag-ruby)
|
5
|
+
- Commit and push until you are happy with your contribution
|
6
|
+
- Run the tests with and make sure they all pass
|
7
|
+
|
8
|
+
```
|
9
|
+
rake spec
|
10
|
+
```
|
11
|
+
|
12
|
+
- [Make a pull request](https://help.github.com/articles/using-pull-requests)
|
13
|
+
- Thanks!
|
14
|
+
|
15
|
+
|
16
|
+
## How to release
|
17
|
+
|
18
|
+
If you're a member of the core team, follow these instructions for releasing bugsnag-ruby.
|
19
|
+
|
20
|
+
### First time setup
|
21
|
+
|
22
|
+
* Create a Rubygems account
|
23
|
+
* Get James/Simon to add you as contributor on bugsnag-ruby in Rubygems
|
24
|
+
|
25
|
+
### Every time
|
26
|
+
|
27
|
+
* Update `VERSION`
|
28
|
+
* Update `CHANGELOG.md`
|
29
|
+
* Update `README.md` if necessary
|
30
|
+
* Commit/push your changes
|
31
|
+
|
32
|
+
```
|
33
|
+
git commit -am v2.X.X
|
34
|
+
git push origin master
|
35
|
+
```
|
36
|
+
|
37
|
+
* Release to rubygems
|
38
|
+
|
39
|
+
```
|
40
|
+
bundle exec rake release
|
41
|
+
```
|
42
|
+
|
43
|
+
* Update the version running in the bugsnag-website project
|
data/Gemfile
ADDED
data/LICENSE.txt
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
Copyright (c) 2012 Bugsnag
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
4
|
+
a copy of this software and associated documentation files (the
|
5
|
+
"Software"), to deal in the Software without restriction, including
|
6
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
7
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
+
permit persons to whom the Software is furnished to do so, subject to
|
9
|
+
the following conditions:
|
10
|
+
|
11
|
+
The above copyright notice and this permission notice shall be
|
12
|
+
included in all copies or substantial portions of the Software.
|
13
|
+
|
14
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
15
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
16
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
17
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
18
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
19
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
20
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,804 @@
|
|
1
|
+
Bugsnag Notifier for Ruby
|
2
|
+
=========================
|
3
|
+
|
4
|
+
The Bugsnag Notifier for Ruby gives you instant notification of exceptions
|
5
|
+
thrown from your **Rails**, **Sinatra**, **Rack** or **plain Ruby** app.
|
6
|
+
Any uncaught exceptions will trigger a notification to be sent to your
|
7
|
+
Bugsnag project.
|
8
|
+
|
9
|
+
[Bugsnag](http://bugsnag.com) captures errors in real-time from your web,
|
10
|
+
mobile and desktop applications, helping you to understand and resolve them
|
11
|
+
as fast as possible. [Create a free account](http://bugsnag.com) to start
|
12
|
+
capturing exceptions from your applications.
|
13
|
+
|
14
|
+
|
15
|
+
Contents
|
16
|
+
--------
|
17
|
+
|
18
|
+
- [How to Install](#how-to-install)
|
19
|
+
- [Sending Custom Data With Exceptions](#sending-custom-data-with-exceptions)
|
20
|
+
- [Sending Handled Exceptions](#sending-handled-exceptions)
|
21
|
+
- [Configuration](#configuration)
|
22
|
+
- [Bugsnag Middleware](#bugsnag-middleware)
|
23
|
+
- [Deploy Tracking](#deploy-tracking)
|
24
|
+
- [EventMachine Apps](#eventmachine-apps)
|
25
|
+
- [Demo Applications](#demo-applications)
|
26
|
+
|
27
|
+
How to Install
|
28
|
+
--------------
|
29
|
+
|
30
|
+
1. Add the `bugsnag` gem to your `Gemfile`
|
31
|
+
|
32
|
+
```ruby
|
33
|
+
gem "bugsnag"
|
34
|
+
```
|
35
|
+
|
36
|
+
2. Install the gem
|
37
|
+
|
38
|
+
```shell
|
39
|
+
bundle install
|
40
|
+
```
|
41
|
+
|
42
|
+
3. Configure the Bugsnag module with your API key.
|
43
|
+
|
44
|
+
**Rails**: Use our generator
|
45
|
+
|
46
|
+
```shell
|
47
|
+
rails generate bugsnag YOUR_API_KEY_HERE
|
48
|
+
```
|
49
|
+
|
50
|
+
**Other Ruby/Rack/Sinatra apps**: Put this snippet in your initialization.
|
51
|
+
|
52
|
+
```ruby
|
53
|
+
Bugsnag.configure do |config|
|
54
|
+
config.api_key = "YOUR_API_KEY_HERE"
|
55
|
+
end
|
56
|
+
```
|
57
|
+
|
58
|
+
The Bugsnag module will read the `BUGSNAG_API_KEY` environment variable if you
|
59
|
+
do not configure one automatically.
|
60
|
+
|
61
|
+
4. **Rack/Sinatra apps only**: Activate the Bugsnag Rack middleware
|
62
|
+
|
63
|
+
```ruby
|
64
|
+
use Bugsnag::Rack
|
65
|
+
```
|
66
|
+
|
67
|
+
**Sinatra**: Note that `raise_errors` must be enabled. If you are using custom
|
68
|
+
error handlers, then you will need to notify Bugsnag explicitly:
|
69
|
+
|
70
|
+
```ruby
|
71
|
+
error 500 do
|
72
|
+
Bugsnag.auto_notify($!)
|
73
|
+
erb :"errors/500"
|
74
|
+
end
|
75
|
+
```
|
76
|
+
|
77
|
+
Sending Custom Data With Exceptions
|
78
|
+
-----------------------------------
|
79
|
+
|
80
|
+
It is often useful to send additional meta-data about your app, such as
|
81
|
+
information about the currently logged in user, along with any
|
82
|
+
exceptions, to help debug problems.
|
83
|
+
|
84
|
+
### Rails Apps
|
85
|
+
|
86
|
+
By default Bugsnag includes some information automatically. For example, we
|
87
|
+
send all the HTTP headers for requests. Additionally if you're using Warden or
|
88
|
+
Devise, the id, name and email of the current user are sent.
|
89
|
+
|
90
|
+
To send additional information, in any rails controller you can define a `before_bugsnag_notify` callback, which allows you to add this additional data by calling `add_tab` on the exception notification object. Please see the [Notification Object](#notification-object) for details on the notification parameter.
|
91
|
+
|
92
|
+
```ruby
|
93
|
+
class MyController < ApplicationController
|
94
|
+
# Define the filter
|
95
|
+
before_bugsnag_notify :add_user_info_to_bugsnag
|
96
|
+
|
97
|
+
# Your controller code here
|
98
|
+
|
99
|
+
private
|
100
|
+
def add_user_info_to_bugsnag(notif)
|
101
|
+
# Set the user that this bug affected
|
102
|
+
# Email, name and id are searchable on bugsnag.com
|
103
|
+
notif.user = {
|
104
|
+
email: current_user.email,
|
105
|
+
name: current_user.name,
|
106
|
+
id: current_user.id
|
107
|
+
}
|
108
|
+
|
109
|
+
# Add some app-specific data which will be displayed on a custom
|
110
|
+
# "Diagnostics" tab on each error page on bugsnag.com
|
111
|
+
notif.add_tab(:diagnostics, {
|
112
|
+
product: current_product.name
|
113
|
+
})
|
114
|
+
end
|
115
|
+
end
|
116
|
+
```
|
117
|
+
|
118
|
+
### Rails API Apps
|
119
|
+
|
120
|
+
If you are building an API using the [rails-api](https://github.com/rails-api/rails-api) gem, your controllers will inherit from `ActionController::API` instead of `ActionController::Base`.
|
121
|
+
|
122
|
+
In this case, the `before_bugsnag_notify` filter will not be automatically available in your controllers. In order to use it, you will need to include the module `Bugsnag::Rails::ControllerMethods`.
|
123
|
+
|
124
|
+
```ruby
|
125
|
+
class ApplicationController < ActionController::API
|
126
|
+
|
127
|
+
# Include module which defines the before_bugsnag_notify filter
|
128
|
+
include Bugsnag::Rails::ControllerMethods
|
129
|
+
|
130
|
+
# Other code here
|
131
|
+
end
|
132
|
+
```
|
133
|
+
|
134
|
+
### Other Ruby Apps
|
135
|
+
|
136
|
+
In other ruby apps, you can provide lambda functions to execute before any `Bugsnag.notify` calls as follows. Don't forget to clear the callbacks at the end of each request or session. In Rack applications like Sinatra, this is automatically done for you.
|
137
|
+
|
138
|
+
```ruby
|
139
|
+
# Set a before notify callback
|
140
|
+
Bugsnag.before_notify_callbacks << lambda {|notif|
|
141
|
+
notif.add_tab(:user_info, {
|
142
|
+
name: current_user.name
|
143
|
+
})
|
144
|
+
}
|
145
|
+
|
146
|
+
# Your app code here
|
147
|
+
|
148
|
+
# Clear the callbacks
|
149
|
+
Bugsnag.before_notify_callbacks.clear
|
150
|
+
```
|
151
|
+
|
152
|
+
### Notification Object
|
153
|
+
|
154
|
+
The notification object is passed to all [before bugsnag notify](#sending-custom-data-with-exceptions) callbacks and is used to manipulate the error report before it is transmitted.
|
155
|
+
|
156
|
+
#### add_tab
|
157
|
+
|
158
|
+
Call add_tab on a notification object to add a tab to the error report so that it would appear on your dashboard.
|
159
|
+
|
160
|
+
```ruby
|
161
|
+
notif.add_tab(:user_info, {
|
162
|
+
name: current_user.name
|
163
|
+
})
|
164
|
+
```
|
165
|
+
|
166
|
+
The first parameter is the tab name that will appear in the error report and the second is the key, value list that will be displayed in the tab.
|
167
|
+
|
168
|
+
#### remove_tab
|
169
|
+
|
170
|
+
Removes a tab completely from the error report
|
171
|
+
|
172
|
+
```ruby
|
173
|
+
notif.remove_tab(:request)
|
174
|
+
```
|
175
|
+
|
176
|
+
#### ignore!
|
177
|
+
|
178
|
+
Calling ignore! on a notification object will cause the notification to not be sent to bugsnag. This means that you can choose dynamically not to send an error depending on application state or the error itself.
|
179
|
+
|
180
|
+
```ruby
|
181
|
+
notif.ignore! if foo == 'bar'
|
182
|
+
```
|
183
|
+
|
184
|
+
#### grouping_hash
|
185
|
+
|
186
|
+
Sets the grouping hash of the error report. All errors with the same grouping hash are grouped together. This is an advanced usage of the library and mis-using it will cause your errors not to group properly in your dashboard.
|
187
|
+
|
188
|
+
```ruby
|
189
|
+
notif.grouping_hash = "#{exception.message}#{exception.class}"
|
190
|
+
```
|
191
|
+
|
192
|
+
#### severity
|
193
|
+
|
194
|
+
Set the severity of the error. Severity can be `error`, `warning` or `info`.
|
195
|
+
|
196
|
+
```ruby
|
197
|
+
notif.severity = "error"
|
198
|
+
```
|
199
|
+
|
200
|
+
#### context
|
201
|
+
|
202
|
+
Set the context of the error report. This is notionally the location of the error and should be populated automatically. Context is displayed in the dashboard prominently.
|
203
|
+
|
204
|
+
```ruby
|
205
|
+
notif.context = "billing"
|
206
|
+
```
|
207
|
+
|
208
|
+
#### user
|
209
|
+
|
210
|
+
You can set or read the user with the user property of the notification. The user will be a hash of `email`, `id` and `name`.
|
211
|
+
|
212
|
+
```ruby
|
213
|
+
notif.user = {
|
214
|
+
id: current_user.id,
|
215
|
+
email: current_user.email,
|
216
|
+
name: current_user.name
|
217
|
+
}
|
218
|
+
```
|
219
|
+
|
220
|
+
#### exceptions
|
221
|
+
|
222
|
+
Allows you to read the exceptions that will be combined into the report.
|
223
|
+
|
224
|
+
```ruby
|
225
|
+
puts "#{notif.exceptions.first.message} found!"
|
226
|
+
```
|
227
|
+
|
228
|
+
#### meta_data
|
229
|
+
|
230
|
+
Provides access to the meta_data in the error report.
|
231
|
+
|
232
|
+
```ruby
|
233
|
+
notif.ignore! if notif.meta_data[:sidekiq][:retry_count] > 2
|
234
|
+
```
|
235
|
+
|
236
|
+
### Exceptions with Meta Data
|
237
|
+
|
238
|
+
If you include the `Bugsnag::MetaData` module into your own exceptions, you can
|
239
|
+
associate meta data with a particular exception.
|
240
|
+
|
241
|
+
```ruby
|
242
|
+
class MyCustomException < Exception
|
243
|
+
include Bugsnag::MetaData
|
244
|
+
end
|
245
|
+
|
246
|
+
exception = MyCustomException.new("It broke!")
|
247
|
+
exception.bugsnag_meta_data = {
|
248
|
+
:user_info => {
|
249
|
+
name: current_user.name
|
250
|
+
}
|
251
|
+
}
|
252
|
+
|
253
|
+
raise exception
|
254
|
+
```
|
255
|
+
|
256
|
+
You can read more about how callbacks work in the
|
257
|
+
[Bugsnag Middleware](#bugsnag-middleware) documentation below.
|
258
|
+
|
259
|
+
|
260
|
+
Sending Handled Exceptions
|
261
|
+
----------------------------
|
262
|
+
|
263
|
+
If you would like to send non-fatal exceptions to Bugsnag, you can call
|
264
|
+
`Bugsnag.notify`:
|
265
|
+
|
266
|
+
```ruby
|
267
|
+
Bugsnag.notify(RuntimeError.new("Something broke"))
|
268
|
+
```
|
269
|
+
|
270
|
+
### Custom Data
|
271
|
+
|
272
|
+
You can also send additional meta-data with your exception:
|
273
|
+
|
274
|
+
```ruby
|
275
|
+
Bugsnag.notify(RuntimeError.new("Something broke"), {
|
276
|
+
:user => {
|
277
|
+
:username => "bob-hoskins",
|
278
|
+
:registered_user => true
|
279
|
+
}
|
280
|
+
})
|
281
|
+
```
|
282
|
+
|
283
|
+
### Severity
|
284
|
+
|
285
|
+
You can set the severity of an error in Bugsnag by including the severity option when
|
286
|
+
notifying bugsnag of the error,
|
287
|
+
|
288
|
+
```ruby
|
289
|
+
Bugsnag.notify(RuntimeError.new("Something broke"), {
|
290
|
+
:severity => "error",
|
291
|
+
})
|
292
|
+
```
|
293
|
+
|
294
|
+
Valid severities are `error`, `warning` and `info`.
|
295
|
+
|
296
|
+
Severity is displayed in the dashboard and can be used to filter the error list.
|
297
|
+
By default all crashes (or unhandled exceptions) are set to `error` and all
|
298
|
+
`Bugsnag.notify` calls default to `warning`.
|
299
|
+
|
300
|
+
Rake Integration
|
301
|
+
----------------
|
302
|
+
|
303
|
+
Rake integration is automatically enabled in Rails 3/4 apps, so providing you load the environment
|
304
|
+
in your Rake tasks you dont need to do anything to get Rake support. If you choose not to load
|
305
|
+
your environment, you can manually configure Bugsnag with a `bugsnag.configure` block in the Rakefile.
|
306
|
+
|
307
|
+
Bugsnag can automatically notify of all exceptions that happen in your rake tasks. In order
|
308
|
+
to enable this, you need to `require "bugsnag/rake"` in your Rakefile, like so:
|
309
|
+
|
310
|
+
```ruby
|
311
|
+
require File.expand_path('../config/application', __FILE__)
|
312
|
+
require 'rake'
|
313
|
+
require "bugsnag/rake"
|
314
|
+
|
315
|
+
Bugsnag.configure do |config|
|
316
|
+
config.api_key = "YOUR_API_KEY_HERE"
|
317
|
+
end
|
318
|
+
|
319
|
+
YourApp::Application.load_tasks
|
320
|
+
```
|
321
|
+
|
322
|
+
> Note: We also configure Bugsnag in the Rakefile, so the tasks that do not load the full
|
323
|
+
environment can still notify Bugsnag.
|
324
|
+
|
325
|
+
Standard Ruby Scripts
|
326
|
+
---------------------
|
327
|
+
|
328
|
+
If you are running a standard ruby script, you can ensure that all exceptions are sent to Bugsnag by
|
329
|
+
adding the following code to your app:
|
330
|
+
|
331
|
+
```ruby
|
332
|
+
at_exit do
|
333
|
+
if $!
|
334
|
+
Bugsnag.notify($!)
|
335
|
+
end
|
336
|
+
end
|
337
|
+
```
|
338
|
+
|
339
|
+
Testing Integration
|
340
|
+
-------------------
|
341
|
+
|
342
|
+
To test that bugsnag is properly configured, you can use the test_exception rake task like this,
|
343
|
+
|
344
|
+
```bash
|
345
|
+
rake bugsnag:test_exception
|
346
|
+
```
|
347
|
+
|
348
|
+
A test exception will be sent to your bugsnag dashboard if everything is configured correctly.
|
349
|
+
|
350
|
+
Configuration
|
351
|
+
-------------
|
352
|
+
|
353
|
+
To configure additional Bugsnag settings, use the block syntax and set any
|
354
|
+
settings you need on the `config` block variable. For example:
|
355
|
+
|
356
|
+
```ruby
|
357
|
+
Bugsnag.configure do |config|
|
358
|
+
config.api_key = "your-api-key-here"
|
359
|
+
config.notify_release_stages = ["production", "development"]
|
360
|
+
end
|
361
|
+
```
|
362
|
+
|
363
|
+
###api_key
|
364
|
+
|
365
|
+
Your Bugsnag API key (required).
|
366
|
+
|
367
|
+
```ruby
|
368
|
+
config.api_key = "your-api-key-here"
|
369
|
+
```
|
370
|
+
|
371
|
+
###release_stage
|
372
|
+
|
373
|
+
If you would like to distinguish between errors that happen in different
|
374
|
+
stages of the application release process (development, production, etc)
|
375
|
+
you can set the `release_stage` that is reported to Bugsnag.
|
376
|
+
|
377
|
+
```ruby
|
378
|
+
config.release_stage = "development"
|
379
|
+
```
|
380
|
+
|
381
|
+
In rails apps this value is automatically set from `RAILS_ENV`, and in rack
|
382
|
+
apps it is automatically set to `RACK_ENV`. Otherwise the default is
|
383
|
+
"production".
|
384
|
+
|
385
|
+
###notify_release_stages
|
386
|
+
|
387
|
+
By default, we will notify Bugsnag of exceptions that happen in any
|
388
|
+
`release_stage`. If you would like to change which release stages
|
389
|
+
notify Bugsnag of exceptions you can set `notify_release_stages`:
|
390
|
+
|
391
|
+
```ruby
|
392
|
+
config.notify_release_stages = ["production", "development"]
|
393
|
+
```
|
394
|
+
|
395
|
+
###endpoint
|
396
|
+
|
397
|
+
By default, we'll send crashes to *notify.bugsnag.com* to display them on
|
398
|
+
your dashboard. If you are using *Bugsnag Enterprise* you'll need to set
|
399
|
+
this to be your *Event Server* endpoint, for example:
|
400
|
+
|
401
|
+
```ruby
|
402
|
+
config.endpoint = "bugsnag.example.com:49000"
|
403
|
+
```
|
404
|
+
|
405
|
+
###auto_notify
|
406
|
+
|
407
|
+
By default, we will automatically notify Bugsnag of any fatal exceptions
|
408
|
+
in your application. If you want to stop this from happening, you can set
|
409
|
+
`auto_notify`:
|
410
|
+
|
411
|
+
```ruby
|
412
|
+
config.auto_notify = false
|
413
|
+
```
|
414
|
+
|
415
|
+
###use_ssl
|
416
|
+
|
417
|
+
Enforces all communication with bugsnag.com be made via ssl. You can turn
|
418
|
+
this off if necessary.
|
419
|
+
|
420
|
+
```ruby
|
421
|
+
config.use_ssl = false
|
422
|
+
```
|
423
|
+
|
424
|
+
By default, `use_ssl` is set to true.
|
425
|
+
|
426
|
+
<!-- Custom anchor for linking from alerts -->
|
427
|
+
<div id="set-project-root"></div>
|
428
|
+
###project_root
|
429
|
+
|
430
|
+
We mark stacktrace lines as `inProject` if they come from files inside your
|
431
|
+
`project_root`. In rails apps this value is automatically set to `RAILS_ROOT`,
|
432
|
+
otherwise you should set it manually:
|
433
|
+
|
434
|
+
```ruby
|
435
|
+
config.project_root = "/var/www/myproject"
|
436
|
+
```
|
437
|
+
|
438
|
+
###app_version
|
439
|
+
|
440
|
+
If you want to track which versions of your application each exception
|
441
|
+
happens in, you can set `app_version`. This is set to `nil` by default.
|
442
|
+
|
443
|
+
```ruby
|
444
|
+
config.app_version = "2.5.1"
|
445
|
+
```
|
446
|
+
|
447
|
+
###params_filters
|
448
|
+
|
449
|
+
Sets which keys should be filtered out from `params` hashes before sending
|
450
|
+
them to Bugsnag. Use this if you want to ensure you don't send sensitive data
|
451
|
+
such as passwords, and credit card numbers to our servers. You can add both
|
452
|
+
strings and regular expressions to this array. When adding strings, keys which
|
453
|
+
*contain* the string will be filtered. When adding regular expressions, any
|
454
|
+
keys which *match* the regular expression will be filtered.
|
455
|
+
|
456
|
+
```ruby
|
457
|
+
config.params_filters += ["credit_card_number", /^password$/]
|
458
|
+
```
|
459
|
+
|
460
|
+
By default, `params_filters` is set to `[/authorization/i, /cookie/i,
|
461
|
+
/password/i, /secret/i]`, and for rails apps, imports all values from
|
462
|
+
`Rails.configuration.filter_parameters`.
|
463
|
+
|
464
|
+
###ignore_classes
|
465
|
+
|
466
|
+
Sets for which exception classes we should not send exceptions to bugsnag.com.
|
467
|
+
|
468
|
+
```ruby
|
469
|
+
config.ignore_classes << "ActiveRecord::StatementInvalid"
|
470
|
+
```
|
471
|
+
|
472
|
+
You can also provide a lambda function here to ignore by other exception
|
473
|
+
attributes or by a regex:
|
474
|
+
|
475
|
+
```ruby
|
476
|
+
config.ignore_classes << lambda {|ex| ex.message =~ /timeout/}
|
477
|
+
```
|
478
|
+
|
479
|
+
By default, `ignore_classes` contains the following:
|
480
|
+
|
481
|
+
```ruby
|
482
|
+
[
|
483
|
+
"ActiveRecord::RecordNotFound",
|
484
|
+
"ActionController::RoutingError",
|
485
|
+
"ActionController::InvalidAuthenticityToken",
|
486
|
+
"CGI::Session::CookieStore::TamperedWithCookie",
|
487
|
+
"ActionController::UnknownAction",
|
488
|
+
"AbstractController::ActionNotFound"
|
489
|
+
]
|
490
|
+
```
|
491
|
+
|
492
|
+
###ignore_user_agents
|
493
|
+
|
494
|
+
Sets an array of Regexps that can be used to ignore exceptions from
|
495
|
+
certain user agents.
|
496
|
+
|
497
|
+
```ruby
|
498
|
+
config.ignore_user_agents << %r{Chrome}
|
499
|
+
```
|
500
|
+
|
501
|
+
By default, `ignore_user_agents` is empty, so exceptions caused by all
|
502
|
+
user agents are reported.
|
503
|
+
|
504
|
+
###proxy_host
|
505
|
+
|
506
|
+
Sets the address of the HTTP proxy that should be used for requests to bugsnag.
|
507
|
+
|
508
|
+
```ruby
|
509
|
+
config.proxy_host = "10.10.10.10"
|
510
|
+
```
|
511
|
+
|
512
|
+
###proxy_port
|
513
|
+
|
514
|
+
Sets the port of the HTTP proxy that should be used for requests to bugsnag.
|
515
|
+
|
516
|
+
```ruby
|
517
|
+
config.proxy_port = 1089
|
518
|
+
```
|
519
|
+
|
520
|
+
###proxy_user
|
521
|
+
|
522
|
+
Sets the user that should be used to send requests to the HTTP proxy for requests to bugsnag.
|
523
|
+
|
524
|
+
```ruby
|
525
|
+
config.proxy_user = "proxy_user"
|
526
|
+
```
|
527
|
+
|
528
|
+
###proxy_password
|
529
|
+
|
530
|
+
Sets the password for the user that should be used to send requests to the HTTP proxy for requests to bugsnag.
|
531
|
+
|
532
|
+
```ruby
|
533
|
+
config.proxy_password = "proxy_secret_password_here"
|
534
|
+
```
|
535
|
+
|
536
|
+
###timeout
|
537
|
+
By default the timeout for posting errors to Bugsnag is 15 seconds, to change this
|
538
|
+
you can set the `timeout`:
|
539
|
+
|
540
|
+
```ruby
|
541
|
+
config.timeout = 10
|
542
|
+
```
|
543
|
+
|
544
|
+
###logger
|
545
|
+
|
546
|
+
Sets which logger to use for Bugsnag log messages. In rails apps, this is
|
547
|
+
automatically set to use `Rails.logger`, otherwise it will be set to
|
548
|
+
`Logger.new(STDOUT)`.
|
549
|
+
|
550
|
+
###middleware
|
551
|
+
|
552
|
+
Provides access to the middleware stack, see the
|
553
|
+
[Bugsnag Middleware](#bugsnag-middleware) section below for details.
|
554
|
+
|
555
|
+
###app_type
|
556
|
+
|
557
|
+
You can set the type of application executing the current code by using `app_type`:
|
558
|
+
|
559
|
+
```ruby
|
560
|
+
config.app_type = "resque"
|
561
|
+
```
|
562
|
+
|
563
|
+
This is usually used to represent if you are running in a Rails server, Sidekiq job or
|
564
|
+
Rake task for example. Bugsnag will automatically detect most application types for you.
|
565
|
+
|
566
|
+
###send_environment
|
567
|
+
|
568
|
+
Bugsnag can transmit your rack environment to help diagnose issues. This environment
|
569
|
+
can sometimes contain private information so Bugsnag does not transmit by default. To
|
570
|
+
send your rack environment, set the `send_environment` option to `true`.
|
571
|
+
|
572
|
+
```ruby
|
573
|
+
config.send_environment = true
|
574
|
+
```
|
575
|
+
|
576
|
+
###send_code
|
577
|
+
|
578
|
+
Bugsnag automatically sends a small snippet of the code that crashed to help you diagnose
|
579
|
+
even faster from within your dashboard. If you don't want to send this snippet you can
|
580
|
+
set the `send_code` option to `false`.
|
581
|
+
|
582
|
+
```ruby
|
583
|
+
config.send_code = false
|
584
|
+
```
|
585
|
+
|
586
|
+
Bugsnag Middleware
|
587
|
+
------------------
|
588
|
+
|
589
|
+
The Bugsnag Notifier for Ruby provides its own middleware system, similar to
|
590
|
+
the one used in Rack applications. Middleware allows you to execute code
|
591
|
+
before and after an exception is sent to bugsnag.com, so you can do things
|
592
|
+
such as:
|
593
|
+
|
594
|
+
- Send application-specific information along with exceptions, eg. the name
|
595
|
+
of the currently logged in user,
|
596
|
+
- Write exception information to your internal logging system.
|
597
|
+
|
598
|
+
To make your own middleware, create a class that looks like this:
|
599
|
+
|
600
|
+
```ruby
|
601
|
+
class MyMiddleware
|
602
|
+
def initialize(bugsnag)
|
603
|
+
@bugsnag = bugsnag
|
604
|
+
end
|
605
|
+
|
606
|
+
def call(notification)
|
607
|
+
# Your custom "before notify" code
|
608
|
+
|
609
|
+
@bugsnag.call(notification)
|
610
|
+
|
611
|
+
# Your custom "after notify" code
|
612
|
+
end
|
613
|
+
end
|
614
|
+
```
|
615
|
+
|
616
|
+
You can then add your middleware to the middleware stack as follows:
|
617
|
+
|
618
|
+
```ruby
|
619
|
+
Bugsnag.configure do |config|
|
620
|
+
config.middleware.use MyMiddleware
|
621
|
+
end
|
622
|
+
```
|
623
|
+
|
624
|
+
You can also view the order of the currently activated middleware by running `rake bugsnag:middleware`.
|
625
|
+
|
626
|
+
Check out Bugsnag's [built in middleware classes](https://github.com/bugsnag/bugsnag-ruby/tree/master/lib/bugsnag/middleware)
|
627
|
+
for some real examples of middleware in action.
|
628
|
+
|
629
|
+
### Multiple projects
|
630
|
+
|
631
|
+
If you want to divide errors into multiple Bugsnag projects, you can specify the API key as a parameter to `Bugsnag.notify`:
|
632
|
+
|
633
|
+
```ruby
|
634
|
+
rescue => e
|
635
|
+
Bugsnag.notify e, api_key: "your-api-key-here"
|
636
|
+
end
|
637
|
+
```
|
638
|
+
|
639
|
+
### Grouping hash
|
640
|
+
|
641
|
+
If you want to override Bugsnag's grouping algorithm, you can specify a grouping hash key as a parameter to `Bugsnag.notify`:
|
642
|
+
|
643
|
+
```ruby
|
644
|
+
rescue => e
|
645
|
+
Bugsnag.notify e, grouping_hash: "this-is-my-grouping-hash"
|
646
|
+
end
|
647
|
+
```
|
648
|
+
|
649
|
+
All errors with the same groupingHash will be grouped together within the bugsnag dashboard.
|
650
|
+
|
651
|
+
|
652
|
+
Deploy Tracking
|
653
|
+
---------------
|
654
|
+
|
655
|
+
Bugsnag allows you to track deploys of your apps. By sending the
|
656
|
+
source revision or application version to bugsnag.com when you deploy a new
|
657
|
+
version of your app, you'll be able to see which deploy each error was
|
658
|
+
introduced in.
|
659
|
+
|
660
|
+
### Using Heroku
|
661
|
+
|
662
|
+
You can easily add Bugsnag deploy tracking to your Heroku application by
|
663
|
+
running the following command from your application's directory:
|
664
|
+
|
665
|
+
```shell
|
666
|
+
$ bundle exec rake bugsnag:heroku:add_deploy_hook
|
667
|
+
```
|
668
|
+
|
669
|
+
If you have multiple Heroku apps, you can specify which app to add the hook
|
670
|
+
for as with the `HEROKU_APP` environment variable:
|
671
|
+
|
672
|
+
```shell
|
673
|
+
$ bundle exec rake bugsnag:heroku:add_deploy_hook HEROKU_APP=my-app
|
674
|
+
```
|
675
|
+
|
676
|
+
### Using Capistrano
|
677
|
+
|
678
|
+
If you use [capistrano](https://github.com/capistrano/capistrano) to deploy
|
679
|
+
your apps, you can enable deploy tracking by adding the integration to your
|
680
|
+
app's `deploy.rb`:
|
681
|
+
|
682
|
+
```ruby
|
683
|
+
require "bugsnag/capistrano"
|
684
|
+
|
685
|
+
set :bugsnag_api_key, "api_key_here"
|
686
|
+
```
|
687
|
+
|
688
|
+
### Using Rake
|
689
|
+
|
690
|
+
If you aren't using capistrano, you can run the following rake command from
|
691
|
+
your deploy scripts.
|
692
|
+
|
693
|
+
```shell
|
694
|
+
rake bugsnag:deploy BUGSNAG_REVISION=source-control-revision BUGSNAG_RELEASE_STAGE=production BUGSNAG_API_KEY=api-key-here
|
695
|
+
```
|
696
|
+
|
697
|
+
The bugsnag rake tasks will be automatically available for Rails 3/4
|
698
|
+
apps, to make the rake tasks available in other apps, add the following to
|
699
|
+
your `Rakefile`:
|
700
|
+
|
701
|
+
```ruby
|
702
|
+
require "bugsnag/tasks"
|
703
|
+
```
|
704
|
+
|
705
|
+
### Configuring Deploy Tracking
|
706
|
+
|
707
|
+
You can set the following environmental variables to override or specify
|
708
|
+
additional deploy information:
|
709
|
+
|
710
|
+
- **BUGSNAG_API_KEY** -
|
711
|
+
Your Bugsnag API key (required).
|
712
|
+
- **BUGSNAG_RELEASE_STAGE** -
|
713
|
+
The release stage (eg, production, staging) currently being deployed.
|
714
|
+
This is set automatically from your Bugsnag settings or rails/rack
|
715
|
+
environment.
|
716
|
+
- **BUGSNAG_REPOSITORY** -
|
717
|
+
The repository from which you are deploying the code. This is set
|
718
|
+
automatically if you are using capistrano.
|
719
|
+
- **BUGSNAG_BRANCH** -
|
720
|
+
The source control branch from which you are deploying the code.
|
721
|
+
This is set automatically if you are using capistrano.
|
722
|
+
- **BUGSNAG_REVISION** -
|
723
|
+
The source control revision for the code you are currently deploying.
|
724
|
+
This is set automatically if you are using capistrano.
|
725
|
+
- **BUGSNAG_APP_VERSION** -
|
726
|
+
The app version of the code you are currently deploying. Only set this
|
727
|
+
if you tag your releases with [semantic version numbers](http://semver.org/)
|
728
|
+
and deploy infrequently.
|
729
|
+
|
730
|
+
For more information, check out the [deploy tracking api](https://bugsnag.com/docs/deploy-tracking-api)
|
731
|
+
documentation.
|
732
|
+
|
733
|
+
|
734
|
+
EventMachine Apps
|
735
|
+
-----------------
|
736
|
+
|
737
|
+
If your app uses [EventMachine](http://rubyeventmachine.com/) you'll need to
|
738
|
+
manually notify Bugsnag of errors. There are two ways to do this in your
|
739
|
+
EventMachine apps, first you should implement `EventMachine.error_handler`:
|
740
|
+
|
741
|
+
```ruby
|
742
|
+
EventMachine.error_handler{|e|
|
743
|
+
Bugsnag.notify(e)
|
744
|
+
}
|
745
|
+
```
|
746
|
+
|
747
|
+
If you want more fine-grained error handling, you can use the
|
748
|
+
[errback](http://eventmachine.rubyforge.org/EventMachine/Deferrable.html#errback-instance_method)
|
749
|
+
function, for example:
|
750
|
+
|
751
|
+
```ruby
|
752
|
+
EventMachine::run do
|
753
|
+
server = EventMachine::start_server('0.0.0.0', PORT, MyServer)
|
754
|
+
server.errback {
|
755
|
+
EM.defer do
|
756
|
+
Bugsnag.notify(RuntimeError.new("Something bad happened"))
|
757
|
+
end
|
758
|
+
}
|
759
|
+
end
|
760
|
+
```
|
761
|
+
|
762
|
+
For this to work, include [Deferrable](http://eventmachine.rubyforge.org/EventMachine/Deferrable.html)
|
763
|
+
in your `MyServer`, then whenever you want to raise an error, call `fail`.
|
764
|
+
|
765
|
+
Integrations
|
766
|
+
------------
|
767
|
+
|
768
|
+
Bugsnag ruby works out of the box with Rails, Sidekiq, Resque, DelayedJob (3+), Mailman, Rake and Rack. It
|
769
|
+
should be easy to add support for other frameworks, either by sending a pull request here or adding a hook
|
770
|
+
to those projects.
|
771
|
+
|
772
|
+
|
773
|
+
Demo Applications
|
774
|
+
-----------------
|
775
|
+
|
776
|
+
[There are demo applications that use the Bugsnag Ruby gem](https://github.com/bugsnag/bugsnag-example-apps/tree/master/apps/ruby):
|
777
|
+
examples include Rails, Sinatra, Rack, Padrino integrations, etc.
|
778
|
+
|
779
|
+
|
780
|
+
Reporting Bugs or Feature Requests
|
781
|
+
----------------------------------
|
782
|
+
|
783
|
+
Please report any bugs or feature requests on the github issues page for this
|
784
|
+
project here:
|
785
|
+
|
786
|
+
<https://github.com/bugsnag/bugsnag-ruby/issues>
|
787
|
+
|
788
|
+
|
789
|
+
Contributing
|
790
|
+
------------
|
791
|
+
|
792
|
+
We'd love you to file issues and send pull requests. If you need help getting started, see [CONTRIBUTING.md](https://github.com/bugsnag/bugsnag-ruby/blob/master/CONTRIBUTING.md)
|
793
|
+
|
794
|
+
|
795
|
+
Build Status
|
796
|
+
------------
|
797
|
+
[![Build Status](https://secure.travis-ci.org/bugsnag/bugsnag-ruby.png)](http://travis-ci.org/bugsnag/bugsnag-ruby)
|
798
|
+
|
799
|
+
|
800
|
+
License
|
801
|
+
-------
|
802
|
+
|
803
|
+
The Bugsnag ruby notifier is free software released under the MIT License.
|
804
|
+
See [LICENSE.txt](https://github.com/bugsnag/bugsnag-ruby/blob/master/LICENSE.txt) for details.
|