Exceptional documentation

This documentation should be useful for anyone wanting to know more in-depth information about Exceptional and how things work. Use the links just below to skip to the relevant part of the documentation.

While we are still developing the API consider this document beta, if you're thinking of using the API outside of Rails please do contact us. We will be announcing the official release on our blog when we're ready.

• Ruby gem
• API

Ruby gem

Ruby on Rails installation

1. Configure your app to load the gem
   Add this to your config/environment.rb file:

   config.gem 'exceptional', :version => '2.0.3'

2. Install or update the gem
   Install the gem by running

   gem install exceptional

   Remove old versions of the plugin (if any) by running:

   rm -rf vendor/plugins/exceptional

3. Configure your API key
   Generate config/exceptional.yml containing your api-key by running:

   exceptional install YOUR-API-KEY

   The file should look like:

   api-key: YOUR-API-KEY

4. Redeploy your changes
   Once your installed and configured Exceptional, you need to deploy the changes to start catching Errors in your deployed environments. We do this by running:

   cap deploy

The Magic

The Exceptional gem for Rails performs some magic when a Rails application is booting, here's what happens

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. A separate log file is setup so as not to interfere with the Rails log. RAILS_ROOT/log/exceptional.log
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 Server Environments

• Litespeed
• Mongrel
• Passenger
• Thin
• Webrick

Usage

For more advanced usage instructions you should check out the rdoc documentation, we're currently having some problems with the RDoc generation (as mentioned in this blog post) but will link it up here as soon it makes sense. In the meantime, if you want to dive in please do take a look at the source code on github.

require 'rubygems'
require 'exceptional'

Exceptional.rescue do
  nil.boom!
end

Exceptional API

Exceptional was designed with Ruby on Rails in mind however, we realised during development that we could abstract things just a bit to suit any language and framework. We currently have client APIs for the following;

• Ruby
• PHP

The API is changing quite a bit at the moment, we'll publish some detailed documentation soon for people interested in implementing clients for other languages. Contact us at support@getexceptional.com if you're interested in using Exceptional for languages other than ruby.