Airbrake

<p align="center"> <img src="https://airbrake-github-assets.s3.amazonaws.com/brand/airbrake-full-logo.png" width="200"> </p>

• Airbrake README
• Airbrake Ruby README
• YARD API documentation

Introduction

[Airbrake][airbrake.io] is an online tool that provides robust exception tracking in any of your Ruby applications. 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.

Key features

![The Airbrake Dashboard][dashboard]

This library is built on top of [Airbrake Ruby][airbrake-ruby]. The difference between Airbrake and Airbrake Ruby is that the airbrake gem is just a collection of integrations with frameworks or other libraries. The airbrake-ruby gem is the core library that performs exception sending and other heavy lifting.

Normally, you just need to depend on this gem, select the integration you are interested in and follow the instructions for it. If you develop a pure frameworkless Ruby application or embed Ruby and don't need any of the listed integrations, you can depend on the airbrake-ruby gem and ignore this gem entirely.

The list of integrations that are available in this gem includes:

• [Heroku support][heroku-docs] (as an [add-on][heroku-addon])
• Web frameworks
  • Rails
  • Sinatra
  • Rack applications
• Job processing libraries
  • ActiveJob
  • Resque
  • Sidekiq
  • DelayedJob
  • Shoryuken
  • Sneakers
• Other libraries
  • ActionCable
  • Rake
  • Logger
• Plain Ruby scripts

Deployment tracking:

• Using Capistrano
• Using the Rake task

Installation

Bundler

Add the Airbrake gem to your Gemfile:

gem 'airbrake'

Manual

Invoke the following command from your terminal:

gem install airbrake

Configuration

Rails

Integration

To integrate Airbrake with your Rails application, you need to know your [project id and project key][project-idkey]. Set AIRBRAKE_PROJECT_ID & AIRBRAKE_PROJECT_KEY environment variables with your project's values and generate the Airbrake config:

export AIRBRAKE_PROJECT_ID=<PROJECT ID>
export AIRBRAKE_PROJECT_KEY=<PROJECT KEY>

rails g airbrake

[Heroku add-on][heroku-addon] users can omit specifying the key and the id. Heroku add-on's environment variables will be used ([Heroku add-on docs][heroku-docs]):

rails g airbrake

This command will generate the Airbrake configuration file under config/initializers/airbrake.rb. Make sure that this file is checked into your version control system. This is enough to start Airbraking.

In order to configure the library according to your needs, open up the file and edit it. [The full list of supported configuration options][config] is available online.

To test the integration, invoke a special Rake task that we provide:

rake airbrake:test

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

The notify_airbrake controller helpers

The Airbrake gem defines two helper methods available inside Rails controllers: #notify_airbrake and #notify_airbrake_sync. If you want to notify Airbrake from your controllers manually, it's usually a good idea to prefer them over [Airbrake.notify][airbrake-notify], because they automatically add information from the Rack environment to notices. #notify_airbrake is asynchronous, while #notify_airbrake_sync is synchronous (waits for responses from the server and returns them). The list of accepted arguments is identical to Airbrake.notify.

Additional features: user reporting, sophisticated API

The library sends all uncaught exceptions automatically, attaching the maximum possible amount information that can help you to debug errors. The Airbrake gem is capable of reporting information about the currently logged in user (id, email, username, etc.), if you use an authentication library such as Devise. The library also provides a special API for manual error reporting. [The description of the API][airbrake-api] is available online.

Automatic integration with Rake tasks and Rails runner

Additionally, the Rails integration offers automatic exception reporting in any Rake tasks^[link] and [Rails runner][rails-runner].

Integration with filter_parameters

If you want to reuse Rails.application.config.filter_parameters in Airbrake you can configure your notifier the following way:

# config/initializers/airbrake.rb
Airbrake.configure do |c|
  c.blocklist_keys = Rails.application.config.filter_parameters
end

There are a few important details:

1. You must load filter_parameter_logging.rb before the Airbrake config
2. If you use Lambdas to configure filter_parameters, you need to convert them to Procs. Otherwise you will get ArgumentError
3. If you use Procs to configure filter_parameters, the procs must return an Array of keys compatible with the Airbrake allowlist/blocklist option (String, Symbol, Regexp)

Consult the example application, which was created to show how to configure filter_parameters.

filter_parameters dot notation warning

The dot notation introduced in [rails/pull/13897][rails-13897] for filter_parameters (e.g. a key like credit_card.code) is unsupported for performance reasons. Instead, simply specify the code key. If you have a strong opinion on this, leave a comment in the [dedicated issue][rails-sub-keys].

Logging

In new Rails apps, by default, all the Airbrake logs are written into log/airbrake.log. In older versions we used to write to wherever Rails.logger writes. If you wish to upgrade your app to the new behaviour, please configure your logger the following way:

c.logger = Airbrake::Rails.logger

Sinatra

To use Airbrake with Sinatra, simply require the gem, [configure][config] it and use our Rack middleware.

# myapp.rb
require 'sinatra/base'
require 'airbrake'

Airbrake.configure do |c|
  c.project_id = 113743
  c.project_key = 'fd04e13d806a90f96614ad8e529b2822'

  # Display debug output.
  c.logger.level = Logger::DEBUG
end

class MyApp < Sinatra::Base
  use Airbrake::Rack::Middleware

  get('/') { 1/0 }
end

run MyApp.run!

To run the app, add a file called config.ru to the same directory and invoke rackup from your console.

# config.ru
require_relative 'myapp'

That's all! Now you can send a test request to localhost:9292 and check your project's dashboard for a new error.

curl localhost:9292

Rack

To send exceptions to Airbrake from any Rack application, simply use our Rack middleware, and [configure][config] the notifier.

require 'airbrake'
require 'airbrake/rack'

Airbrake.configure do |c|
  c.project_id = 113743
  c.project_key = 'fd04e13d806a90f96614ad8e529b2822'
end

use Airbrake::Rack::Middleware

Note: be aware that by default the library doesn't filter any parameters, including user passwords. To filter out passwords add a filter.

Appending information from Rack requests

If you want to append additional information from web requests (such as HTTP headers), define a special filter such as:

Airbrake.add_filter do |notice|
  next unless (request = notice.stash[:rack_request])
  notice[:params][:remoteIp] = request.env['REMOTE_IP']
end

The notice object carries a real Rack::Request object in its stash. Rack requests will always be accessible through the :rack_request stash key.

Optional Rack request filters

The library comes with optional predefined builders listed below.

RequestBodyFilter

RequestBodyFilter appends Rack request body to the notice. It accepts a length argument, which tells the filter how many bytes to read from the body.

By default, up to 4096 bytes is read:

Airbrake.add_filter(Airbrake::Rack::RequestBodyFilter.new)

You can redefine how many bytes to read by passing an Integer argument to the filter. For example, read up to 512 bytes:

Airbrake.add_filter(Airbrake::Rack::RequestBodyFilter.new(512))

Sending custom route breakdown performance

Arbitrary code performance instrumentation

For every route in your app Airbrake collects performance breakdown statistics. If you need to monitor a specific operation, you can capture your own breakdown:

def index
  Airbrake::Rack.capture_timing('operation name') do
    call_operation(...)
  end

  call_other_operation
end

That will benchmark call_operation and send performance information to Air