Ruby 10.x Migration Guide #22296
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,93 @@ | ||||||||||
| --- | ||||||||||
| title: Ruby agent 9.x to 10.x migration guide | ||||||||||
| tags: | ||||||||||
| - Agents | ||||||||||
| - Ruby agent | ||||||||||
| - Getting started | ||||||||||
| redirects: | ||||||||||
| - /docs/agents/ruby-agent/getting-started/migration-10x-guide | ||||||||||
| freshnessValidatedDate: never | ||||||||||
| --- | ||||||||||
|
|
||||||||||
| 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 [#summary] | ||||||||||
|
|
||||||||||
| Main changes in v10.0 include: | ||||||||||
|
|
||||||||||
| * [Removed support for Ruby 2.4 and 2.5](#ruby_2425) | ||||||||||
| * [Removed support for Puma versions < 3.9.0](#puma_version_removal) | ||||||||||
| * [Removed Cross Application Tracing (CAT) and related APIs](#cat_removal) | ||||||||||
| * [Renamed ActiveJob metrics](activejob_rename) | ||||||||||
| * [Renamed `bin/newrelic` command to `bin/newrelic_rpm`](renamed_cli_command) | ||||||||||
| * [Removed support for recording deployments via the agent](removed_record_deployments) | ||||||||||
| * [Removed the `NewRelic::Agent::SqlSampler#notice_sql` method](#sql_sampler_removal) | ||||||||||
| * [Removed unused arguments from various `NewRelic::Agent::Datastores` APIs](#unused_arguments_removal) | ||||||||||
| * [Improved configuration validation and coercion](improved_config_validation) | ||||||||||
| * [Removed the experimental feature Configurable Security Policies (CSP)](#csp_removal) | ||||||||||
|
|
||||||||||
| See the [milestone for 10.0](https://github.com/newrelic/newrelic-ruby-agent/milestone/119?closed=1) for more information. | ||||||||||
|
|
||||||||||
| Alongside these breaking changes are several other improvements. See the [CHANGELOG](https://github.com/newrelic/newrelic-ruby-agent/blob/main/CHANGELOG.md) for more details. | ||||||||||
|
|
||||||||||
| ## Removed support for Ruby 2.4 and 2.5 [#ruby_2425] | ||||||||||
|
|
||||||||||
| 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 (Ruby 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](https://www.ruby-lang.org/en/downloads/branches/). | ||||||||||
|
Contributor
There was a problem hiding this comment. I see
Suggested change
|
||||||||||
|
|
||||||||||
| ## Removed support for Puma versions < 3.9.0 [#puma_version_removal] | ||||||||||
|
|
||||||||||
| 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 Cross Application Tracing (CAT) and Related APIs [#cat_removal] | ||||||||||
|
|
||||||||||
| Cross Application Tracing (CAT) has been removed in favor of [Distributed Tracing](https://docs.newrelic.com/docs/distributed-tracing/concepts/introduction-distributed-tracing/). The configuration option `cross_application_tracer.enabled` has been removed along with the following public API methods: | ||||||||||
|
|
||||||||||
| * `NewRelic::Agent::External.process_request_metadata` | ||||||||||
| * `NewRelic::Agent::External.get_response_metadata` | ||||||||||
| * `NewRelic::Agent::Transaction::ExternalRequestSegment#process_response_metadata` | ||||||||||
| * `NewRelic::Agent::Transaction::ExternalRequestSegment#get_request_metadata` | ||||||||||
| * `NewRelic::Agent::Transaction::ExternalRequestSegment#read_response_headers` | ||||||||||
|
Comment on lines
+45
to
+51
Contributor
There was a problem hiding this comment. I think it's good to list all of these, but I think we should also have something about what configuration looks like if you want to turn on DT or keep it off. I know we have it documented elsewhere, but it may be worth it to repeat here. Copy/pasteable code snippets are nice in these kinds of guides. Also, if we have any related DT APIs that can be used instead of these CAT APIs, I'd like to call them out here too. |
||||||||||
|
|
||||||||||
| ## Renamed ActiveJob metrics [activejob_rename] | ||||||||||
|
|
||||||||||
| ActiveJob metrics 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 to reflect the new format. | ||||||||||
|
|
||||||||||
| * Old format: Ruby/ActiveJob/<QueueName>/<Method> | ||||||||||
| * New format: Ruby/ActiveJob/<ClassName>/<QueueName>/<Method> | ||||||||||
|
Comment on lines
+57
to
+58
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||||||
|
|
||||||||||
| ## Renamed `bin/newrelic` command to `bin/newrelic_rpm` [renamed_cli_command] | ||||||||||
|
|
||||||||||
| 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. | ||||||||||
|
Contributor
There was a problem hiding this comment. Maybe a small example here could be calling the Something like a: # before
bin/newrelic install
# after
bin/newrelic_rpm install |
||||||||||
|
|
||||||||||
| ## Removed support for recording deployments via the agent [removed_record_deployments] | ||||||||||
|
|
||||||||||
| 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](https://docs.newrelic.com/docs/change-tracking/change-tracking-introduction/) for a list of available options. | ||||||||||
|
|
||||||||||
| ## Removed the NewRelic::Agent::SqlSampler#notice_sql method [sql_sampler_removal] | ||||||||||
|
|
||||||||||
| The `NewRelic::Agent::SqlSampler#notice_sql` method has been removed. To track SQL queries, you should use the `NewRelic::Agent::Datastores.notice` method instead. | ||||||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
After this, what do you think about a before/after code snippet for calling the methods? |
||||||||||
|
|
||||||||||
| ## Removed unused arguments from various `NewRelic::Agent::Datastores` APIs [unused_arguments_removal] | ||||||||||
|
|
||||||||||
| The following APIs from the `NewRelic::Agent::Datastores` class have had method arguments removed: | ||||||||||
|
|
||||||||||
| * `NewRelic::Agent::Datastores.notice_sql`, previously had three positional arguments, `query`, `scoped_metric` and `elapsed`. Now, it only has `query`. | ||||||||||
| * `NewRelic::Agent::Datastores.notice_statement`, previously had two positional arguments `query` and `elapsed`. Now it only has `query`. | ||||||||||
| * `NewRelic::Agent::Datastores.wrap` requires a proc. Previously the proc received three arguments: the result of the yield, the most specific scoped metric name, and the elapsed time of the call. Now, it only receives one: the result of the yield. | ||||||||||
|
|
||||||||||
| The values of the removed arguments are derived from the current segment at the time of the call. | ||||||||||
|
Comment on lines
+72
to
+80
Contributor
There was a problem hiding this comment. Maybe we combine this section and the one above into one Sql statements/datastore step? I'd like to see before and after examples for each of these method changes as well. |
||||||||||
|
|
||||||||||
| ## Improved configuration validation and coercion [improved_config_validation] | ||||||||||
|
|
||||||||||
| The internals used to coerce and validate the values provided for agent configuration are now more performant and more accurate. | ||||||||||
|
|
||||||||||
| * Warning messages will now be logged to the newrelic_agent.log file when nil is provided as a config value for a setting that does not support it. | ||||||||||
| * Integer values are permitted for Float configuration types. | ||||||||||
| * Float values are permitted for Integer configuration types. | ||||||||||
| * Fatal interruptions are prevented when a default value can be found to replace an invalid input value. | ||||||||||
|
Comment on lines
+86
to
+89
Contributor
There was a problem hiding this comment. Can we think of anything people need to do with this to migrate? If not, maybe we should leave it out. One idea would be to suggest people changing the |
||||||||||
|
|
||||||||||
| ## Removed the experimental feature Configurable Security Policies (CSP) [#csp_removal] | ||||||||||
|
|
||||||||||
| The experimental feature, Configurable Security Policies (CSP), is no longer supported and has been removed. | ||||||||||
|
Contributor
There was a problem hiding this comment. What do you think about recommending High Security Mode as a replacement? |
||||||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We might want to structure this overview in the same order as the list at the bottom of the confluence doc (internal) about major version releases.