Airbrake

This add-on is operated by Rackspace Hosting

Reclaim your inbox and send your application errors to our hosted service.

Airbrake

Last Updated: 19 March 2014

Table of Contents

Airbrake is an add-on that provides error tracking to your applications. We send e-mail alerts when the app crashes, and keep a dashboard of all errors with detailed information with backtrace and parameters on how to solve the issue.

Add Airbrake to your app and reclaim your inbox, get real-time notifications of errors as they occur.

Airbrake is accessible via an API and has supported client libraries for Java, Ruby, Python, Grails, Scala, Play!, Node.js and Clojure.

Provisioning the add-on

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

A list of all plans available can be found here.

$ heroku addons:add airbrake
-----> Adding airbrake on afternoon-sword-90... done, v14 ($9/mo)
Use `heroku addons:docs airbrake` to view documentation.

Once Airbrake has been added a AIRBRAKE_API_KEY setting will be available in the app configuration and will contain the api_key. This can be confirmed using the heroku config:get command.

$ heroku config:get AIRBRAKE_API_KEY
a8i2r4b1r1a0k1e5k11L1A1B5b00m112

Configure your notification settings (Important)

Once you have included and configured the notifier in your application, you will want to configure your notification settings.

This is important - without setting your email address, you won’t receive notification emails.

Airbrake can deliver exception notifications to your email inbox. To configure these delivery settings:

  1. Visit your application’s Airbrake Add-on page, like http://api.heroku.com/myapps/my-great-app/addons/airbrake:developer or type heroku addons:open airbrake
  2. Click the drop down settings, to configure the Airbrake Add-on.
  3. Click the “Settings” to update the email on your account.

Airbrake Email Update

Including the Airbrake notifier in your application

After adding the Airbrake add-on, you will need to install and configure the Airbrake notifier.

Your application connects to Airbrake with an API key. On Heroku, this is automatically provided to your application in ENV['AIRBRAKE_API_KEY'], so installation should be a snap!

Rails

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

Rails 3.x

Add the airbrake gems to your Gemfile. In Gemfile:

gem 'airbrake'

Then from your project’s RAILS_ROOT, run:

$ bundle install
$ rails generate airbrake --api-key `heroku config:get AIRBRAKE_API_KEY`

Rails 2.x

Add the airbrake gem to your app. In config/environment.rb:

config.gem 'airbrake'

Then from your project’s RAILS_ROOT, run:

$ rake gems:install
$ rake gems:unpack GEM=airbrake
$ generate airbrake --api-key `heroku config:get AIRBRAKE_API_KEY`

As always, if you choose not to vendor the airbrake gem, make sure every server you deploy to has the gem installed or your application won’t start.

Rack applications

In order to use airbrake in a non-Rails rack app, just load the airbrake, configure your API key, and use the Airbrake::Rack middleware:

require 'rubygems'
require 'rack'
require 'airbrake'

Airbrake.configure do |config|
  config.api_key = `ENV['AIRBRAKE_API_KEY']`
end

app = Rack::Builder.app do
  use Airbrake::Rack
  run lambda { |env| raise "Rack down" }
end

use Airbrake::Rack
run app

Rails 1.x

For Rails 1.x, visit the Airbrake’s README on GitHub, and be sure to use ENV['AIRBRAKE_API_KEY'] where your API key is required in configuration code.

Collect errors for non-production Rails environments

By default errors are only collected from your app’s production environment.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the AIRBRAKE_API_KEY values retrieved from heroku config to .env.

$ heroku config -s --app | grep AIRBRAKE_API_KEY >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Development environment

When developing locally it is best to turn off the integration with Airbrake to minimise dependencies on remote services.

Deploy changes

Deploy the Airbrake configuration to Heroku:

$ git add config/airbrake.rb
$ git commit -a -m "Adding airbrake config"
$ git push heroku master
…
-----> Heroku receiving push
-----> Launching... done, v3
       http://warm-frost-1289.herokuapp.com deployed to Heroku

To git@heroku.com:warm-frost-1289.git
 * [new branch]      master -> master

Set up deploy notification

If your Airbrake plan supports deploy notification, set it up for your Heroku application like this:

rake airbrake:heroku:add_deploy_notification

This will install a Heroku HTTP Deploy Hook to notify Airbrake of the deploy.

Sending current user information

Airbrake provides information about the current logged in user, so you can easily determine the user who experienced the error in your app.

It uses current_user and current_member to identify the authenticated user, where current_user takes precendence.

If you use different naming, please add the following lines to your controller:

alias_method :current_duck, :current_user
helper_method :current_duck

Voila! You’ll get information about a duck that experienced a crash of your app.

By default Airbrake collects the following attributes:

  • id
  • name
  • username
  • email

You can also customize attributes that will be collected

Airbrake.configure do |config|
# ...
# collect only user ids
config.user_attributes = [:id] # ["id"] also works
end

Using Airbrake with Rake

Do you want Airbrake to report exceptions that happen inside a rake task? Simples.

Airbrake.configure do |config|
    # ...
    config.rescue_rake_exceptions = true
end

Sending notices to Airbrake manually from controllers

For the most part, Airbrake works for itself.

It intercepts the exception middleware calls, sends notifications and continues the middleware call chain.

If you want to log arbitrary things which you’ve rescued yourself from a controller, you can do something like this inside actions:

# ...
rescue => ex
 notify_airbrake(ex)
 flash[:failure] = 'Encryptions could not be rerouted, try again.'
end

The #notify_airbrake call will send the notice over to Airbrake for later analysis. While in your controllers you use the notify_airbrake method, anywhere else in your code, use Airbrake.notify.

To perform custom error processing after Airbrake has been notified, define the instance method #rescue_action_in_public_without_airbrake(exception) in your controller.

Java

Airbrake provides a jar for integrating apps with Airbrake with Java Applications.

The easy way to use airbrake is configuriong log4j appender. Otherwise if you don’t use log4j you can use airbrake notifier directly with a very simple API.

Setting up with Maven

<project>
    <dependencies>
        <dependency>
            <groupId>io.airbrake</groupId>
            <artifactId>airbrake-java</artifactId>
            <version>2.2.0</version>
        </dependency>
    </dependencies>
</project>

Without Maven

you need to add these libraries to your classpath

Log4j

log4j.rootLogger=INFO, stdout, airbrake

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=[%d,%p] [%c{1}.%M:%L] %m%n

log4j.appender.airbrake=airbrake.AirbrakeAppender
log4j.appender.airbrake.api_key=YOUR_AIRBRAKE_API_KEY
#log4j.appender.airbrake.env=development
#log4j.appender.airbrake.env=production
log4j.appender.airbrake.env=test
log4j.appender.airbrake.enabled=true
#log4j.appender.airbrake.noticesUrl=http://api.airbrake.io/notifier_api/v2/notices

or in XML format:

<appender name="AIRBRAKE" class="airbrake.AirbrakeAppender">
     <param name="api_key" value="YOUR_AIRBRAKE_API_KEY"/>
    <param name="env" value="test"/>
    <param name="enabled" value="true"/>
<!-- param name="noticesUrl" value="http://api.airbrake.io/notifier_api/v2/notices" / -->
</appender>

<root>
    <appender-ref ref="AIRBRAKE"/>
</root>

Send Errors Directly.

When developing locally it is best to turn off the integration with Airbrake to minimise dependencies on remote services.

try {
    doSomethingThatThrowAnException();
} catch(Throwable t) {
    AirbrakeNotice notice = new AirbrakeNoticeBuilder(YOUR_AIRBRAKE_API_KEY, t, "env").newNotice();
    AirbrakeNotifier notifier = new AirbrakeNotifier();
    notifier.notify(notice);
}

Monitoring & Logging

Airbrake uses the logger from your Rails application by default, presumably STDOUT. If you don’t like Airbrake scribbling to your standard output, just pass another Logger instance inside your configuration:

Airbrake.configure do |config|
# ...
config.logger = Logger.new("path/to/your/log/file")
end

Dashboard

For more information on the features available within the Airbrake dashboard please see the docs at airbrake.io.

The Airbrake dashboard allows you to view errors, add users, complete integrations.

Airbrake Dashboard

The dashboard can be accessed via the CLI:

$ heroku addons:open airbrake
Opening airbrake for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Airbrake from the Add-ons menu.

Troubleshooting

We recommend checking out the Airbrake Kb for more infromation on how to fix issues with Airrake.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade airbrake:newplan
-----> Upgrading airbrake:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: airbrake:newplan

Removing the add-on

Airbrake can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove airbrake
-----> Removing airbrake on afternoon-sword-90... done, v15 ($9/mo)

Before removing Airbrake a data export can be performed by contacting support@airbrake.io

Support

All Airbrake support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at Airbrake Support Forum & Knowledge base..

Additional resources

Additional resources are available at: