Resque instrumentation

In addition to your web application itself, the New Relic Ruby agent can also instrument your Resque jobs.

Capturing job arguments

Starting with Ruby agent version 3.6.9, you can optionally configure the Ruby agent to capture Resque job arguments in transaction traces and traced errors. This can be especially useful in attempting to reproduce failed jobs. By default this feature is off in case your job arguments contain sensitive information. To enable this feature, edit your newrelic.yml as appropriate for your agent version:

• For newrelic_rpm 3.12.0 or higher: attributes.include: job.resque.args.*
• For newrelic_rpm 3.6.9 to 3.11.X: resque.capture_params: true

This feature is distinct from the generic capture_params top-level setting, which controls whether HTTP request parameters are captured on transaction traces and traced errors for web requests. You can configure these two settings independently.

Resque versions 1.23.1 or higher

If you are running Resque 1.23.1 or higher, you should not need to make any code changes outside of the normal agent installation procedures in order for New Relic's Resque instrumentation to work.

Exception: If you have leftover calls to NewRelic::Agent methods from your Resque before_first_fork, before_fork, or after_fork hooks from when you were running an older version of Resque, be sure to remove those calls after upgrading to Resque 1.23.1 or higher.

Alternate forking modes

The resque-multi-job-forks or resque-jobs-per-fork gems change the forking behavior of Resque so that it will not fork for each individual job, but instead fork once per batch of jobs. Similarly, you can set the FORK_PER_JOB environment variable to false in order to completely disable forking in Resque.

If you use any of these alternate forking modes in your application, make sure you are running Ruby agent version 3.9.7 or higher. Earlier versions of the Ruby agent do not work correctly with these alternate forking modes. If you are upgrading to 3.9.7 or higher, make sure to remove any direct calls to NewRelic::Agent methods such as manual_start or after_fork that you may have previously been using in order to get the agent to work in these environments.

Old Resque versions (< 1.23.1)

It is possible to use New Relic's Ruby agent with Resque versions older than 1.23.1. However, New Relic recommends that you upgrade to Resque 1.23.1 or higher for best results.

Many applications use the hooks exposed by Resque (before_fork, after_fork, etc.) in order to inject custom code at critical points during the lifetime of Resque jobs. The New Relic Ruby agent also must use these hooks in order to be able to place its instrumentation.

Resque versions before 1.23.1 do not allow hooks to be defined multiple times; the last definition will take precedence. If you cannot upgrade to a Resque version >= 1.23.1 (which allows hooks to be defined multiple times without overwriting each other), you can modify your custom Resque hooks by adding the necessary New Relic code. Here is an example.

Example: Modifying custom Resque hooks

You may omit definitions for any hooks that you have no custom code for. They will be automatically installed by the agent in this case.

Resque.before_first_fork do
  # ... your custom hook code ...
  NewRelic::Agent.manual_start(:dispatcher => :resque,
                               :sync_startup => true,
                               :start_channel_listener => true)
end
    
Resque.before_fork do |job|
  # ... your custom hook code ...
  NewRelic::Agent.register_report_channel(job.object_id)
end
    
Resque.after_fork do |job|
  # ... your custom hook code ...
  NewRelic::Agent.after_fork(:report_to_channel => job.object_id,
                             :report_instance_busy => false)
end

Deadlocking jobs

Some customers (particularly those with very high job throughput) have reported intermittent deadlocks in their Resque worker processes with the Ruby agent enabled. These deadlocks are due to a bad interaction between the background thread that the Ruby agent uses to send data to New Relic servers and Resque's forking behavior.

Use either of these options to resolve these issues:

• Disable Resque's forking behavior by setting the FORK_PER_JOB environment variable to false when spawning Resque processes.
• Use the resolv-replace library from Ruby's standard library to replace Ruby's native DNS resolution code with a pure Ruby version.

The Ruby agent uses a background thread in the Resque master process to send data to the New Relic collector. In some environments, this thread will acquire a native lock during DNS resolution (when resolving the hostnames of New Relic collectors).

If this native lock is held by the background thread while the main Resque master process's main thread calls fork to create a child process, it will still be marked as held in the forked child process. However, since fork only copies the calling thread, the background thread that was holding the native lock will not exist in the child process, and thus the native lock will never be released. If the child process attempts to do any DNS resolution, it will attempt to acquire the same native lock and deadlock. To avoid this Github issue, use resolv-replace instead of Ruby's default DNS resolution path.