Ruby on Rails

Ruby on Rails is supported out-of-the-box by AppSignal. To install follow the installation steps in AppSignal, start by clicking 'Add app' on the accounts screen.

The AppSignal integration for Rails works by tracking exceptions and performance in requests. When an error occurs in a controller during a request AppSignal will report it. Performance issues will be based on the duration of a request and create a timeline of events detailing which parts of the application took the longest.

Active Job

See our Active Job page for more information on how our Active Job instrumentation works.

Configure AppSignal in an initializer

We recommend using our config/appsignal.yml config file or environment variables to configure AppSignal. By default, it's not possible to configure AppSignal from a Rails initializer, because AppSignal loads before your application's initializers, in order to be able to report errors that take place during initialization.

To configure AppSignal in a Rails initializer, first configure Rails to start AppSignal after the app's initializers have run.

# config/application.rb
 
# ...
 
module MyApp
  class Application < Rails::Application
    # Add this line
    config.appsignal.start_at = :after_initialize
 
    # Other config
  end
end

Then, in the initializer:

# config/initializers/appsignal.rb
 
Appsignal.configure do |config|
  config.ignore_actions = ["My action"]
end

Do not call Appsignal.start in the initializers. The Ruby gem will start AppSignal automatically when Rails has run all initializers.

When a Rails app is configured to start AppSignal after the initializers have loaded, it is no longer possible to report errors from initializers when booting Rails app.

Error reporting from initializers

By default, AppSignal reports errors that occur in controller, Rake tasks and Active Job jobs. It does not report errors that occur when the application is booting, before the Rails initializers. To do get notified when these errors occur, adding the following to your config.ru file, around the line that requires the environment.rb file.

# config.ru
begin
  require ::File.expand_path("../config/environment",  __FILE__)
rescue Exception => error
  Appsignal.send_error(error)
  raise
end

The errors that occur here will not be grouped under an incident with an action name.

Backtrace cleaner

With the Rails integration, AppSignal will run the backtrace of each exception through the Rails backtrace cleaner. This cleaner gives you the option to modify or filter out unwanted backtrace lines, removing clutter and noise from the backtrace.

You can add or remove filters and silencers to the default configuration.

Filters will mutate the given line. An example would be to remove the Rails.root prefix.

Silencers will remove the line from the backtrace, if the given expression returns true. You can add these additional backtrace cleaner rules in an initialize.

For example:

# config/initializers/backtrace_cleaner.rb
bc = Rails.backtrace_cleaner
bc.add_filter { |line| line.gsub(Rails.root.to_s, '<root>') }
bc.add_silencer { |line| line.index('<root>').nil? and line.index('/') == 0 }
bc.add_silencer { |line| line.index('<root>/vendor/') == 0 }

For more information about the backtrace cleaner, see the Rails BacktraceCleaner documentation.

Error reporter

AppSignal reports errors raised via ActiveSupport::ErrorReporter by default. ActiveSupport::ErrorReporter was introduced in Rails 7.0 to standardize custom error reporting.

You can disable this functionality with the enable_rails_error_reporter configuration option.

If a transaction is active in the context an error is reported through the Rails error reporter, it will include the same metadata and sample data as the active transaction: namespace, action name, tags, custom data, parameters, etc.

# In both scenarios, the error is reported by AppSignal
Rails.error.handle do
  raise "some error"
end
 
Rails.error.record do
  raise "some error"
end

Namespace and action from the current transaction

When reporting errors, we determine the namespace and action name in which it takes place, such as a controller or background job, on a best-effort basis. The incident namespace and action name will not always be set or be accurate.

If an AppSignal transaction is active (like in a web request or background job) the error reported with Rails.error.handle/record will have the same namespace, action name, tags, parameters, custom data, etc. as the active transaction. If no AppSignal transaction is active, no namespace, action name, tags, etc. will be set by default.

Namespace and action from the context

If you want to change the reported error's namespace and action name without changing them on the already active AppSignal transaction, you can customize this on the error reporter call.

# The error reported here will have the "custom_namespace" namespace
# and "CustomizedActionName#index" action name
Rails.error.handle(:context => { :appsignal => { :namespace => "custom_namespace", :action => "CustomizedActionName#index" } }) do
  raise "some error"
end

Tags from the active transaction

By default, the request/job's transaction tags are copied to the error reporter's error AppSignal transaction from the request/job's transaction.

# Rails controller example using a before_action callback
class ExamplesController < ApplicationController
  before_action do
    Appsignal.add_tags(:tag1 => "value1", :tag2 => "value2")
  end
 
  def index
    # The error reported here will have the same tags set
    # as in the `before_action` callback
    Rails.error.handle do
      raise "some error"
    end
  end
end

Tags from context

You can add tags to a reported error by using context in the Rails.error.handle/record call. These tags will only be set on the error reported with the Rails.error.handle/record methods.

Rails.error.handle(:context => { :tag1 => "value1", :tag2 => "value2" }) do
  raise "some error"
end

The same tagging limitations apply as for using Appsignal.add_tags.

Ruby gem 3 legacy behavior

In AppSignal for Ruby gem version 3 the error reporting behavior is different.

• Errors reported with the Rails.error.handle method are reported to AppSignal.
• Errors reported with Rails.error.record are not reported to AppSignal to avoid reporting the error twice when it's being reported by our Rails error reporting middleware.

All errors reported with the Rails error reporter are reported as separate errors. They do not always include the same metadata and sample data from any active AppSignal transaction. See the section for context inheritance limitations for more information.

# Reported by AppSignal
Rails.error.handle do
  raise "some error"
end
 
# NOT reported by AppSignal
Rails.error.record do
  raise "some error"
end

Context inheritance limitations

In Ruby gem 3 the context inheritance from the active transaction is limited. The metadata and some of the sample data is only copied if it set at the time Rails.error.handle/record is called.

In practice this mean Rails controllers and Active Job jobs will be accurately reported. Other libraries like Sidekiq jobs, no action name is set when reporting errors with Rails.error.handle.

Tags set after Rails.error.handle/record is called are not reported for the error reported using this helper.

Runners

AppSignal will automatically report errors inside Rails runners. Some manual setup is also required to instrument a runner's performance.

We recommend putting the runner's code in a separate file and wrap it in the Appsignal.monitor_and_stop helper, as shown in the example below.

bin/rails runner path_to_file.rb

# path_to_file.rb
 
Appsignal.monitor_and_stop(:namespace => :runner, :action => "Runner name") do
  # Some code
end