Exceptional is an exception tracking and managing utility for Ruby & Rails applications
This guide covers
The Exceptional Rails Plugin
The Exceptional Ruby Gem
Advanced Exceptional (Adapters, API)
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 getexceptional.com
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
Configure : The post install hook will create an
exceptional.ymlconfig 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 -f vendor/plugins/exceptional/Rakefile exceptional::rails_install api_key=YOUR-API-KEY
Restart your application
Check RAILS_ROOT/log/exceptional.log to ensure the Exceptional plugin is successfully enabled
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 Exceptional plugin for Rails performs some magic when a Rails application is booting
Configuration file loaded from [RAILS_ROOT]/config/exceptional.yml
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)
The plugin authenticates with the getexceptional.com service, exiting if unable to do so.
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
Litespeed
Mongrel
Passenger
Thin
Webrick
Add github to your gem sources list
gem sources -a gems.github.com
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
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
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.
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
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
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
To run the file sweeper rake task directly (from RAILS_ROOT) rake -f vendor/plugins/exceptional/Rakefile 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
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.