--- title: Ruby agent 7.x to 8.x migration guide source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/getting-started/migration-8x-guide --- ## Summary [#summary] This guide covers the major changes between the 7.x and 8.x series of the Ruby agent, issues that may be encountered while upgrading, and how to successfully migrate to version 8.x. The main changes include: - [Changes to the `add_method_tracer` API method](#add_method_tracer) - [Distributed Tracing is enabled by default](#distributed_tracing) - [Cross Application Tracing is deprecated](#cross_application_tracing) - [Removed deprecated API methods and legacy instrumentation](#removed_deprecated) See the [milestone for 8.0](https://github.com/newrelic/newrelic-ruby-agent/milestone/10?closed=1) for more information. ## Changes to the `add_method_tracer` API method [#add_method_tracer] ### Metric name parameter accepts Procs; strings no longer interpolated The second argument to `add_method_tracer` is the name of the metric used to record calls to the traced method. Previously, this string could include Ruby-style interpolation to allow for the metric name to include variables from the method receiver. For example: ```ruby # old (<= 7.2) add_method_tracer :foo, 'metric_#{args[0]}' ``` As of 8.0, this string will no longer be interpolated. To preserve the behavior described above, pass a Proc instead: ```ruby # new (8.0+) add_method_tracer :foo, -> (*args) { "metric_#{args[0]}" } # note the double-quotes ``` Note that the arity of the Proc passed to `add_method_tracer` should match the arity of the original traced method (or use a compatible splat). ### `:code_header` and `:code_footer` parameters accept only Procs Similar to metric names, the `:code_header` and `:code_footer` options to `add_method_tracer` were previously given as strings that would be interpolated in the context of the method receiver. In Ruby agent 8.0, `:code_header` and `:code_footer` will only be invoked if given as Procs, as in the example above. ### Call `add_method_tracer` once per method Calling `add_method_tracer` multiple times on the same method will overwrite any previously defined method tracers for that method. There should be only one `add_method_tracer` line for each traced method. Previously, the agent allowed adding multiple metrics to the same method by invoking `add_method_tracer` once for each such metric. This can still be done, but the metric names need to be passed as the second argument of `add_method_tracer` as an array of strings or procs. ```ruby # old add_method_tracer :foo, 'metric1' add_method_tracer :foo, 'metric2', push_scope: false add_method_tracer :foo, 'metric3', push_scope: false ``` ```ruby # new add_method_tracer :foo, ['metric1', 'metric2', 'metric3'] ``` Note that the first metric name will be created as a scoped metric unless `push_scope: false` is specified. The following named metrics will be unscoped. Each traced method may only have one scoped metric. > #### 💡 TIP > > Older versions of Mocha can cause issues with the updated `add_method_tracer`. Mocha version 1.2.0 fixes this bug, so if after upgrading agent versions, you run into errors in your test suite such as: > > ``` > NoMethodError: super: no superclass method 'instance_method' for > ``` > > and happen to have Mocha version < `1.2.0` installed, try increasing the Mocha version to `1.2.0` or above. > > We have only seen error this come up in a test environment calling Mocha methods. However, we recommend you verify the functionality of your application when troubleshooting. ## Distributed Tracing is enabled by default [#distributed_tracing] The default configuration option for `distributed_tracing.enabled` is set to true for versions 8.0 or higher. To disable distributed tracing, set this configuration option to false in your `newrelic.yml`. ```yml distributed_tracing: enabled: false ``` ## Cross Application Tracing is deprecated [#cross_application_tracing] [Cross Application Tracing](https://docs.newrelic.com/docs/agents/ruby-agent/features/cross-application-tracing-ruby/) is deprecated in 8.0 and will be removed in a future release. > #### 💡 TIP > > Distributed tracing and cross application tracing cannot be used simultaneously. If both configuration options are enabled, then only distributed tracing is used. > > To continue using cross application tracing, settings for both distributed tracing and cross application tracing need to be updated in your newrelic.yml. > > ```yml > cross_application_tracing: > enabled: true > > distributed_tracing: > enabled: false > ``` ## Removed deprecated API methods and legacy instrumentation [#removed_deprecated] The following methods had been previously deprecated and are now removed. | Removed | Replacement | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `disable_transaction_tracing` API method | [`disable_all_tracing`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent:disable_all_tracing) or [`ignore_transaction`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent:ignore_transaction) API methods | | `External.start_segment` API method | [`Tracer#start_external_request_segment`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent/Tracer.start_external_request_segment) API method | | `Transaction.wrap` API method | [`Tracer#in_transaction`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent/Tracer.in_transaction) API method | | Mongo < 2.1 instrumentation | Upgrade to Mongo 2.1 or higher | | Excon < 0.19.0 instrumentation | Upgrade to Excon 0.19.0 or higher |