Migration guide from v4 to v5

Airbrake README
Airbrake Ruby README
YARD API documentation

The Airbrake gem v5 release introduced new features, bug fixes and some breaking changes. Don't worry, we tried to make this transition as smooth as possible. This guide will help you to upgrade from Airbrake v4 to Airbrake v5.

The most prominent change is that the Airbrake gem was split into two gems: airbrake and airbrake-ruby. The airbrake-ruby gem is the core gem, which defines how to send notices. The airbrake gem contains integrations with web frameworks and other software.

Please note, that we still do support Airbrake v4 for quite some time. However, it is feature frozen.

Migration Instructions

General changes
Integration changes

General changes

Configuration

Old option	New option	required?
api_key	project_key	required
n/a	project_id	required
development_environments	ignore_environments	optional
port	host	optional
secure	host	optional
proxy_host	proxy	optional
proxy_port	proxy	optional
proxy_user	proxy	optional
proxy_pass	proxy	optional
params_filter	add_filter	optional
params_whitelist_filter	add_filter	optional
backtrace_filters	add_filter	optional
ignore_by_filters	add_filter	optional
rake_environment_filters	add_filter	optional
ignore	add_filter	optional
ignore_rake	add_filter	optional
ignore_user_agent	add_filter	optional
ignore_only	add_filter	optional
environment_name	environment	optional
project_root	root_directory	optional
async	removed (async by default)	n/a
http_open_timeout	removed	n/a
development_lookup	removed	n/a
notifier_name	removed	n/a
notifier_url	removed	n/a
notifier_version	removed	n/a
user_information	removed	n/a
framework	removed	n/a
rescue_rake_exceptions	removed	n/a
user_attributes	removed (autodetected)	n/a
test_mode	removed	n/a

The api_key option was renamed to project_key. ^[link]

# Old way
Airbrake.configure do |c|
  c.api_key = 'a1b2c3d4e5f6g780'
end

# New way
Airbrake.configure do |c|
  c.project_key = 'a1b2c3d4e5f6g780'
end

The new mandatory option - project_id. To find your project's id, either copy it from the URL or navigate to your project's settings and find these fields on the right sidebar. ^[link]
```
# Old way
# Didn't exist.

# New way
Airbrake.configure do |c|
  c.project_id = 93597
end
```

The development_environments option was renamed to ignore_environments. Its behaviour was also slightly changed. By default, the library sends exceptions in all environments, so you don't need to assign an empty Array anymore to get this behavior. If you relied on the default value of development_environments before upgrading, you should explicitly set ignore_environments to %w(development test cucumber) to preserve the old behavior. ^[link]

# Old way
Airbrake.configure do |c|
  c.development_environments = %w(development test)

  # OR to collect exceptions in all envs

  c.development_environments = []

  # OR don't set this option to get the default (development, test, cucumber)
end

# New way
Airbrake.configure do |c|
  c.environment = Rails.env
  c.ignore_environments = %w(development test)

  # OR to collection exceptions in all envs

  # Simply don't set this option

  # OR use the old default value

  c.ignore_environments = %w(development test cucumber)
end

The port option was removed. It was merged with the host option. From now on simply include your port in your host. ^[link]

# Old way
Airbrake.configure do |c|
  c.host = 'example.com'
  c.port = 8080
end

# New way
Airbrake.configure do |c|
  c.host = 'http://example.com:8080'
end

The secure option was removed. It was merged with the host option. From now on simply specify your protocol, when you define host. The library will guess the mode based on the URL scheme (HTTP or HTTPS). ^[link]
```
# Old way
Airbrake.configure do |c|
  c.host = 'example.com'
  c.secure = true
end

# New way
Airbrake.configure do |c|
  c.host = 'https://example.com'
end
```
The http_open_timeout & http_read_timeout options were removed. ^[link]

The proxy_host, proxy_port, proxy_user & proxy_pass options were merged into one option - proxy. It accepts a Hash with the host, port, user & password keys. ^[link]

# Old way
Airbrake.configure do |c|
  c.proxy_host = 'example.com'
  c.proxy_port = 8080
  c.proxy_user = 'user'
  c.proxy_pass = 'p4ssw0rd'
end

# New way
Airbrake.configure do |c|
  c.proxy = {
    host: 'example.com',
    port: 8080,
    user: 'user',
    password: 'p4ssw0rd',
  }
end

The params_filters option was replaced with the blacklist filter. ^[link]
The params_whitelist_filters option was replaced with the whitelist filter ^[link]
The backtrace_filters, ignore_by_filters, rake_environment_filters, ignore, ignore_rake, ignore_user_agent & ignore_only options were replaced with the add_filter API. ^[link]
The development_lookup option was removed. ^[link]

The environment_name was renamed to environment. ^[link]

# Old way
Airbrake.configure do |c|
  c.environment_name = 'staging'
end

# New way
Airbrake.configure do |c|
  c.environment = 'staging'
end

The project_root option was renamed to root_directory. ^[link]

NOTE: you must set this if you want Airbrake backtraces to link to GitHub. In Rails projects this value should typically be equal to Rails.root.
```
# Old way
Airbrake.configure do |c|
  c.project_root = '/var/www/project'
end

# New way
Airbrake.configure do |c|
  c.root_directory = '/var/www/project'
end
```
The notifier_name, notifier_url & notifier_version options were removed. ^[link]
The user_information option was removed. ^[link]
The framework option was removed. ^[link]
The rescue_rake_exceptions option was removed. ^[link]
The user_attributes option was removed. Airbrake will automatically include :id, :name, :username and :email attributes. If :name is not available Airbrake will build it from :first_name and :last_name. ^[link]
The test_mode option was removed. ^[link]
The async option was removed. Airbrake is now async by default. Read the Airbrake.notify docs for more information. ^[link]
The list of default ignored exceptions was relaxed. The library now ignores only SystemExit exceptions. ^[link]
Airbrake no longer reuses filters specified by Rails.application.config.filter_parameters. Instead, use the add_filter API. ^[link]

Library API

Blacklist filter

Instead of various filter options the library supports blacklist filtering. The blacklist filter is global, which means it filters every matching key in the notice's payload.

Airbrake v5.2.0+

# Old way
Airbrake.configure do |c|
  c.params_filters << 'credit_card_number'
end

# New way
Airbrake.configure do |c|
  c.blacklist_keys << 'credit_card_number'
end

Airbrake v5.0.0-v5.1.0 API (deprecated)

Airbrake.blacklist_keys([:credit_card_number])

Whitelist filter

Instead of various filter options the library supports whitelist filtering. The whitelist filter is global, which means it filters every key except the specified ones.

Airbrake v5.2.0+

# Old way
Airbrake.configure do |c|
  c.params_whitelist_filters << 'email'
end

# New way
Airbrake.configure do |c|
  c.whitelist_keys << [:email]
end

Airbrake v5.0.0-v5.1.0 API (deprecated)

Airbrake.whitelist_keys([:email])

Ignore by filter

Since the ignore_by_filter option was removed, the new API was introduced - Airbrake.add_filter. The API is similar to ignore_by_filter, but .add_filter doesn't rely on return values. Instead, you can mark notices as ignored with help of the Airbrake::Notice#ignore! method. Airbrake.add_filter replaces a lot of legacy options.

# Old way
Airbrake.configure do |c|
  c.ignore_by_filter do |exception_data|
    true if exception_data[:error_class] == "RuntimeError"
  end
end

# New way
Airbrake.add_filter do |notice|
  # The library supports nested exceptions, so one notice can carry several
  # exceptions.
  if notice[:errors].any? { |error| error[:type] == 'RuntimeError' }
    notice.ignore!
  end
end

The notice that add_filter yields is an instance of Airbrake::Notice. Its public API is described in the airbrake-ruby README.

Notify

Airbrake.notify is now async. To be able to send exceptions synchronously, the Airbrake.notify_sync method was added. Both methods have the same method signature. ^[link]

The list of accepted arguments was amended. The first argument can now additionally accept Strings. The second argument is still a Hash, but the difference is that anything you pass there will be added to the Params tab. The support for api_key, error_message, backtrace, parameters and session was removed.
```
# Old way
Airbrake.notify(
  RuntimeError.new('Oops'),
  api_key: '1a2b3c4d5e6f7890',
  error_message: 'Notification',
  backtrace: caller,
  parameters: {},
  session: {}
)

# New way
Airbrake.notify('Oops', this_will_be: 'prepended to the Params tab')
```
Airbrake.notify_or_ignore was removed. ^[link]

Other changes

The library no longer sends ENV by default. If you need this behaviour, use the add_filter API. ^[link]
```
Airbrake.add_filter do |notice|
  notice[:environment].merge!(ENV)
end
```
The Airbrake.configuration interface was removed. It's no longer possible to read config values. ^[link]
The Airbrake CLI was removed completely. Instead, it is recommended to use Rake tasks. ^[link]
The bundled ca-bundle.crt was removed. ^[link]

Integration changes

Heroku

The deploy hook Rake task was renamed from airbrake:heroku:add_deploy_notification to airbrake:install_heroku_deploy_hook. ^[link]

# Old way
bundle exec rake airbrake:heroku:add_deploy_notification

# New way
bundle exec rake airbrake:install_heroku_deploy_hook

The way to generate the Airbrake config was simplified. ^[link]

# Old way
rails g airbrake --api-key `heroku config:get AIRBRAKE_API_KEY`

# New way
rails g airbrake

Rails

The support for Rails 2 was dropped. Airbrake v5 officially supports only 3.2.*, 4.0.*, 4.1.*, 4.2.* and above. ^[link]
The Rails generator was changed to accept two parameters: project id and project key. The --api-key flag was removed. ^[link]
```
# Old way
rails g airbrake --api-key YOUR_API_KEY

# New way
rails g airbrake YOUR_PROJECT_ID YOUR_API_KEY
```
The notify_airbrake helper method's signature was amended to conform to the Airbrake.notify signature. ^[link]

Rack applications

The name of the Airbrake Rack middle ware was changed from Airbrake::Rails::Middleware to Airbrake::Rack::Middleware

# Old way
use Airbrake::Rails::Middleware

# New way
use Airbrake::Rack::Middleware

Resque

Replace resque/failure/airbrake with airbrake/resque/failure

# Old way
require 'resque/failure/airbrake'
Resque::Failure.backend = Resque::Failure::Airbrake

# New way
require 'airbrake/resque/failure'
Resque::Failure.backend = Resque::Failure::Airbrake

Sidekiq

Replace airbrake/sidekiq with airbrake/sidekiq/error_handler

# Old way
require 'airbrake/sidekiq'

# New way
require 'airbrake/sidekiq/error_handler'

Deployment with Rake task

The list of recognised environment variables passed to the airbrake:deploy Rake task was changed.

# Old way
rake airbrake:deploy USER=john TO=production REVISION=38748467 REPO=https://github.com/airbrake/airbrake

# New way
rake airbrake:deploy USERNAME=john ENVIRONMENT=production REVISION=38748467 REPOSITORY=https://github.com/airbrake/airbrake

Capistrano

There is no longer a difference between integration with Capistrano 2 and 3. For Capistrano 3 you no longer need an after hook.

# Old way
# For Capistrano 2
# Capfile
require 'airbrake/capistrano'
# For Capistrano 3
# Capfile
require 'airbrake/capistrano3'
# config/deploy.rb
after 'deploy:finished', 'airbrake:deploy'

# New way
# For Capistrano 2
require 'airbrake/capistrano/tasks'
# For Capistrano 3
# Capfile
require 'airbrake/capistrano/tasks'
# config/deploy.rb
after :finished, 'airbrake:deploy'

Happy Airbraking with Airbrake v5!
The Airbrake team

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migration_guide_from_v4_to_v5.md

Migration_guide_from_v4_to_v5.md

Migration guide from v4 to v5

Migration Instructions

General changes

Configuration

Library API

Blacklist filter

Airbrake v5.2.0+

Airbrake v5.0.0-v5.1.0 API (deprecated)

Whitelist filter

Airbrake v5.2.0+

Airbrake v5.0.0-v5.1.0 API (deprecated)

Ignore by filter

Notify

Other changes

Integration changes

Heroku

Rails

Rack applications

Resque

Sidekiq

Deployment with Rake task

Capistrano

Files

Migration_guide_from_v4_to_v5.md

Latest commit

History

Migration_guide_from_v4_to_v5.md

File metadata and controls

Migration guide from v4 to v5

Migration Instructions

General changes

Configuration

Library API

Blacklist filter

Airbrake v5.2.0+

Airbrake v5.0.0-v5.1.0 API (deprecated)

Whitelist filter

Airbrake v5.2.0+

Airbrake v5.0.0-v5.1.0 API (deprecated)

Ignore by filter

Notify

Other changes

Integration changes

Heroku

Rails

Rack applications

Resque

Sidekiq

Deployment with Rake task

Capistrano