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

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.

# Gemfile
 
gem "appsignal", "~> 3.0"

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.

# Gemfile
 
gem "appsignal"

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. 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 to configure AppSignal in Ruby.
• The skip_session_data option is removed. Use the send_session_data option instead.
• The debug option is removed. Use the log_level: debug option instead.
• The transaction_debug_mode option is removed. Use the log_level: trace option instead.
• The working_dir_path option is removed. Use the working_directory_path option 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 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 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
  • Hanami
  • Grape
  • Padrino
  • Using more than one of these libraries or mounting them on a Rails app? Follow this guide 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 makes it easier to always report errors, without knowing the difference between the Appsignal.set_error and Appsignal.send_error helpers.

  Ruby

  # 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

• Multiple errors can be reported on one transaction with the Appsignal.report_error helper.

• The Appsignal.monitor_transaction and Appsignal.monitor_single_transaction helpers are replaced by the Appsignal.monitor and Appsignal.monitor_and_stop helpers.

  • Note: newer versions of the Ruby gem have deprecated the Appsignal.monitor_and_stop helper.

• New helpers for adding tags and sample data (parameters, request headers, session data and custom data) to transactions. See the customization helpers documentation for more information.

  Ruby

  # 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"
    }
  )

• 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 documentation for more information.

• The Appsignal::Transaction::GenericRequest helper is removed. Use our customization helpers 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 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 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.

• 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.

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 instead.
  • To set metadata on the transaction, use our customization helpers.
• 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 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.