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