> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade from AppSignal for Ruby gem 3.x to 4.x

> A guide to help applications upgrade from AppSignal for Ruby gem 3 to version 4.

AppSignal for Ruby 4.0 is a major release that introduces multiple error support, amendable sample data, changes to how it instruments other gems, how custom instrumentation works, and the removal of previously deprecated modules. Follow this guide to make the upgrade process smoother.

## Upgrade to the latest 3.x series

Before upgrading to AppSignal for Ruby gem 4.0, upgrade to the latest gem from the 3.x series. This version will print and log deprecation warnings for things that were removed in version 4.x of the Ruby gem. Run the tests for your app the gem is integrated with and fix any deprecation warnings and errors you may encounter.

First, in the app's `Gemfile`, update the version lock to `~> 3.0` and run `bundle update appsignal` in a terminal in the same directory as the `Gemfile`.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Gemfile

  gem "appsignal", "~> 3.0"
  ```
</CodeGroup>

Run your applications and fix any deprecation warnings printed to the application's STDERR output and logged in `appsignal.log` during its operation.

## Upgrade to the latest 4.x series

After all deprecation warnings are resolved using version 3 of the Ruby gem, remove the version lock from the `Gemfile` and run `bundle update appsignal` again to update AppSignal for Ruby to version 4.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Gemfile

  gem "appsignal"
  ```
</CodeGroup>

## Changes

Below are all the notable changes between the latest Ruby gem version 3 and the new version 4. Please go through them and update your application as described.

### Main library

* The `Appsignal.start_logger` method is removed. The logger is now automatically started on `Appsignal.start`. Applications need to remove the `Appsignal.start_logger` call.
* The AppSignal Ruby gem configuration is frozen after `Appsignal.start` is called. The configuration can no longer be modified after the Ruby gem has started.
* The `Appsignal.start` method can only be called once. Subsequent calls are ignored by the Ruby gem.

### Configuration

* AppSignal will not start if loading the `config/appsignal.yml` file causes an error. Check the application output or the `appsignal.log` file for any warnings.
* Configure AppSignal in Ruby with the new [`Appsignal.configure` helper](/ruby/configuration/load-order#configure-helper). Apps using the `Appsignal.config = Appsignal::Config.new(...)` pattern must update their apps to use this method instead.
* The `Appsignal.config =` method is removed. Instead, use the [`Appsignal.configure` helper](/ruby/configuration/load-order#configure-helper) to configure AppSignal in Ruby.
* The `skip_session_data` option is removed. Use the [`send_session_data` option](/ruby/configuration/options#option-send_session_data) instead.
* The `debug` option is removed. Use the [`log_level: debug` option](/ruby/configuration/options#option-log_level) instead.
* The `transaction_debug_mode` option is removed. Use the [`log_level: trace` option](/ruby/configuration/options#option-log_level) instead.
* The `working_dir_path` option is removed. Use the [`working_directory_path` option](/ruby/configuration/options#option-working_directory_path) instead.

### Integrations

* The `Appsignal::Rack::EventHandler` middleware is added. It will add the `response_status` tag to samples and track a `response_status` metric with the request's response status code. See [our Rack integration docs](/ruby/integrations/rack) for more information.
* The `Appsignal::Rack::InstrumentationMiddleware` middleware replaces the `Appsignal::Rack::GenericInstrumentation` middleware. This new middleware does not set the action to "unknown" by default. It is required to set the action name in each app endpoint with `Appsignal.set_action` when only using the `InstrumentationMiddleware` middleware. See [our Rack integration docs](/ruby/integrations/rack) for more information.
* `Appsignal::Grape::Middleware` is renamed to `Appsignal::Rack::GrapeMiddleware`.
* The `Appsignal::Rack::StreamingListener` is replaced by `Appsignal::Rack::InstrumentationMiddleware`.
* The `Appsignal::Hooks::SidekiqPlugin` is removed without replacement.
* The Grape, Hanami, Padrino and Sinatra integrations now use the `Appsignal.load` mechanism to integrate with these libraries. Please follow the installation guides for these libraries to update to the new loading mechanism.
  * [Sinatra](/ruby/integrations/sinatra)
  * [Hanami](/ruby/integrations/hanami)
  * [Grape](/ruby/integrations/grape)
  * [Padrino](/ruby/integrations/padrino)
  * Using more than one of these libraries or mounting them on a Rails app? [Follow this guide](/ruby/integrations/rack-libraries) as well.
* The errors and performance issues reported by our Rake integration are now reported under the "rake" namespace.

### Custom instrumentation

* The [`Appsignal.report_error` helper](/ruby/instrumentation/exception-handling) makes it easier to always report errors, without knowing the difference between the `Appsignal.set_error` and `Appsignal.send_error` helpers.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Before
  Appsignal.set_error(error)
  Appsignal.send_error(error, :tag => "value", "custom namespace")

  # After
  Appsignal.report_error(error)
  Appsignal.report_error(error) do
    Appsignal.set_namespace("custom namespace")
    Appsignal.add_tags(:tag => "value")
  end
  ```
</CodeGroup>

* Multiple errors can be reported on one transaction with the [`Appsignal.report_error` helper](/ruby/instrumentation/exception-handling#reporting-multiple-exceptions).
* The `Appsignal.monitor_transaction` and `Appsignal.monitor_single_transaction` helpers are replaced by the [`Appsignal.monitor` and `Appsignal.monitor_and_stop` helpers](/ruby/instrumentation/background-jobs).
  * Note: newer versions of the Ruby gem have [deprecated the `Appsignal.monitor_and_stop` helper](/ruby/instrumentation/background-jobs#stop-requirement).
* New helpers for adding tags and sample data (parameters, request headers, session data and custom data) to transactions. See the [customization helpers](/guides/custom-data) documentation for more information.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Before
  Appsignal.tag_request(:tag => "value")
  Appsignal::Transaction.current.set_sample_data(
    "custom_data",
    :i18n => {
      :locale => "en_GB",
      :default_locale => "en_US"
    }
  )

  # After
  Appsignal.add_tags(:tag => "value")
  Appsignal.add_custom_data(
    :i18n => {
      :locale => "en_GB",
      :default_locale => "en_US"
    }
  )
  ```
</CodeGroup>

* Sample data is amended by default. Adding additional parameters, request headers, session data and custom data will merge it with the previously set values. See the [customization helpers](/guides/custom-data) documentation for more information.
* The `Appsignal::Transaction::GenericRequest` helper is removed. Use our [customization helpers](/guides/custom-data) to add metadata to the transaction.
* The `appsignal.action` and `appsignal.route` request environment keys are removed. Use the `Appsignal.set_action` helper to set the action name instead.
* The `tags` and `namespace` arguments were removed from the `Appsignal.set_error` and `Appsignal.send_error` helpers. Use the block method to customize the transaction before it's sent instead. See [our exception handling guide](/ruby/instrumentation/exception-handling) for more information.
* The `Appsignal::Minutely` constant is renamed to `Appsignal::Probes`.
* The `Appsignal::Probes.probes.register` method is replaced with `Appsignal::Probes.register`. See [our minutely probes documentation](/ruby/instrumentation/minutely-probes) for more information.
* The `Appsignal.set_host_gauge` and `Appsignal.set_process_gauge` helpers are removed without replacement. Instead, tag the metric with the hostname or process ID using the [`Appsignal.set_gauge` helper](/metrics/custom#gauge).
* The `Appsignal.listen_for_error` helper is removed without replacement. Instead, manually rescue errors using `rescue => error` and report them using the [`Appsignal.report_error` helper](/ruby/instrumentation/exception-handling#appsignalreport_error).

### Library internals

Listed here are changes to library internals that may have previously been used in our documentation or support cases. We recommend you refrain from relying on these anymore. These are private components and may change at any moment. Breaking changes include:

* The `Appsignal::Transaction.create` and `Appsignal::Transaction.new` methods no longer accept the `id`, `request`, and `options` arguments. The transaction ID is now automatically generated.
  * Instead of manually creating a Transaction object, use the [`Appsignal.monitor` helper](/ruby/instrumentation/background-jobs) instead.
  * To set metadata on the transaction, use our [customization helpers](/guides/custom-data).
* The `Appsignal::Transaction#set_http_or_background_action` method is removed. Use the `Appsignal.set_action` helper instead.
* The `Appsignal::Transaction#set_http_or_background_queue_start` method is removed. Use the `Appsignal::Transaction#set_queue_start` helper instead.
* The `AppSignal::Transaction#params=` helper is removed. Use the [`Appsignal.add_params` helper](/guides/custom-data/request-parameters) instead.

## Welcome to 4.x!

This guide should cover upgrading most Ruby applications to AppSignal Ruby gem 4.x. If you have any questions, ran into errors, or would like assistance upgrading to the new version, please don't hesitate to [contact support][contact].

[contact]: mailto:support@appsignal.com