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.