projectlocker_pulse 0.2.1

data/CHANGELOG

@@ -0,0 +1,26 @@
+Version 0.2.1 - 2013-04-05 13:04:45 -0400
+===============================================================================
+Removed errant print statements.
+
+Version 0.2.0 - 2013-04-05 12:53:17 -0400
+===============================================================================
+Changed name to ProjectLocker Pulse
+
+===============================================================================
+Changed name to ProjectLocker Pulse
+
+Version 0.1.1 - 2013-03-07 13:24:33 -0500
+===============================================================================
+Minor doc revisions.
+
+Version 0.1.0 - 2013-03-06 13:43:25 -0500
+===============================================================================
+Beta release
+
+Version 0.0.2 - 2012-09-24 14:01:10 -0400
+===============================================================================
+Documentation revisions
+
+Version 0.0.1 - 2012-09-22 10:15:37 -0500
+===============================================================================
+Forked from Airbrake 3.1.4 per MIT license

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Guardfile

@@ -0,0 +1,6 @@
+guard :test do
+  watch(%r{^lib/(.+)\.rb$}) { |m| "test/#{m[1]}_test.rb" }
+  watch(%r{^test/.+_test\.rb$})
+  watch('test/helper.rb')  { "test" }
+end
+

data/INSTALL

@@ -0,0 +1,20 @@
+=== Configuration
+
+You should have something like this in config/initializers/pulse.rb.
+
+  Pulse.configure do |config|
+    config.api_key = '1234567890abcdef'
+  end
+
+(Please note that this configuration should be in a global configuration, and
+is *not* environment-specific. Pulse 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.)
+
+You can test that Pulse is working in your production environment by using 
+this rake task (from RAILS_ROOT):
+
+  rake pulse:test
+
+If everything is configured properly, that task will send a notice to Pulse 
+which will be visible immediately.

data/MIT-LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2012 - 2013, ProjectLocker
+Airbrake Gem Copyright (c) 2007 - 2012, Exceptional DBA Airbrake.io
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,439 @@
+ProjectLocker Exception Reporting
+========
+
+This is the notifier gem for integrating apps with [ProjectLocker Exception Reporting](http://www.projectlocker.com).
+
+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.
+
+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.
+
+
+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](https://github.com/mperham/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 "#{exception.class.name}: #{exception.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](http://portal.projectlocker.com/support/new_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](http://www.projectlocker.com/images/projectlocker_logo_244x30.png)
+
+Special thanks to ![thoughtbot](http://thoughtbot.com/images/tm/logo.png) and Airbrake as creators of the Airbrake gem upon which this is based.
+
+Pulse is maintained and funded by [ProjectLocker](http://www.projectlocker.com)
+
+The names and logos for ProjectLocker, Airbrake, and thoughtbot are trademarks of their respective holders.
+
+License
+-------
+
+Pulse is Copyright © 2012-2013 ProjectLocker. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

data/README_FOR_HEROKU_ADDON.md

@@ -0,0 +1,89 @@
+Pulse on Heroku
+==================
+
+Send your application errors to our hosted service and reclaim your inbox.
+
+1. Installing the Heroku add-on
+----------------------------
+To use Pulse on Heroku, install the Pulse add-on:
+
+    $ heroku addons:add pulse:basic # This adds the the basic plan.
+                                       # If you'd like another plan, specify that instead.
+
+2. Including the Pulse notifier in your application
+--------------------------------------------------
+After adding the Pulse add-on, you will need to install and configure the Pulse notifier.
+
+Your application connects to Pulse with an API key. On Heroku, this is automatically provided to your
+application in `ENV['PULSE_API_KEY']`, so installation should be a snap! (Hoptoad is Pulse's old name.)
+
+### Rails 3.x
+
+Add the Pulse and heroku gems to your Gemfile.  In Gemfile:
+
+    gem 'projectlocker-pulse'
+    gem 'heroku'
+
+Then from your project's RAILS_ROOT, run:
+
+    $ bundle install
+    $ script/rails generate pulse --heroku
+
+### Rails 2.x
+
+Install the heroku gem if you haven't already:
+
+    gem install heroku
+
+Add the Pulse gem to your app. In config/environment.rb:
+
+    config.gem 'projectlocker-pulse'
+
+Then from your project's RAILS_ROOT, run:
+
+    $ rake gems:install
+    $ rake gems:unpack GEM=projectlocker-pulse
+    $ script/generate pulse --heroku
+
+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.
+
+### Rack applications
+
+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:
+
+    require 'rubygems'
+    require 'rack'
+    require 'projectlocker_pulse'
+
+    Pulse.configure do |config|
+      config.api_key = `ENV['PULSE_API_KEY']`
+    end
+
+    app = Rack::Builder.app do
+      use Pulse::Rack
+      run lambda { |env| raise "Rack down" }
+    end
+
+3. Configure your notification settings (important!)
+---------------------------------------------------
+
+Once you have included and configured the notifier in your application,
+you will want to configure your notification settings.
+
+This is important - without setting your email address, you won't receive notification emails.
+
+Pulse can deliver exception notifications to your email inbox.  To configure these delivery settings:
+
+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).
+2. Click the name of your Pulse addon. 
+3. Click "Settings" to configure the Pulse Add-on.
+
+4. Optionally: Set up deploy notification
+-----------------------------------------
+
+If your Pulse plan supports deploy notification, set it up for your Heroku application like this:
+
+    rake pulse:heroku:add_deploy_notification
+
+This will install a Heroku [HTTP Deploy Hook](http://docs.heroku.com/deploy-hooks) to notify Pulse of the deploy.