Migration Guide

Table of Content

• Benefits
• Major Changes
• Configuration Changes
• API Changes
• Example Apps
• Community Fork

Benefits

• Unified Interfaces With Other SDKs: The design of sentry-raven is outdated compared with our modern Sentry SDKs. If you also use other Sentry SDKs, such as Sentry's JavaScript SDK for your frontend application, you'll notice that their interfaces are quite different from the one provided for sentry-raven. The new sentry-ruby SDK provides a more consistent user experience across all different platforms.

• Tracing: The Sentry Ruby SDK includes tracing, which you can enable if you haven't already as (discussed here).

• Future Support: sentry-raven has entered maintenance mode, which means it won't receive any new feature supports or aggressive bug fixes.

• Better Extensibility: Unlike sentry-raven, sentry-ruby is built with extensibility in mind and will allow the community to build extensions for different integrations/features.

Major Changes

Integrations Were Extracted

Sentry's Ruby SDK still supports integration with Rack by providing built-in middleware, but you'll need to install gems for integrations with Rails, sidekiq, delayed_job, and other libraries.

Currently available integrations are:

• sentry-rails
• sentry-sidekiq
• sentry-delayed_job
• sentry-resque

Removed Processors

In sentry-raven we have different processor classes for data scrubbing. But updated Sentry Ruby SDK doesn't support these processors. Instead, to protect users' sensitive data, the Ruby SDK adds a new configuration option of send_default_pii. When the value is set to false (default), sensitive information, such as

• user ip
• user cookie
• request body
• query parameters

will not be sent to Sentry.

You can re-enable it by setting:

config.send_default_pii = true 

As for scrubbing sensitive data, please use Sentry's Advanced Data Scrubbing feature.

New Components and Structure

Senty's Ruby SDK uses a unified structure, which introduces two new components: Hub and Scope (which are both documented here). Most users won't interact with Hub directly, but will need Scope to configure contextual data.

Context Interfaces Changed

In sentry-raven, we provided helpers like Raven.user_context for setting contextual data. In our updated Ruby SDK, those helpers were removed, and you'll need to use a different approach for setting those data like:

Configure data globally

# Before Raven.user_context(id: 1)  # After Sentry.set_user(id: 1) 

Configure data in a local scope

# Before Raven.tags_context(foo: "bar") do  Raven.capture_message("test") end  # After Sentry.with_scope do |scope|  scope.set_tags(foo: "bar")   Sentry.capture_message("test") end 

Configuration Changes

Removed

config.sanitize_credit_cards config.sanitize_fields config.sanitize_fields_excluded config.sanitize_http_headers  config.scheme config.secret_key config.server  config.tags config.logger config.encoding config.silence_ready  # please only use config.before_send config.should_capture config.transport_failure_callback 

Renamed/Relocated

config.current_environment #=> config.environment config.environments #=> config.enabled_environments  config.rails_report_rescued_exceptions #=> config.rails.report_rescued_exceptions with sentry-rails installed  config.ssl #=> config.transport.ssl config.ssl_ca_file #=> config.transport.ssl_ca_file config.ssl_verification #=> config.transport.ssl_verification config.timeout #=> config.transport.timeout config.open_timeout #=> config.transport.open_timeout config.proxy #=> config.transport.proxy  # These options are present in sentry-ruby 4.* but were removed in 5.0 with the faraday removal config.http_adapter #=> config.transport.http_adapter config.faraday_builder #=> config.transport.faraday_builder 

Added

This section only lists a few important additions. See the full list of configuration options here

# this behaves similar to the old config.scheme option config.transport.transport_class = MyTransportClass  # sentry-ruby sends events asynchronously with its own background workers # the default number of workers equals to your machine's processor count # you can adjust the number with config.background_worker_threads = 10  # to send events synchronously like sentry-raven does, set it to 0 config.background_worker_threads = 0 

API Changes

In this section, we provide code examples to guide you through the changes required for the migration.

Installation

Old:

gem "sentry-raven" 

New:

gem "sentry-ruby"  # and the integrations you need gem "sentry-rails" gem "sentry-sidekiq" gem "sentry-delayed_job" gem "sentry-resque" 

Configuration

Old:

Raven.configure do |config|  config.dsn = "DSN" end 

New:

Sentry.init do |config|  config.dsn = "DSN"   # Add data like request headers and IP for users, if applicable;  # see https://docs.sentry.io/platforms/ruby/data-management/data-collected/ for more info  config.send_default_pii = true end 

Set Contextual Data (global)

Old:

Raven.user_context(id: 1) Raven.context.tags = { foo: "bar" } Raven.context.extra = { debug: true } 

New:

Sentry.set_user(id: 1) Sentry.set_tags(foo: "bar") Sentry.set_extras(debug: true) 

Set Contextual Data (local)

Old:

Raven.user_context(id: 1) do  # send event end Raven.tag_context(foo: "bar") do  # send event end Raven.extra_context(debug: true) do  # send event end 

New:

Sentry.with_scope do |scope|  scope.set_user(id: 1)  scope.set_tags(foo: "bar")  scope.set_extras(debug: true)  # send event end 

Manual Message/Exception Capturing

Old:

Raven.capture_message("test", extra: { debug: true }) 

New:

Sentry.capture_message("test", extra: { debug: true }) 

The options for these methods are also changed. Currently available options are:

• contexts
• tags
• extra
• user
• level
• fingerprint
• backtrace

To set transaction_name (transaction in sentry-raven) of the event, please use

Sentry.get_current_scope.set_transaction_name("NewTransaction") 

Exception#raven_context

sentry-ruby doesn't capture raven_context from exceptions anymore. Just use set_tags or set_extra as above to set contextual data.

Example Apps

• Rails example
• Sinatra example
• Sidekiq examples:
  • with Rails
  • without Rails

Community Fork

A community maintained fork of sentry-ruby that works with older Ruby versions (2.1, 2.2 and 2.3) is available here. You can use this in cases where it is impossible for you to upgrade but please note that we don't officially support it.