ProjectLocker Exception Reporting

This is the notifier gem for integrating apps with ProjectLocker Exception Reporting.

When an uncaught exception occurs, Pulse will POST the relevant data to the Pulse server specified in your environment.

Rails Installation

Rails 3.x

Add the Pulse gem to your Gemfile. In Gemfile:

gem "projectlocker-pulse"

Then from your project's RAILS_ROOT, and in your development environment, run:

bundle install
rails generate pulse --api-key your_key_here

That's it!

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.

Rails 2.x

Add the Pulse gem to your app. In config/environment.rb:

config.gem 'projectlocker-pulse'

or if you are using bundler:

gem 'projectlocker-pulse', :require => 'pulse/rails'

Then from your project's RAILS_ROOT, and in your development environment, run:

rake gems:install
rake gems:unpack GEM=projectlocker-pulse
script/generate pulse --api-key your_key_here

As always, if you choose not to vendor the projectlocker-pulse gem, make sure every server you deploy to has the gem installed or your application won't start.

Non-rails apps using Bundler

There is an undocumented dependency in activesupport where the i18n gem is required only if the core classes extensions are used (active_support/core_ext). This can lead to a confusing LoadError exception when using Pulse. Until this is fixed in activesupport the workaround is to add i18n to the Gemfile for your Sinatra/Rack/pure ruby application:

gem 'i18n'
gem 'projectlocker-pulse'

Rack

In order to use Pulse in a non-Rails rack app, just load pulse, configure your API key, and use the Pulse::Rack middleware:

require 'rack'
require 'projectlocker_pulse'

Pulse.configure do |config|
  config.api_key = 'my_api_key'
end

app = Rack::Builder.app do
  run lambda { |env| raise "Rack down" }
end

use Pulse::Rack
run app

Sinatra

Using Pulse in a Sinatra app is just like a Rack app:

require 'sinatra'
require 'projectlocker_pulse'

Pulse.configure do |config|
  config.api_key = 'my api key'
end

use Pulse::Rack

get '/' do
  raise "Sinatra has left the building"
end

Usage

For the most part, Pulse works for itself.

It intercepts the exception middleware calls, sends notifications and continues the middleware call chain.

If you want to log arbitrary things which you've rescued yourself from a controller, you can do something like this:

...
rescue => ex
  notify_pulse(ex)
  flash[:failure] = 'Encryptions could not be rerouted, try again.'
end
...

The #notify_pulse call will send the notice over to Pulse for later analysis. While in your controllers you use the notify_pulse method, anywhere else in your code, use Pulse.notify.

To perform custom error processing after Pulse has been notified, define the instance method #rescue_action_in_public_without_pulse(exception) in your controller.

Informing the User

The Pulse gem is capable of telling the user information about the error that just happened via the user_information option. They can give this error number in bug reports, for example. By default, if your 500.html contains the text

<!-- PULSE ERROR -->

then that comment will be replaced with the text "Pulse Error [errnum]". You can modify the text of the informer by setting config.user_information. Pulse will replace "error_id }" with the ID of the error that is returned from Pulse.

Pulse.configure do |config|
...
  config.user_information = "<p>Tell the devs that it was <strong>{{ error_id }}</strong>'s fault.</p>"
end

You can also turn the middleware that handles this completely off by setting config.user_information to false.

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 "manual" methods would be env['pulse.error_id'] = Pulse.notify_or_ignore(...).

Current user information

Pulse provides information about the current logged in user, so you could easily determine the user who experienced the error in your app.

It uses current_user and current_member to identify the authenticated user, where current_user takes precedence.

If you use different naming, please add the following lines to your controller:

alias_method :current_duck, :current_user
helper_method :current_duck

Voila! You'll get information about a duck that experienced crash about your app.

Asynchronous notifications with Pulse

When your user experiences error using your application, it gets sent to Pulse server. This introduces a considerable latency in the response.

Asynchronous notification sending deals with this problem. Pulse uses girl_friday to achieve this . (thanks Mike)

It's disabled by default and you can enable it in your Pulse configuration.

Pulse.configure do |config|
  ...
  config.async = true
end

Note that this feature is enabled with JRuby 1.6+, Rubinius 2.0+ and Ruby 1.9+. It does not support Ruby 1.8 because of its poor threading support.

For implementing custom asynchronous notice delivery, send a block to config.async. It receives notice param. Pass it to Pulse.sender.send_to_pulse method to do actual delivery. In this way it's possible to move Pulse notification even in background worker(e.g. Resque or Sidekiq).

# Thread-based asynchronous send
Pulse.configure do |config|
  ...
  config.async do |notice|
    Thread.new { Pulse.sender.send_to_pulse(notice) }
  end
end

# Resque-like configuration
Pulse.configure do |config|
  ...
  config.async do |notice|
    Resque.enqueue(PulseDeliveryWorker, notice)
  end
end

Tracking deployments in Pulse

Pulse supports the ability to track deployments of your application in Pulse. By notifying Pulse 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 Pulse that occurred before and after a deploy.

When Pulse is installed as a gem, you need to add

require 'pulse/capistrano'

to your deploy.rb

If you don't use Capistrano, then you can use the following rake task from your deployment process to notify Pulse:

rake pulse:deploy TO=#{rails_env} REVISION=#{current_revision} REPO=#{repository} USER=#{local_user}

Going beyond exceptions

You can also pass a hash to Pulse.notify 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
  Pulse.notify_or_ignore(
    :error_class   => "Special Error",
    :error_message => "Special Error: #{e.message}",
    :parameters    => params
  )
end

While in your controllers you use the notify_pulse method, anywhere else in your code, use Pulse.notify. Pulse 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 Pulse 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 "#exceptionexception.classexception.class.name: #exceptionexception.message"
: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.

Pulse merges the hash you pass with these default options:

{
  :api_key       => Pulse.api_key,
  :error_message => 'Notification',
  :backtrace     => caller,
  :parameters    => {},
  :session       => {}
}

You can override any of those parameters.

Sending shell environment variables when "Going beyond exceptions"

One common request we see is to send shell environment variables along with manual exception notification. We recommend sending them along with CGI data or Rack environment (:cgi_data or :rack_env keys, respectively.)

See Pulse::Notice#initialize in lib/pulse/notice.rb for more details.

Filtering

You can specify a whitelist of errors that Pulse 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).

Pulse ignores the following exceptions by default:

ActiveRecord::RecordNotFound
ActionController::RoutingError
ActionController::InvalidAuthenticityToken
CGI::Session::CookieStore::TamperedWithCookie
ActionController::UnknownAction
AbstractController::ActionNotFound
Mongoid::Errors::DocumentNotFound

To ignore errors in addition to those, specify their names in your Pulse configuration block.

Pulse.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.

Pulse.configure do |config|
  config.api_key      = '1234567890abcdef'
  config.ignore_only  = ["ActiveRecord::IgnoreThisError"] # or [] to ignore no exceptions.
end

To ignore certain user agents, add in the #ignore_user_agent attribute as a string or regexp:

Pulse.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:

Pulse.configure do |config|
  config.api_key      = '1234567890abcdef'
  config.ignore_by_filter do |exception_data|
    true if exception_data[:error_class] == "RuntimeError"
  end
end

To replace sensitive information sent to the Pulse service with [FILTERED] use #params_filters:

Pulse.configure do |config|
  config.api_key      = '1234567890abcdef'
  config.params_filters << "credit_card_number"
end

Note that, when rescuing exceptions within an ActionController method, Pulse will reuse filters specified by #filter_parameter_logging.

Testing

When you run your tests, you might notice that the Pulse 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 or spec_helper.rb files to redefine that method so those errors are not reported while running tests.

module Pulse
  def self.notify(exception, opts = {})
    # do nothing.
  end
end

Proxy Support

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.

Pulse.configure do |config|
  config.proxy_host = proxy.host.com
  config.proxy_port = 4038
  config.proxy_user = foo # optional
  config.proxy_pass = bar # optional

Logging

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:

Pulse.configure do |config|
  ...
  config.logger = Logger.new("path/to/your/log/file")
end

Supported Rails versions

See SUPPORTED_RAILS_VERSIONS for a list of official supported versions of Rails.

Please open up a support ticket if you're using a version of Rails that is listed above and the notifier is not working properly.

Javascript Notifier

To automatically include the Javascript node on every page, use this helper method from your layouts:

<%= pulse_javascript_notifier %>

It's important to insert this very high in the markup, above all other javascript. Example:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf8">
    <%= pulse_javascript_notifier %>
    <!-- more javascript -->
  </head>
  <body>
    ...
  </body>
</html>

This helper will automatically use the API key, host, and port specified in the configuration.

The Javascript notifier tends to send much more notifications than the base Rails project. If you want to receive them into a separate Pulse project, specify its API key in the js_api_key option.

config.js_api_key = 'another-projects-api-key'

To test the Javascript notifier in development environment, overwrite (temporarily) the development_environments option:

Pulse.configure do |config|
  # ...
  config.development_environments = []
end

Development

See TESTING.md for instructions on how to run the tests.

Credits

ProjectLocker

Special thanks to and Airbrake as creators of the Airbrake gem upon which this is based.

Pulse is maintained and funded by ProjectLocker

The names and logos for ProjectLocker, Airbrake, and thoughtbot are trademarks of their respective holders.