forked from thoughtbot/hoptoad_notifier
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
194 lines (138 loc) · 6.61 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
HoptoadNotifier
===============
This is the notifier plugin for integrating apps with Hoptoad.
When an uncaught exception occurs, HoptoadNotifier will POST the relevant data
to the Hoptoad server specified in your environment.
INSTALLATION
------------
REMOVE EXCEPTION_NOTIFIER
In your ApplicationController, REMOVE this line:
include ExceptionNotifiable
In your config/environment* files, remove all references to ExceptionNotifier
Remove the vendor/plugins/exception_notifier directory.
INSTALL HOPTOAD_NOTIFIER
From your project's RAILS_ROOT, run:
script/plugin install git://github.com/thoughtbot/hoptoad_notifier.git
CONFIGURATION
You should have something like this in config/initializers/hoptoad.rb.
HoptoadNotifier.configure do |config|
config.api_key = '1234567890abcdef'
end
(Please note that this configuration should be in a global configuration, and
is *not* environment-specific. Hoptoad is smart enough to know what errors are
caused by what environments, so your staging errors don't get mixed in with
your production errors.)
That should be it! Now all exceptions will be logged to Hoptoad where they can
be aggregated, filtered, sorted, analyzed, massaged, and searched. In previous
releases you had to include HoptoadNotifier::Catcher into your
ApplicationController, but the plugin takes care of that now.
** NOTE FOR RAILS 1.2.* USERS: **
You will need to copy the hoptoad_notifier_tasks.rake file into your
RAILS_ROOT/lib/tasks directory in order for the following to work:
You can test that hoptoad is working in your production environment by using
this rake task (from RAILS_ROOT):
rake hoptoad:test
If everything is configured properly, that task will send a notice to hoptoad
which will be visible immediately.
USAGE
For the most part, hoptoad works for itself. Once you've included the notifier
in your ApplicationController (which is now done automatically by the plugin),
all errors will be rescued by the #rescue_action_in_public provided by the plugin.
If you want to log arbitrary things which you've rescued yourself from a
controller, you can do something like this:
...
rescue => ex
notify_hoptoad(ex)
flash[:failure] = 'Encryptions could not be rerouted, try again.'
end
...
The #notify_hoptoad call will send the notice over to hoptoad for later
analysis.
TRACKING DEPLOYMENTS IN HOPTOAD
Paying Hoptoad plans support the ability to track deployments of your application in Hoptoad.
By notify Hoptoad of your application deployments, all errors are resolved when a deploy occurs,
so that you'll be notified again about any errors that reoccur after a deployment.
Additionally, it's possible to review the errors in Hoptoad that occurred before and after a deploy.
When Hoptoad is installed as a plugin this functionality is loaded automatically (if you have Capistrano version 2.0.0 or greater).
When Hoptoad installed as a gem, you need to add
require 'hoptoad_notifier/recipes/hoptoad'
to your deploy.rb
GOING BEYOND EXCEPTIONS
You can also pass a hash to notify_hoptoad method and store whatever you want, not just an exception. And you can also use it anywhere, not just in controllers:
begin
params = {
# params that you pass to a method that can throw an exception
}
my_unpredicable_method(params)
rescue => e
HoptoadNotifier.notify(
:error_class => "Special Error",
:error_message => "Special Error: #{e.message}",
:request => { :params => params }
)
end
While in your controllers you use the notify_hoptoad method, anywhere else in your code, use HoptoadNotifier.notify. Hoptoad will get all the information about the error itself. As for a hash, these are the keys you should pass:
* :error_class – Use this to group similar errors together. When Hoptoad catches an exception it sends the class name of that exception object.
* :error_message – This is the title of the error you see in the errors list. For exceptions it is "#{exception.class.name}: #{exception.message}"
* :request – While there are several ways to send additional data to Hoptoad, passing a Hash with :params key as :request as in the example above is the most common use case. When Hoptoad catches an exception in a controller, the actual HTTP client request is being sent using this key.
Hoptoad merges the hash you pass with these default options:
def default_notice_options
{
:api_key => HoptoadNotifier.api_key,
:error_message => 'Notification',
:backtrace => caller,
:request => {},
:session => {},
:environment => ENV.to_hash
}
end
You can override any of those parameters.
FILTERING
You can specify a whitelist of errors, that Hoptoad will not report on. Use
this feature when you are so apathetic to certain errors that you don't want
them even logged.
This filter will only be applied to automatic notifications, not manual
notifications (when #notify is called directly).
Hoptoad ignores the following exceptions by default:
ActiveRecord::RecordNotFound
ActionController::RoutingError
ActionController::InvalidAuthenticityToken
CGI::Session::CookieStore::TamperedWithCookie
To ignore errors in addition to those, specify their names in your Hoptoad
configuration block.
HoptoadNotifier.configure do |config|
config.api_key = '1234567890abcdef'
config.ignore << ActiveRecord::IgnoreThisError
end
To ignore *only* certain errors (and override the defaults), use the
#ignore_only attribute.
HoptoadNotifier.configure do |config|
config.api_key = '1234567890abcdef'
config.ignore_only = [ActiveRecord::IgnoreThisError]
end
To ignore certain user agents, add in the #ignore_user_agent attribute as a
string or regexp:
HoptoadNotifier.configure do |config|
config.api_key = '1234567890abcdef'
config.ignore_user_agent << /Ignored/
config.ignore_user_agent << 'IgnoredUserAgent'
end
To ignore exceptions based on other conditions, use #ignore_by_filter:
HoptoadNotifier.configure do |config|
config.api_key = '1234567890abcdef'
config.ignore_by_filter do |exception_data|
true if exception_data[:error_class] == "RuntimeError"
end
end
TESTING
When you run your tests, you might notice that the hoptoad service is recording
notices generated using #notify when you don't expect it to. You can
use code like this in your test_helper.rb to redefine that method so those
errors are not reported while running tests.
module HoptoadNotifier::Catcher
def notify(thing)
# do nothing.
end
end
THANKS
Thanks to Eugene Bolshakov for the excellent write-up on GOING BEYOND EXCEPTIONS, which we have included above.