Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Exceptional helps you track errors in apps. This Repo contains the Ruby Gem. Exceptional also supports Django, iOS, Javascript, Node-JS, PHP. Each App needs an API key, this is given on signup at
branch: v0.1.0-dev

This branch is 91 commits ahead, 229 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Exceptional -

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 :)


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

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

script/plugin install git://

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

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

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

rake exceptional::test

  1. Restart your application

  2. Check RAILS_ROOT/log/exceptional.log to ensure the Exceptional plugin is working error free


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 (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 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


  1. Add github to your gem sources list

gem sources -a

  1. Install the Exceptional gem

sudo gem install contrast-exceptional


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 is pluggable. This is implemented via Adapters, and the different adapter implementations allow for various qualities of service.


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


The HttpAsyncAdapter dispatches exception data to the in a temporary thread. To use the HttpAsyncAdapter set the adapter: HttpAsyncAdapter configuration variable within the exceptional.yml file


The FileAdapter writes exception data to the filesystem as .json files, which are later published to the 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 if you wish to understand more about our plans for the API.

Something went wrong with that request. Please try again.