Ruby agent 7.x to 8.x migration guide

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
• Distributed Tracing is enabled by default
• Cross Application Tracing is deprecated
• Removed deprecated API methods and legacy instrumentation

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

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

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

NoMethodError: super: no superclass method 'instance_method' for <ExampleClass>

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.

distributed_tracing:
  enabled: false

Cross Application Tracing is deprecated

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

cross_application_tracing:
  enabled: true

distributed_tracing:
  enabled: false

Removed deprecated API methods and legacy instrumentation

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