Skip to content

Latest commit

 

History

History
595 lines (471 loc) · 15.8 KB

Migration_guide_from_v4_to_v5.md

File metadata and controls

595 lines (471 loc) · 15.8 KB
Raw

Migration guide from v4 to v5

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

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 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](#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. [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