This guide covers the major changes between the 9.x and 10.x series of the Ruby agent and how to have a successful migration.
Summary
Main changes in v10.0 include:
- Removed support for Ruby 2.4 and 2.5
- Removed Cross Application Tracing (CAT) and related APIs
- Removed support for recording deployments via the agent
- Removed
NewRelic::Agent::SqlSampler#notice_sqland simplifiedNewRelic::Agent::DatastoresAPIs - Removed support for Puma versions < 3.9.0
- Removed the experimental feature Configurable Security Policies (CSP)
- Renamed ActiveJob metrics and segments
- Renamed
bin/newreliccommand tobin/newrelic_rpm
See the milestone for 10.0 for more information.
Alongside these breaking changes are several other improvements. See the CHANGELOG for more details.
Removed support for Ruby 2.4 and 2.5
Ruby 2.4 and 2.5 are no longer supported by the Ruby agent. To continue using the latest Ruby agent version, please update to Ruby 2.6.0 or higher.
New Relic continues to support certain older Ruby versions even after they have fallen out of the officially supported maintenance window provided by the Ruby language development team. For example, as of March 31, 2026 the oldest Ruby version supported by the Ruby team will be version 3.3, whereas with Ruby agent version 10.0, Ruby versions 2.6 and higher are still supported. For more information about official Ruby team support of Ruby versions, see Ruby Maintenance Branches.
Removed Cross Application Tracing (CAT) and Related APIs
Cross Application Tracing (CAT) has been removed in favor of Distributed Tracing. CAT used New Relic-specific headers for linking transactions between APM-monitored applications, while Distributed Tracing adopts the W3C Trace Context. To turn on Distributed Tracing, set the configuration option distributed_tracing.enabled to true.
distributed_tracing.enabled: trueThe configuration option cross_application_tracer.enabled has been removed along with the following public API methods:
| Removed CAT API | Distributed Tracing Replacement | Context |
|---|---|---|
NewRelic::Agent::External.process_request_metadata | NewRelic::Agent::DistributedTracing.accept_distributed_trace_headers | Reads W3C Trace Context headers from an incoming request to link the service to the upstream trace. |
NewRelic::Agent::External.get_response_metadata | No equivalent needed | Response metadata is obsolete; linkage is handled by W3C headers in the request. |
NewRelic::Agent::Transaction::ExternalRequestSegment#process_response_metadata | No equivalent needed | Response-based processing is removed in favor of request header propagation. |
NewRelic::Agent::Transaction::ExternalRequestSegment#get_request_metadata | NewRelic::Agent::DistributedTracing.insert_distributed_trace_headers | Creates and adds W3C Trace Context headers to the outbound request headers. |
NewRelic::Agent::Transaction::ExternalRequestSegment#read_response_headers | No equivalent needed | Trace linkage does not require reading response headers. |
Learn more about using Distributed Tracing APIs.
Removed support for recording deployments via the agent
The agent no longer supports the ability to send application deployment information using a Capistrano recipe or the newrelic deployments CLI command. To track changes and deployments in New Relic, please see our guide to Change Tracking for a list of available options.
Removed NewRelic::Agent::SqlSampler#notice_sql and simplified NewRelic::Agent::Datastores APIs
Removed the NewRelic::Agent::SqlSampler#notice_sql method
The NewRelic::Agent::SqlSampler#notice_sql method has been removed. To track SQL queries, you should use the NewRelic::Agent::Datastores.notice_sql method instead.
Removed unused arguments from various NewRelic::Agent::Datastores APIs
Several NewRelic::Agent::Datastores APIs have been simplified by removing redundant arguments. Timing (elapsed) and metric scope information are automatically derived from the current segment.
The following APIs have been updated:
| Old API | New API | Change |
|---|---|---|
NewRelic::Agent::Datastores.notice_sql(query, scoped_metric, elapsed) | NewRelic::Agent::Datastores.notice_sql(query) | Removed scoped_metric and elapsed arguments. |
NewRelic::Agent::Datastores.notice_statement(statement, elapsed) | NewRelic::Agent::Datastores.notice_statement(statement) | Removed elapsed argument. |
NewRelic::Agent::Datastores.wrap(...) do \|result, scoped_metric, elapsed_time\| | NewRelic::Agent::Datastores.wrap(...) do \|result\| | Removed scoped_metric and elapsed_time from the callback block arguments. |
Removed support for Puma versions < 3.9.0
The minimum version of Puma now supported is 3.9.0 or higher. If using Puma, upgrade to version 3.9.0 or later before upgrading the agent.
Removed the experimental feature Configurable Security Policies (CSP)
The experimental feature, Configurable Security Policies (CSP), is no longer supported and has been removed. The agent's default security settings automatically provide security for your APM data, however, you can further restrict the information that New Relic receives using high-security mode.
Renamed ActiveJob metrics and segments
ActiveJob metrics and segments have been updated to include the job's class name for more specific reporting. Update all custom dashboards and NRQL alerts that query ActiveJob metrics and segments to reflect the new format.
Old format:
"Ruby/ActiveJob/#{QueueName}/#{Method}" # metrics"ActiveJob/#{Adapter}/Queue/#{Event}/Named/#{JobQueueName}" # segmentsNew format:
"Ruby/ActiveJob/#{QueueName}/#{JobClassName}/#{Method}" # metrics"ActiveJob/#{Adapter}/Queue/#{Event}/Named/#{JobQueueName}/#{JobClassName}" # segmentsRenamed bin/newrelic command to bin/newrelic_rpm
The executable file for the agent's CLI has been renamed from bin/newrelic to bin/newrelic_rpm. This change resolves a name collision with the standalone New Relic CLI tool.
Old command:
$bin/newrelic installNew command:
$bin/newrelic_rpm install