Instrumentation for scripts and background jobs

AppSignal supports many gems out-of-the-box and doesn't require additional instrumentation to report error and performance data. For custom scripts and libraries we don't support, you can add monitoring by following this guide.

Monitoring scripts

An AppSignal sample is composed of two elements: a transaction and events. Before reporting events with our instrumentation helpers, you must first create a transaction.

Use the Appsignal.monitor helper to create a transaction and make it active for the duration of the given block.

The monitor helper will report the instrumented code block as performance measurements listed in the Performance section in the AppSignal UI, grouped by action name. It will track the block's duration and report exceptions that occur inside.

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

The monitor helper accepts two keyword arguments:

• namespace (Optional): Customize the namespace of the transaction. Defaults to "web".
• action (Required): We group the script's samples by this action name for issue creation and notifications. Without an action name, no information about the monitored block is reported, because we don't know how to group the data.

Set the action name later

The Appsignal.monitor helper's action argument can be left nil or explicitly set to :set_later, but only if the Appsignal.set_action helper is still called inside the block to set the action name. Without an action name, no data is reported about the instrumented block. This method of setting the action name can be helpful if the action name can only be determined in a processing step inside the block.

class CronJobScript
  def call
    Appsignal.monitor(
      :action => :set_later
    ) do
      # Your code
 
      # Set action name later
      Appsignal.set_action("My action name")
    end
  end
end

Instrumentation events

By default, the Ruby gem will report events from supported integrations. These events will appear in the event timeline. Use our instrumentation helpers to add your own events to the event timeline. This creates a more detailed breakdown of what's happening inside the monitored block.

class CronJobScript
  def call
    Appsignal.monitor(
      :namespace => "cron",
      :action    => "CronJobScript#call"
    ) do
      Appsignal.instrument "fetch.plans" do
        # Complex part of fetching payment plans
      end
 
      Appsignal.instrument "send.invoices" do
        # Complex part of sending invoices
      end
    end
  end
end

Stop requirement

For scripts running on short-lived hosts, it is required to stop the AppSignal Ruby gem before the script exits. This will ensure it reports the data from the script to AppSignal before the host shuts down.

This behavior is only needed in such scenarios like:

• When a scheduled task (a cron job) is run by a hosting service.
• When a script is run on a container that starts to run this script and shuts down when the script exits.
• When a script is run on a Heroku runner, or similar hosting providers.

It is not needed to stop the AppSignal Ruby gem if the host on which the script is started, continues to run after the script has exited.

AppSignal is stopped automatically when the script exits and a container or hosting environment like Heroku is detected.

This behavior is controlled by the enable_at_exit_hook option. Ensure this option is set to true for scripts that require AppSignal to be stopped, if it's not automatically detected.

It may be needed to add an additional sleep call of a couple seconds to ensure there's enough time to send all the data. Use the at_exit usage example from the code below if needed.

# This block is called after all tasks are ran
# Ensures the AppSignal agent has enough time to send the data to the AppSignal servers
at_exit { sleep 10 }
 
# Your script code

Monitor and stop helper

If your process always runs one task/job and immediately exits afterward, you can use the Appsignal.monitor_and_stop helper. This will ensure that AppSignal stops automatically after the block has been executed.

# This block is called right before the script exits
# Ensures the AppSignal agent has enough time to send the data to the AppSignal servers
at_exit do
  sleep 10
end
 
class CronJobScript
  def call
    Appsignal.monitor_and_stop(
      :namespace => "cron",
      :action    => "CronJobScript#call"
    ) do
      # Your code
    end
  end
end