# Migration Guide | Sentry for Resque

## [Table of Content](https://docs.sentry.io/.md#table-of-content)

* [Benefits](https://docs.sentry.io/.md#benefits)
* [Major Changes](https://docs.sentry.io/.md#major-changes)
* [Configuration Changes](https://docs.sentry.io/.md#configuration-changes)
* [API Changes](https://docs.sentry.io/.md#api-changes)
* [Example Apps](https://docs.sentry.io/.md#example-apps)
* [Community Fork](https://docs.sentry.io/.md#community-fork)

## [Benefits](https://docs.sentry.io/.md#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](https://docs.sentry.io/product/insights/overview.md), which you can enable if you haven't already as ([discussed here](https://docs.sentry.io/platforms/ruby/tracing.md)).

* **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](https://docs.sentry.io/.md#major-changes)

Ruby 2.3 and Rails 4 are no longer supported.

#### [Integrations Were Extracted](https://docs.sentry.io/.md#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](https://github.com/getsentry/sentry-ruby/tree/master/sentry-rails.md)
* [sentry-sidekiq](https://github.com/getsentry/sentry-ruby/tree/master/sentry-sidekiq.md)
* [sentry-delayed\_job](https://github.com/getsentry/sentry-ruby/tree/master/sentry-delayed_job.md)
* [sentry-resque](https://github.com/getsentry/sentry-ruby/tree/master/sentry-resque.md)

#### [Removed Processors](https://docs.sentry.io/.md#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:

```ruby
config.send_default_pii = true
```

As for scrubbing sensitive data, please use Sentry's [Advanced Data Scrubbing](https://docs.sentry.io/security-legal-pii/scrubbing/advanced-datascrubbing.md) feature.

#### [New Components and Structure](https://docs.sentry.io/.md#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](https://docs.sentry.io/platforms/ruby/enriching-events/scopes.md)). Most users won't interact with `Hub` directly, but will need `Scope` to configure contextual data.

#### [Context Interfaces Changed](https://docs.sentry.io/.md#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

```ruby
# Before
Raven.user_context(id: 1)

# After
Sentry.set_user(id: 1)
```

Configure data in a local scope

```ruby
# 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](https://docs.sentry.io/.md#configuration-changes)

#### [Removed](https://docs.sentry.io/.md#removed)

```ruby
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](https://docs.sentry.io/.md#renamedrelocated)

```ruby
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](https://docs.sentry.io/.md#added)

This section only lists a few important additions. See the full list of configuration options [here](https://docs.sentry.io/platforms/ruby/configuration/options.md)

```ruby
# 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](https://docs.sentry.io/.md#api-changes)

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

**Installation**

Old:

```ruby
gem "sentry-raven"
```

New:

```ruby
gem "sentry-ruby"

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

**Configuration**

Old:

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

New:

```ruby
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:

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

New:

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

**Set Contextual Data (local)**

Old:

```ruby
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:

```ruby
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:

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

New:

```ruby
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

```ruby
Sentry.get_current_scope.set_transaction_name("NewTransaction")
```

### [`Exception#raven_context`](https://docs.sentry.io/.md#exceptionraven_context)

`sentry-ruby` doesn't capture `raven_context` from exceptions anymore. However, you can use `before_send` to replicate the same behavior:

```rb
config.before_send = lambda do |event, hint|
  if exception = hint[:exception]
    exception.raven_context.each do |key, value|
      # here I assume the event would be a Sentry::Event object
      # however, it'll be a hash if you use the async callback (which will be removed in version 6.0)
      event.send("#{key}=", value)
    end
  end

  event
end
```

## [Example Apps](https://docs.sentry.io/.md#example-apps)

* [Rails example](https://github.com/getsentry/sentry-ruby/tree/master/sentry-rails/examples/rails-6.0)

* [Sinatra example](https://github.com/getsentry/sentry-ruby/tree/master/sentry-ruby/examples/sinatra.md)

* Sidekiq examples:

  * [with Rails](https://github.com/getsentry/sentry-ruby/tree/master/sentry-rails/examples/rails-6.0)
  * [without Rails](https://github.com/getsentry/sentry-ruby/tree/master/sentry-sidekiq/example.md)

## [Community Fork](https://docs.sentry.io/.md#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](https://github.com/ifad/sentry-legacy-ruby.md). You can use this in cases where it is impossible for you to upgrade but please note that we don't officially support it.
