• EnglishEspañol日本語한국어Português
  • Log inStart now

Ruby agent 7.x to 8.x migration guide


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:

See the milestone for 8.0 for more information.

Changes to the add_method_tracer API method

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:

# 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:

# 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).

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.

# old
add_method_tracer :foo, 'metric1'
add_method_tracer :foo, 'metric2', push_scope: false
add_method_tracer :foo, 'metric3', push_scope: false
# 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.


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 <ExampleClass>

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

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.

enabled: false

Cross Application Tracing is deprecated

Cross Application Tracing is deprecated in 8.0 and will be removed in a future release.


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.

enabled: true
enabled: false

Removed deprecated API methods and legacy instrumentation

The following methods had been previously deprecated and are now removed.



disable_transaction_tracing API method

disable_all_tracing or ignore_transaction API methods

External.start_segment API method

Tracer#start_external_request_segment API method

Transaction.wrap API method

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

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.