Monitor Ruby background processes

Our Ruby agent automatically instruments several common background job frameworks. You can also customize it to trace any background tasks. Data from background jobs appears in the Transactions page in APM as Non-web transactions.

Supported frameworks

The following background job frameworks are supported by default in recent versions of the Ruby agent:

• Resque instrumentation (Ruby agent 3.4.0)
• Sidekiq instrumentation (Ruby agent 3.6.0)
• Delayed::Job instrumentation (Ruby agent 2.10)

If you are using these frameworks, monitoring background jobs typically doesn't require additional configuration.

Monitor custom background jobs

You can instrument custom background jobs to appear in the APM Transactions page as Non-web transactions. To monitor Non-web transactions while using an unsupported framework, you must add custom instrumentation.

As an example, a background job periodically runs a task called SalesOrganization#find_new_leads.

1. Add the ControllerInstrumentation module.

2. Use the add_transaction_tracer directive below the method definition

3. Add :category => :task to tell the agent this trace is a Non-web transaction.

   require 'newrelic_rpm'
   
   class SalesOrganization
     include
       ::NewRelic::Agent::Instrumentation::ControllerInstrumentation
     def find_new_leads
       ...
     end
     add_transaction_tracer :find_new_leads, :category => :task
   end

   Copy

   You can pass a string to the :category, but values will only appear on the APM Transactions page if the string begins with OtherTransaction/.

Monitor custom background methods

Using the Ruby agent API, you can designate specific methods to trace the Non-web transactions. This gathers traces for slow running jobs and associates captured errors to transactions.

To instrument a class method, use the class singleton.

As an example, a background job periodically runs a task called SalesOrganization#find_new_leads.

1. Add the ControllerInstrumentation module below the method definition.

2. Use the add_transaction_tracer directive

3. Add :category => :task to tell the agent this trace is a Non-web transaction.

   require 'newrelic_rpm'
   
   class SalesOrganization
     def self.find_new_leads
       ...
     end
     class << self
         include
           ::NewRelic::Agent::Instrumentation::ControllerInstrumentation
       add_transaction_tracer :find_new_leads, :category => :task
     end
   end

   Copy

   For more information, see Ruby custom metrics.

Monitor short-lived processes

Make sure the process isn't running before the agent connects to the backend servers. To do so, make the Ruby agent synchronously connect to New Relic, rather than the default asynchronous behavior.

First, in your Gemfile, add require: false to the end of your newrelic_rpm gem installation:

gem 'newrelic_rpm', require: false

Then, call manual_start and pass in the :sync_startup => true option:

require 'new_relic/agent'
NewRelic::Agent.manual_start(:sync_startup => true)

Note: Most configuration options can be passed to manual start.

Using require 'new_relic/agent' will require the agent's code, and it will make sure the agent doesn't run until you manually start it.

If the process is shorter than the agent harvest cycle, you need to manually shut down the agent with ::NewRelic::Agent.shutdown to ensure all queued data is sent.

Configure newrelic.yml for background processes

Configuring your newrelic.yml depends on the context of the background application.

Report to an alternate application name

You can make jobs that run in the context of an existing New Relic web application appear under a different application name in the APM UI.

1. Begin before newrelic_rpm gets required by your worker code.

2. Set the NEW_RELIC_APP_NAME environment variable to the application name to use for your background jobs when starting your background worker processes. This will override the app_name setting in your newrelic.yml.

   bash

   Copy

   $
   NEW_RELIC_APP_NAME="My Background Jobs"
   $
   ./bin/my_background_worker.rb

Ensure the agent starts

The Ruby agent will automatically start in most cases as soon as you require 'newrelic_rpm', unless the agent detects a blacklisted executable name, rake task name, or constant. This prevents it from starting during common rake tasks and interactive console sessions.

ENV['NRCONFIG'] ||= File.dirname(__FILE__) +
  '/../../config/newrelic.yml'
ENV['NEW_RELIC_LOG'] ||= File.dirname(__FILE__) +
  '/../../log/newrelic_agent.log'

For more information, see the documentation about controlling agent startup

Monitor scripts

The agent startup instructions apply when running background jobs in a daemon. If a script executes a single background task and exits, manually shut down the agent with ::NewRelic::Agent.shutdown when the script finishes. This ensures the New Relic collector receives the data. For example:

require 'newrelic_rpm'

class SalesOrganization
  include
    ::NewRelic::Agent::Instrumentation::ControllerInstrumentation
  def find_new_leads
    ...
  end
  add_transaction_tracer :find_new_leads, :category => :task
end

SalesOrganization.new.find_new_leads
::NewRelic::Agent.shutdown