Contextify
========

This is the notifier gem for integrating apps with [Contextify](http://contextify.io).

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

Help
----

For help with using Contextify and this notifier visit [our support site](http://help.contextify.io).

For discussion of Contextify development check out the [mailing list](http://groups.google.com/group/hoptoad-notifier-dev).

For SSL verification see the [Resources](https://github.com/contextify/contextify/blob/master/resources/README.md).

Rails Installation
------------------

### Rails 3.x

Add the contextify gem to your Gemfile.  In Gemfile:

    gem "contextify"

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

    bundle install
    rails generate contextify --api-key your_key_here

That's it!

The generator creates a file under `config/initializers/contextify.rb` configuring Contextify 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 contextify gem to your app. In config/environment.rb:

    config.gem 'contextify'
    
or if you are using bundler:

    gem 'contextify', :require => 'contextify/rails'

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

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

As always, if you choose not to vendor the contextify 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/contextify.rb` configuring Contextify 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.

### Upgrading From Earlier Versions of Contextify

If you're currently using the plugin version (if you have a
vendor/plugins/hoptoad_notifier directory, you are), you'll need to perform a
few extra steps when upgrading to the gem version.

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

    config.gem 'contextify'

Remove the plugin:

    rm -rf vendor/plugins/hoptoad_notifier

Make sure the following line DOES NOT appear in your ApplicationController file:

    include HoptoadNotifier::Catcher

If it does, remove it.  The new catcher is automatically included by the gem
version of Contextify.

Before running the contextify generator, you need to find your project's API key.
Log in to your account at contextify.io, and click on the "Projects" button.
Then, find your project in the list, and click on its name. In the left-hand
column, you'll see an "Edit this project" button. Click on that to get your
project's API key. If you accidentally use your personal API api_key,
you will get API key not found errors, and exceptions will not be stored
by the Contextify service.

Then from your project's RAILS_ROOT, run:

    rake gems:install
    script/generate contextify --api-key your_key_here

Once installed, you should vendor the contextify gem.

    rake gems:unpack GEM=contextify

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

### Upgrading from Earlier Versions of the Hoptoad Gem (with config.gem)

If you're currently using the gem version of the hoptoad_notifier and have
a version of Rails that uses config.gem (in the 2.x series), there is
a step or two that you need to do to upgrade. First, you need to remove
the old version of the gem from vendor/gems:

    rm -rf vendor/gems/hoptoad_notifier-X.X.X

Then you must remove the hoptoad_notifier_tasks.rake file from lib:

    rm lib/tasks/hoptoad_notifier_tasks.rake

You can then continue to install normally. If you don't remove the rake file,
you will be unable to unpack this gem (Rails will think it's part of the
framework).



You can test that Contextify is working in your production environment by using
this rake task (from RAILS_ROOT):

    rake contextify:test

If everything is configured properly, that task will send a notice to Contextify
which will be visible immediately.

### Removing hoptoad_notifier

in your ApplicationController, REMOVE this line:

    include HoptoadNotifiable

In your config/environment* files, remove all references to HoptoadNotifier

Remove the vendor/plugins/hoptoad_notifier directory.

### Remove hoptoad_notifier plugin

Remove the vendor/plugins/hoptoad_notifier directory before installing the gem, or run:

    script/plugin remove hoptoad_notifier

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 Contextify. 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 'contextify'

Rack
----

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

    require 'rack'
    require 'contextify'

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

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

Sinatra
-------

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

    require 'sinatra'
    require 'contextify'

    Contextify.configure do |config|
      config.api_key = 'my API key'
    end

    use Contextify::Rack

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

Usage
-----

For the most part, Contextify 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_contextify(ex)
      flash[:failure] = 'Encryptions could not be rerouted, try again.'
    end
    ...

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

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

Informing the User
------------------

The contextify 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

    <!-- AIRBRAKE ERROR -->

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

    Contextify.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['contextify.error_id']`. When the exception is caught
automatically in a controller, Contextify sets that value. If you're, however, calling the Contextify methods like
`Contextify#notify` or `Contextify#notify_or_ignore`, please make sure you set that value. So the proper way of calling the 
"manual" methods would be `env['contextify.error_id'] = Contextify.notify_or_ignore(...)`.

Tracking deployments in Contextify
--------------------------------

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

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

    require 'contextify/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 Contextify:

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

Going beyond exceptions
-----------------------

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

While in your controllers you use the `notify_contextify` method, anywhere else in
your code, use `Contextify.notify`. Contextify 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 Contextify 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 Contextify, passing a Hash as :parameters as in the example above is the most common use case. When Contextify catches an exception in a controller, the actual HTTP client request parameters are sent using this key.

Contextify merges the hash you pass with these default options:

    {
      :api_key       => Contextify.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 Contextify::Notice#initialize in lib/contextify/notice.rb for
more details.

Filtering
---------

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

Contextify 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 Contextify
configuration block.

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

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

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

    Contextify.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 Contextify service with [FILTERED] use #params_filters:

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

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

Testing
-------

When you run your tests, you might notice that the Contextify 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 Contextify
      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 Contextify servers. To configure the proxy settings, added the following information to your Contextify configuration block.

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

Supported Rails versions
------------------------

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

Please open up a support ticket ( http://help.contextify.io ) or submit a new github issue
if you're using a version of Rails that is listed above and the notifier is
not working properly.

Javascript Notifer
------------------

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

    <%= contextify_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">
        <%= contextify_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 Contextify 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:

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

Development
-----------

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

Credits
-------

![thoughtbot](http://thoughtbot.com/images/tm/logo.png)

Contextify is maintained and funded by [contextify.io](http://contextify.io)

Thank you to all [the contributors](https://github.com/contextify/contextify/contributors)!

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

License
-------

Contextify is Copyright © 2008-2012 Contextify. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.