Ruby 10.x Migration Guide

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

@@ -0,0 +1,114 @@
+---
+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 Cross Application Tracing (CAT) and related APIs](#cat_removal)
+* [Renamed ActiveJob metrics and segments](#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 `NewRelic::Agent::SqlSampler#notice_sql` and simplified `NewRelic::Agent::Datastores` APIs](#removed_and_simplified_apis)
+* [Removed support for Puma versions < 3.9.0](#puma_version_removal)
+* [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. 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 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/). 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`. 
+
+```yaml
+distributed_tracing.enabled: true
+```
+
+The 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](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent/DistributedTracing).
+
+## Renamed ActiveJob metrics and segments [#activejob_rename]
+
+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
+"Ruby/ActiveJob/#{QueueName}/#{Method}" # metrics
+"ActiveJob/#{Adapter}/Queue/#{Event}/Named/#{JobQueueName}" # segments
+```
+
+New format
+```ruby
+"Ruby/ActiveJob/#{ClassName}/#{QueueName}/#{Method}" # metrics
+"ActiveJob/#{Adapter}/#{ClassName}/Queue/#{Event}/Named/#{JobQueueName}" # segments
+```
+
+## 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.
+
+Old command
+```bash
+bin/newrelic install
+```
+
+New command
+```bash
+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 NewRelic::Agent::SqlSampler#notice_sql and simplified `NewRelic::Agent::Datastores` APIs [#removed_and_simplified_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 [#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 the experimental feature Configurable Security Policies (CSP) [#csp_removal]
+
+The experimental feature, Configurable Security Policies (CSP), is no longer supported and has been removed. The agent's default security settings [automatically](https://docs.newrelic.com/docs/apm/new-relic-apm/getting-started/apm-agent-data-security/) provide security for your APM data, however, you can further restrict the information that New Relic receives using [high-security mode](https://docs.newrelic.com/docs/apm/agents/manage-apm-agents/configuration/high-security-mode/).