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 short-lived processes, like scripts run by cron jobs, it's necessary to call Appsignal.stop before the Ruby process exits. Calling stop ensures that all the instrumentation data gets flushed to the AppSignal system agent and doesn't get lost.

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.

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