Upgrade Ruby agent versions

To take the fullest advantage of New Relic's latest features, enhancements, and important security patches, New Relic strongly recommends that you follow the procedures to update your Ruby agent to the latest version. For additional information about specific agent updates, refer to the Ruby agent release notes.

Upgrade to Ruby agent version 4

In New Relic Ruby agent version 4.0.0, a number of APIs that had been deprecated for some time were deleted. If you use any of the following methods, you must update your API with the recommended replacement before upgrading to Ruby agent version 4.0.0 or higher.


Replace with NewRelic::Agent#notice_error


Replace with NewRelic::Agent.ignore_transaction


Replace with NewRelic::Agent.add_custom_attributes


Replace with NewRelic::Agent.add_custom_attributes

Delete the method call as it is no longer needed and had been returning an empty string.

  • If you had chained get_stats with increment_count, use:


  • If you had chained get_stats with record_data_point, use:


  • If you had chained get_stats_no_scope with increment_count, use:


  • If you had chained get_stats_no_scope with record_data_point, use:



Delete the method call as it only logs a warning message to the agent log.


Replace with NewRelic::Agent.drop_buffered_data


Replace with NewRelic::Agent.add_custom_attributes


Replace with NewRelic::Agent::Datastores::MetricHelper.metrics_for


Replace with NewRelic::Agent::Transaction.recording_web_transaction?


Replace with NewRelic::Agent::Transaction.abort_transaction!


Delete inclusions of this module. As of Ruby agent version 3.9.0, New Relic instruments Rack middlewares by default. As a result, this entire module has been deprecated.


Replace with NewRelic::Agent.record_metric


Replace with NewRelic::Agent.record_metric


Replace with either of these methods:

  • NewRelic::Agent::MethodTracer.trace_execution_scoped
  • NewRelic::Agent::MethodTracer.trace_execution_unscoped

Replace with NewRelic::Agent::MethodTracer.trace_execution_unscoped


Replace with NewRelic::Agent::MethodTracer.trace_execution_scoped


Replace with NewRelic::Agent.record_metric


Replace with NewRelic::Agent.record_metric


Delete the method call as it only logs a warning message to the agent log.


Delete the method call as it only logs a warning message to the agent log.


Delete the method call as it is no longer supported


Replace with NewRelic::NoticedError#exception_class_name


Delete inclusions of this module. The Ruby agent automatically collect errors for all Rack applications in either of these situations:

  • If automatic Rack middleware instrumentation is enabled
  • If you have manually added any New Relic middlewares into your middleware stack

Ruby versions not supported

End of life notification: As of January 26, 2015, New Relic will no longer accept data from Ruby agent versions earlier than 3.5.3.

These agent versions use an out-of-date protocol when communicating with New Relic's data collection services, and many also contain a potential security issue where they may incorrectly send sensitive data to New Relic's servers.

Determine your Ruby agent versions

To determine which Ruby agent versions your apps currently use:

  1. From the account dropdown in the New Relic UI, select Account settings > Connected agents.
  2. Optional: Sort by Oldest agent version.

Instrument JRuby

For correct instrumentation:

Otherwise, if your application has no transactions and you are using JRuby, you will not be able to see your CPU metrics. 

This was due to a bug in JRuby, where Process.times returned wall clock time instead of elapsed CPU time. That bug was fixed as of New Relic’s Ruby agent and JRuby 1.7.0.

For more help

Additional documentation resources include:

  • New Relic for Ruby (overview including compatibility and requirements, installation, configuration, troubleshooting, and known issues)
  • Ruby agent installation (Ruby gems, configuration file, and procedures to install, update, and uninstall)

Join the discussion about Ruby in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.