We've released version 4.0 of the AppSignal gem, which offers significant changes and improvements to our Ruby integration.

In this blog post, we'll cover the core updates and explain the steps you need to take before you upgrade.

One Helper For All Your Error Reporting Needs

AppSignal for Ruby 4.0 introduces new functionality to our report_error helper, which we first introduced in 3.10.0.

The Appsignal.report_error helper lets you capture multiple exceptions from a single request, providing high-context error insights with just one line of code.

Here's how to use it to report multiple errors:

# Example Rails controller action
def index
  # Shared metadata for all errors in this request
  Appsignal.add_tags("user_id" => current_user.id)
 
  begin
    raise "whoops"
  rescue => error
    Appsignal.report_error(error)
  end
 
  begin
    raise "oh no, another error"
  rescue => error
    Appsignal.report_error(error) do
      # Add a tag for just this error
      Appsignal.add_tags(:tag_for_just_this_error => "some value")
    end
  end
 
  # Both errors will have the "user_id" tag
  # The second error will also have the "tag_for_just_this_error" tag
end

Improved Helpers for Better Background Job Monitoring

While we offer out-of-the-box support for most of the integrations Ruby apps use, like Resque, Sidekiq, and Delayed Job, we've improved our helpers. It's now easier for you to monitor custom scripts and unsupported libraries with the new Appsignal.monitor helper.

With Appsignal.monitor, you no longer need to create transactions manually, add instrumentations, and catch exceptions; you can now instrument your code in a simple block:

class CronJobScript
  def call
    Appsignal.monitor(
      :namespace => "cron",
      :action    => "CronJobScript#call"
    ) do
      # Your code
    end
  end
end

Sample Data Is Now Amendable

Sample data adds contextual data to samples (like relevant IDs from models, the application state in a request/background job, and other specific information from your app), so you get the most out of your monitoring data.

In AppSignal for Ruby 4.0, sample data is easier to use, thanks to its amendability. You can add the same type of data multiple times, as and when it makes sense in your app's flow.

def process_order
    Appsignal.add_session_data(
        :user_id => @current_user.id,
        :order_data => { :state => "processing" }
    )
 
    processed_order = OrderProcessorHelper(order)
 
    # Add more session data
    Appsignal.add_session_data(
        :order_data => {
            :state => processed_order.state,
            :processed_at => processed_order.processed_at
        }
    )
end

This data will be visible when inspecting a request in AppSignal.

A New Way to Configure AppSignal for Ruby

We've made some changes to how you configure AppSignal, including removing and replacing some configuration options.

The new Appsignal.configure helper will automatically detect your app environment.

# Old way
Appsignal.config = Appsignal::Config.new(
  File.expand_path("../", __FILE__),
  "application environment",
  :activejob_report_errors => "discard",
  :sidekiq_report_errors => "discard",
  :ignore_actions => ["My ignored action", "My other ignored action"],
  :request_headers => Appsignal::Config::DEFAULT_CONFIG[:request_headers] + ["MY_HTTP_HEADER"],
  :send_params => true,
  :enable_host_metrics => false
)
 
# New way
Appsignal.configure do |config|
  config.activejob_report_errors = "discard"
  config.sidekiq_report_errors = :discard
  config.ignore_actions = ["My ignored action", "My other ignored action"]
  config.request_headers << "MY_HTTP_HEADER"
  config.send_params = true
  config.enable_host_metrics = false
end

This provides a more stable, convenient and efficient way to configure your AppSignal integration (whether you're using Rails, Sinatra, or any other integration we support), while ensuring the configuration defaults remain intact.

A full list of changes to our configuration can be found in our documentation about upgrading from AppSignal for Ruby 3.x to 4.x and Ruby changelog.

How to Upgrade to 4.0

Depending on what version of the AppSignal gem you currently use, upgrading immediately to 4.0 may introduce breaking changes. For that reason, we recommend taking the following steps to ensure a smooth upgrade process.

1. Upgrade to the Latest Version of AppSignal (3.0)

To do this, update the gem's version lock to ~> 3.0 in your Gemfile:

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

Save your Gemfile and run:

bundle update appsignal

2. Resolve Errors and Deprecation Warnings

These will be printed in your STDERR output and logged in your app's appsignal.log file.

3. Upgrade to the Latest 4.x Version of AppSignal

Once you've fixed all errors and deprecation warnings, you can upgrade to 4.x by removing the version lock from your Gemfile:

# Gemfile
gem "appsignal"

After updating your Gemfile, run:

bundle update appsignal

Our upgrading from AppSignal for Ruby 3.x to 4.x documentation explains this process in more detail and highlights the fundamental changes between AppSignal 3.x and 4.0.

Get Monitoring with AppSignal for Ruby v4.0

If you're not yet an AppSignal customer, you can sign up today for a free 30-day trial (no credit card required) and be up and monitoring in less time than it takes to drink a cup of coffee.

We're here to help if you have any trouble upgrading to 4.x or monitoring questions in general. Just drop us an email!