This add-on is operated by Torsten Buhl

Powerful & intelligent error tracking and exception monitoring from Germany.


Last Updated: 07 May 2015

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, stack trace, …) 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:create exceptiontrap:developer
-----> Adding exceptiontrap to sharp-mountain-4005... done, v18 ($10/mo)

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

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

Migrating between plans

Use the heroku addons:upgrade and heroku addons:downgrade commands to migrate to a new plan.

$ heroku addons:upgrade exceptiontrap:small
Upgrading to exceptiontrap:small on sharp-mountain-4005... done, v18 ($25/mo)
Use `heroku addons:docs exceptiontrap` to view documentation.

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

Some exceptions are ignored by default, e.g. RoutingError and RecordNotFound errors. You can change this behavior in the generated config/exceptiontrap.yml file.

Using with PHP, Zend Framework & other frameworks


Download the exceptiontrap-php plugin from Github to your desired folder (e.g. 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 exceptiontrap-php plugin from Github to your desired library folder (e.g. /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 the 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.

  'module' => 'YOUR_CURRENT_MODULE',
  'controller' => 'YOUR_CURRENT_CONTROLLER',
  'action' => 'YOUR_CURRENT_ACTION'

Further integration

If there is data in your request parameters, session or environment, which you don’t want to be sent to Exceptiontrap, define 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.

  'InvalidArgumentException', 'Zend_Translate_Exception'


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:destroy exceptiontrap
-----> Removing exceptiontrap from sharp-mountain-4005... done, v20 (free)


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.