Exceptional - getexceptional.com

Exceptional is an exception tracking and managing utility for Ruby & Rails applications

This guide covers

1. The Exceptional Rails Plugin
2. The Exceptional Ruby Gem
3. Advanced Exceptional (Adapters, API)

The Exceptional Rails Plugin

The Exceptional plugin for Rails shares the same source repository as the ruby gem, the only thing that makes a Rails plugin a plugin is the init.rb and install.rb ruby files. We think this is cool, if you feel differently let us know :)

Installation

The Exceptional Rails plugin will work alongside any other exception management solution. Though it would be a good idea to remove them if you decide to use Exceptional to ensure the best possible performance.

You will need an account at getexceptional.com

1. Install : From the root folder of your Rails application, run the following command to download and install it:

        script/plugin install git://github.com/contrast/exceptional.git
   

2. Configure : The post install hook will create an exceptional.yml config file in your RAILS_ROOT/config directory, you need to configure your API Key. Your API Key is available from your account area at getexceptional.com

        rake exceptional::rails_install api_key=YOUR-API-KEY
   

3. Test: You can test your exceptional plugin is working properly with

        rake exceptional::test
   

4. Restart your application
5. Check RAILS_ROOT/log/exceptional.log to ensure the Exceptional plugin is working error free

Configuration

The Exceptional Rails plugin is configured via the RAILS_ROOT/config/exceptional.yml YAML file. By default the exceptional plugin is enabled only for the ‘Production’ rails environment.

Configuration Variables

        api-key
                Exceptional API Key (Required)

        enabled
                Whether to enable the Exceptional Plugin (Default = true)

        ssl
                To use SSL to communicate with getexceptional.com (Default = false)

        log-level
                Log Level for RAILS_ROOT/log/exceptional.log (Default 'info')

        adapter
                Exception data publish adapter (Default = 'HttpAdapter') - (see adapters section below)

The Magic

The Exceptional plugin for Rails performs some magic when a Rails application is booting

1. Configuration file loaded from [RAILS_ROOT]/config/exceptional.yml
2. The deployed environment is checked for what server the Rails application is running within, quietly exiting at this point if no server is detected. (See below for a list of supported server environments)
3. The plugin authenticates with the getexceptional.com service, exiting if unable to do so.
4. A hook is installed in Rails by defining a method on ActionController::Base and adding an alias_method_chain to call it around rescue_action

Supported Rails Server Environments

• Litespeed
• Mongrel
• Passenger
• Thin
• Webrick

Ruby Gem

Installation

1. Add github to your gem sources list

        gem sources -a http://gems.github.com
   

2. Install the Exceptional gem

        sudo gem install contrast-exceptional
   

Usage

        require 'rubygems'
        require 'exceptional'

        Exceptional.api_key = "YOUR-API-KEY-GOES-HERE"

        Exceptional.rescue do
                nil.boom!
        end

Advanced Exceptional

The Exceptional Gem/Plugin has some extra features. A brief overview is given below, but more detail is available by generating the rdoc directly from the project. Within the exceptional plugin directory run

        rake docs

Pluggable Publishing Adapters

How the Exceptional Gem/Plugin publishes data to the getexceptional.com is pluggable. This is implemented via Adapters, and the different adapter implementations allow for various qualities of service.

HttpAdapter

The HttpAdapter is a single threaded direct HTTP dispatch of the exception data to the getexceptional.com. The HttpAdapter is the default adapter used by the Exceptional Gem/Plugin

HttpAsyncAdapter

The HttpAsyncAdapter dispatches exception data to the getexceptional.com in a temporary thread. To use the HttpAsyncAdapter set the

        adapter: HttpAsyncAdapter

configuration variable within the exceptional.yml file

FileAdapter

The FileAdapter writes exception data to the filesystem as .json files, which are later published to the getexceptional.com at a specified interval by a file_sweeper rake task. To use the FileAdapter set the

        adapter: FileAdapter

configuration variable within the exceptional.yml file

When an exception is passed to the plugin, the FileAdapter will create a JSON file representing the exception and save it to the RAILS_ROOT/log/exceptional directory

File Sweeper

To run the file sweeper rake task directly (from RAILS_ROOT)

        rake exceptional:file_sweeper

To run the file sweeper from a cron job every 15 mins, you can use a crontab entry of

        */15 * * * * cd [FULL/PATH/TO/RAILS/ROOT]/vendor/plugins/exceptional && [FULL/PATH/TO]/rake --silent exceptional:file_sweeper

You must replace the [FULL/PATH/TO] with the full path to your RAILS_ROOT and directory where rake is installed

example crontab

        */15 * * * * cd /home/user/apps/myapp/vendor/plugins/exceptional && /usr/local/bin/rake --silent exceptional:file_sweeper

The file sweeper will log its activity to RAILS_ROOT/log/exceptional_file_sweeper.log

Exceptional API

The Exceptional API based on published data in .json format. The API is currently in beta, and likely to change. Please contact us at support@getexceptional.com if you wish to understand more about our plans for the API.