Rake task monitoring

Every exception recorded in a Rake task will be sent to AppSignal and filed under the "Background" namespace. Note that we only track exceptions in Rake tasks. There is no performance monitoring for Rake tasks.

(To manually integrate performance monitoring in select Rake tasks please see our integration guide and custom instrumentation guide.)

Depending on what version of the AppSignal gem you use and in what context some manual steps are required.

Integrations

Rails applications

For Rails applications make sure you depend on the :environment task. This loads the Rails application into memory and starts AppSignal as part of the application.

# lib/tasks/my_task.rb
task :my_task => :environment do
  # do stuff
end

Rakefile

Your Rails application's Rakefile should look something like the example below. This should already be the case, no need to change it.

# Rakefile
require File.expand_path("../config/application", __FILE__)
 
# Only require this file for gem version < 1.0
# require "appsignal/integrations/rake"
 
Rails.application.load_tasks

(For older versions of the AppSignal gem, versions < 1, you will need to require the Rake integration manually. It is automatically loaded for version 1.x and higher.)

Ruby applications

For pure Ruby applications some extra steps are required to load AppSignal. AppSignal needs to be required, configured and loaded. See also our integration guide.

# Rakefile
require "appsignal"
 
Appsignal.start
 
task :foo do
  raise "bar"
end

Monitoring Rake task performance

To monitor Rake task performance and all events that occur in the task, configure AppSignal with the enable_rake_performance_instrumentation config option set to true.

With this feature enabled, all Rake tasks will instrumented and counted towards your plan.

Appsignal.stop requirement

Some scenarios require Appsignal.stop to be called to report the AppSignal data from in Rake tasks. Appsignal.stop flushes all data from the application to the AppSignal agent and sends it to the AppSignal servers before the task container stops.

This method is called for you when an error is raised in a task.

# Rakefile
task :foo do
  # Is automatically sent to AppSignal
  raise "My error"
end

Appsignal.stop should be called when Rake task performance monitoring disabled for any task that:

1. Does not raise an Error.
2. Calls Appsignal.send_error or calls any custom metrics helper method.

# Rakefile
task :foo do
  # Called after all tasks are ran
  # The argument "rake" is the name of the parent process name which is being
  # stopped and logs it as the reason why AppSignal is stopping.
  at_exit do
    Appsignal.stop "rake"
  end
 
  # Helper methods that require an `Appsignal.stop` call if no error is raised
  Appsignal.send_error StandardError.new("bar")
  # Custom metrics helpers: https://docs.appsignal.com/metrics/custom.html
  Appsignal.increment_counter "my_custom_counter"
end

For short lived hosts, such as containers and Heroku schedulers, an additional step needs to be taken to ensure the AppSignal agent has time to send the data before the host is shut down. Read on in the next section.

Rake tasks and containers

When running a single Rake task on a one-off host (e.g. with Docker containers, Kubernetes or Heroku schedulers) there are three requirements. This guarantees that the app AppSignal extension has time to flush the data to the agent and the agent has time to send the data to our API before shutting (the container) down.

The requirements are:

• Appsignal.stop must be called in the Rake task.
  • When Rake task performance monitoring is enabled, this is done automatically for all tasks.
• running_in_container must be set to true in the config.
  • For most containers types running_in_container is automatically set to true when detected, for others manual configuration is required.
• A sleep of e.g. 5 seconds to give AppSignal agent time to sent the data

An example of how Appsignal.stop is called in the Rakefile:

# Rakefile
# One-off host example task
task :foo do
  # Called after all tasks are ran
  # The argument "rake" is the name of the parent process name which is being
  # stopped and logs it as the reason why AppSignal is stopping.
  at_exit do
    Appsignal.stop "rake"
    sleep 5 # For one-off hosts, give the AppSignal agent time to send the data
  end
 
  # Tracking data with AppSignal in your task
  Appsignal.increment_counter "my_custom_counter"
end

Note: A sleep of 5 seconds was added to the end of the Rake task example in the example above. This is required for tasks that are run on one-off hosts. When the task completes, the process stops. The Appsignal.stop call flushes all the transaction data currently in the AppSignal extension to our agent. It then sleeps for 5 seconds to allow the agent to send the data before shutting down.

Examples

Rake application

See our example repository for a Ruby + Rake + AppSignal example application.