Exceptiontrap

This add-on is operated by Exceptiontrap

Just powerful & intelligent error tracking for Ruby on Rails and PHP.

Exceptiontrap

Last Updated: 14 March 2014

The Exceptiontrap add-on is currently in beta.

Table of Contents

Exceptiontrap is an add-on for providing exception and error tracking to your Ruby on Rails and PHP applications.

Exceptiontrap catches occuring errors and exceptions in your application and notifies you about them in real-time. The errors are sent to the Exceptiontrap service that groups the incoming errors automatically and provide you all the information (request params, environment variables, stacktrace, …) you need to resolve them.

For example: If your email provider is down and your application crashes while users are trying to sign up, Exceptiontrap lets you know about that immediately.

Provisioning the add-on

Exceptiontrap can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add exceptiontrap:test
-----> Adding exceptiontrap to sharp-mountain-4005... done, v18 (free)

Once Exceptiontrap has been added a EXCEPTIONTRAP_API_KEY setting will be available in the app configuration and will contain the key for your app, which is used to send errors to the Exceptiontrap service. This can be confirmed using the heroku config:get command.

$ heroku config:get EXCEPTIONTRAP_API_KEY
23541e40d697b5f3925f5dfefa99e21e

After installing Exceptiontrap the application should be configured to fully integrate with the add-on.

Using with Rails 2.3+, Rails 3 and Rails 4

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Exceptiontrap library.

gem 'exceptiontrap'

Update application dependencies with bundler.

$ bundle install

Generate the configuration file (the api-key is set as ENV parameter by Heroku, so you can just use ‘heroku’ here)

$ rails generate exceptiontrap --api-key heroku

Using with PHP, Zend Framework & other frameworks

PHP

Download the plugin from https://github.com/itmLABS/exceptiontrap-php to your desired folder (i.e. Exceptiontrap/).

Insert the following lines into your applications codebase (the api-key is set as ENV parameter by Heroku, so you can just use ‘heroku’ here).

require_once 'Exceptiontrap/Exceptiontrap.php';
Exceptiontrap::setup('heroku', true, 'YOUR_APPLICATION_ENV');

Zend Framework 1.x

Download the plugin from https://github.com/itmLABS/exceptiontrap-php to your desired library folder (i.e. /libraries/Exceptiontrap/).

Insert the following lines into your applications codebase (the api-key is set as ENV parameter by Heroku, so you can just use ‘heroku’ here).

require_once 'Exceptiontrap/Exceptiontrap.php';
Exceptiontrap::setup('heroku', true, 'YOUR_APPLICATION_ENV');

Register Plugin for better integration

If you use the Bootsrap class (recommended) insert the following method.

protected function _initExceptiontrap(){
  Zend_Controller_Front::getInstance()->registerPlugin(new Exceptiontrap_Services_Zf1ErrorHandler());
}

Or register the plugin manually to the front controller.

$controller = Zend_Controller_Front::getInstance();
$controller->registerPlugin(new Exceptiontrap_Services_Zf1ErrorHandler());

Other frameworks

The Exceptiontrap plugin / class is designed to be framework agnostic. So integration into your framework of choice should be fine with the general PHP integration documented above.

You can set the request-components by yourself for better integration. The setRequestComponents class method expects an associated array to do this.

Exceptiontrap::setRequestComponents(array(
  'module' => 'YOUR_CURRENT_MODULE',
  'controller' => 'YOUR_CURRENT_CONTROLLER',
  'action' => 'YOUR_CURRENT_ACTION'
));

Further integration

If you have data in your request params, session or environment, which you don’t want to be sent to Exceptiontrap, set them as follows:

Exceptiontrap::setFilterParams(array('HTTP_COOKIE', '_app_session', 'password'));

You can also specify exceptions and errors, which should be ignored and not sent.

Exceptiontrap::setIgnoreList(array('InvalidArgumentException', 'Zend_Translate_Exception'));

Dashboard

There are two ways to access the Exceptiontrap webservice.

Heroku Single Sign On

The Exceptiontrap service is accessible directly through your heroku dashboard. Just click on the Exceptiontrap add-on in your apps add-on list and you will be automatically logged in with a heroku user we created for you.

Login at exceptiontrap.com

Additionally, we automatically create a user account for the email address you use to log in on heroku. After you add the add-on, we send you an invitation email to let you set your password.

Just log in at Exceptiontrap directly with this email address.

If you add Exceptiontrap to multiple applications, you can switch with one click between all your accounts using this login method. Once you’re logged in with your email address, you can also log in through the heroku dashboard (mentioned above) to use this user account.

Removing the add-on

Exceptiontrap can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove exceptiontrap
-----> Removing exceptiontrap from sharp-mountain-4005... done, v20 (free)

Support

All Exceptiontrap support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at contact@exceptiontrap.com.