Ruby 10.x Migration Guide

src/content/docs/apm/agents/ruby-agent/getting-started/migration-10x-guide.mdx

@@ -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/).
+
+## 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`
+
+## 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>
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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.