This add-on is operated by Airbrake Technologies Inc

Powerful error monitoring and APM software captures bugs so you fix them fast

Last updated September 16, 2021

Airbrake is an add-on that provides robust bug tracking in any of your Ruby, JavaScript, Go, Java, PHP, .NET, Python, Node.js, iOS, Swift and Android applications via its API. In doing so, it allows you to easily review errors, tie an error to an individual piece of code, and trace the cause back to recent changes.

The Airbrake dashboard provides easy categorization, searching, and prioritization of exceptions so that when errors occur, your team can quickly determine the root cause.

Provisioning the add-on

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

$ heroku addons:create airbrake
Creating airbrake-spherical-7439... done, (free)
Adding airbrake-spherical-7439 to airbrake-c8eef44... done
Setting AIRBRAKE_API_KEY, AIRBRAKE_PROJECT_ID and restarting airbrake-c8eef44... done, v14
Use `heroku addons:docs airbrake` to view documentation.

Once Airbrake has been added, two environment variables will be available in the app configuration: AIRBRAKE_API_KEY and AIRBRAKE_PROJECT_ID. This can be confirmed using the heroku config:get command.

$ heroku config:get AIRBRAKE_API_KEY
a8i2r4b1r1a0k1e5k11L1A1B5b00m112
$ heroku config:get AIRBRAKE_PROJECT_ID
113204

These variables should be used to configure our notifier libraries.

Including the Airbrake notifier in your application

Ruby

Add the Airbrake gem to your Gemfile:

gem 'airbrake'

Next, select the integration you’re interested in and follow the appropriate instructions. We provide integrations for:

• Web frameworks
  • Rails
  • Sinatra
  • Rack applications
• Job processing libraries
  • ActiveJob
  • Resque
  • Sidekiq
  • DelayedJob
• Other libraries
  • Rake
  • Plain Ruby scripts

Rails

Generate your Airbrake config (the generator will automatically retrieve your key and id from the Heroku configuration):

rails g airbrake

Verify that your application sends exceptions to the Airbrake dashboard:

rake airbrake:test

In case of success, a test exception should appear in your dashboard.

Deploy tracking

To implement Deploy Hooks on Heroku, please use one of the following options.

You can manually create the Deploy hook:

heroku addons:add deployhooks:http \
--url="https://airbrake.io/api/v3/projects/PROJECT_ID/heroku-deploys\
?key=PROJECT_KEY\
&environment=ENVIRONMENT\
&repository=REPOSITORY_URL"

Or create it using rake:

rake airbrake:install_heroku_deploy_hook

Be sure to provide the app name for the rake task if you have multiple Heroku apps configured. You can send it by setting the HEROKU_APP environment variable.

The repository URL will default to the URL of the origin remote. The REPOSITORY_URL environment variable can be used to override this value.

export HEROKU_APP=your-heroku-app
export REPOSITORY_URL=git@github.com:username/repo.git
rake airbrake:install_heroku_deploy_hook

Java

For more information, visit our official GitHub repo.

Installation

Gradle:

compile 'io.airbrake:javabrake:0.1.6'

Maven:

<dependency>
  <groupId>io.airbrake</groupId>
  <artifactId>javabrake</artifactId>
  <version>0.1.6</version>
</dependency>

Ivy:

<dependency org='io.airbrake' name='javabrake' rev='0.1.6'>
  <artifact name='javabrake' ext='pom'></artifact>
</dependency>

Quickstart

Configuration:

import io.airbrake.javabrake.Notifier;

int projectId = 12345;
String projectKey = "FIXME";
Notifier notifier = new Notifier(projectId, projectKey);

notifier.addFilter(
    (Notice notice) -> {
      notice.setContext("environment", "production");
      return notice;
    });

Using notifier directly:

try {
  do();
} catch (IOException e) {
  notifier.report(e);
}

Using Airbrake proxy class:

import io.airbrake.javabrake.Airbrake;

try {
  do();
} catch (IOException e) {
  Airbrake.report(e);
}

By default report sends errors asynchronously returning a Future, but synchronous API is also available:

import io.airbrake.javabrake.Notice;

Notice notice = Airbrake.reportSync(e);
if (notice.exception != null) {
    logger.info(notice.exception);
} else {
    logger.info(notice.id);
}

To set custom params you can build and send notice in separate steps:

import io.airbrake.javabrake.Notice;

Notice notice = Airbrake.buildNotice(e);
notice.setContext("component", "mycomponent");
notice.setParam("param1", "value1");
Airbrake.send(notice);

You can also set custom params on all reported notices:

notifier.addFilter(
    (Notice notice) -> {
      notice.setParam("myparam", "myvalue");
      return notice;
    });

Or ignore specific notice:

notifier.addFilter(
    (Notice notice) -> {
      if (notice.context.get("environment") == "development") {
          // Ignore notice.
          return null;
      }
      return notice;
    });

To debug why notices are not sent you can use onReportedNotice hook:

notifier.onReportedNotice(
    (notice) -> {
      if (notice.exception != null) {
        logger.info(notice.exception);
      } else {
        logger.info(String.format("notice id=%s url=%s", notice.id, notice.url));
      }
    });

log4j integration

See https://github.com/airbrake/log4javabrake

log4j2 integration

See https://github.com/airbrake/log4javabrake2

logback integration

See https://github.com/airbrake/logback

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

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

The dashboard can be accessed via the CLI:

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

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

Troubleshooting

We recommend checking out the Airbrake Knowledge Base for more information on how to fix issues with Airbrake.

Migrating between plans

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.

$ heroku addons:remove airbrake

 !    WARNING: Destructive Action
 !    This command will affect the app: airbrake-c8eef44
 !    To proceed, type "airbrake-c8eef44" or re-run this command with --confirm airbrake-c8eef44

> airbrake-c8eef44
Destroying airbrake-clear-5179 on airbrake-c8eef44... done, (free)
Removing vars for AIRBRAKE from airbrake-c8eef44 and restarting... done, v13

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

Contact & support

All Airbrake support and runtime issues should be submitted to the Heroku Support channels. For non-support related issues or product feedback, feel free to:

• file an issue on the relevant notifier library repository on GitHub
• send us an email
• tweet at us
• chat with us (visit airbrake.io and click on the round orange button in the bottom right corner)