Ruby agent 6.x to 7.x migration guide

Summary

This guide covers the major changes between the 6.x and 7.x series of the Ruby agent, issues that may be encountered while upgrading, and how to migrate successfully to version 7.x.

Main changes include:

Support for Ruby 2.0 and 2.1 is dropped
SSL Certificate Bundle is removed
Several APIs that were deprecated in various 6.x releases are now removed
Auto-instrumentation defaults to prepend over method chaining
Auto-instrumentation gets consistent configuration attributes

See the milestone for 7.0 target release for more information.

Support for Ruby 2.0 and 2.1 is dropped

Ruby 2.0 and 2.1 reached EOL in February 2016, and New Relic is following suit with dropping support for these versions in the 7.0 release. There are no known changes that would inherently prevent these versions from continuing to work, but we are no longer guaranteeing the Ruby agent continues to function without issues going forward. If you need Ruby 2.0 or 2.1, then continue to use 6.15.0, which is the last release published to support these Ruby versions.

Prepend instrumentation configuration

Relevant pull request: Prepend instrumentation #565.

Potential issue: The agent fails to initialize and start reporting data. A stack level too deep error message is reported in the logs.

Solution: Our configuration and dependency detection mechanism can now be controlled through configuration. By default all auto-instrumented gems/libraries are activated with the prepend strategy. The default configuration setting for these libraries in the absence of any settings appearing in the configuration file is auto, which will pick the best strategy. In the case of a known conflict with prepend strategies, auto instructs the agent to fall back to method-chaining when such conflicts are detected. Below is a complete explanation of our changes to the configuration section for auto-instrumentation using sidekiq as an example.

instrumentation:
  sidekiq: chain

Tip

The use case for this is when an unknown gem is found to be conflicting. The user is able to revert to method-chaining to deal with the conflict until the agent can be updated to auto-detect and handle the conflict.

To disable instrumentation altogether:

instrumentation:
  sidekiq: disable

In some cases, we may know specific gems conflict with prepend. To facilitate, we offer by default an auto config option, which automatically degrades to chain in such cases.

The default setting in most cases is thus:

instrumentation:
  sidekiq: auto

It's possible to force using prepend strategy by specifying it in the config file:

instrumentation:
  sidekiq: prepend

Tip

The use case for this is when a newer version of the conflicting gem is released and it's known to no longer conflict with prepend strategy.

If you encounter stack level too deep errors, see our troubleshooting guide on how to resolve these issues. After working through this troubleshooting guide, you can let us know about the prepend conflict you find by commenting on this GitHub issue. We appreciate your feedback so we may detect and automatically fall back to method-chaining in such scenarios.

Modernized auto-instrumentation strategy

Ruby introduced prepend as a way to insert method definitions earlier into the method resolution stack in Ruby 2.0 (released in 2013) with the intent that prepend eliminates the need to do method-chaining as a means of patching original gem libraries' implementations with trace/observability logic.

Mixing prepend with method-chaining (a.k.a. method_alias monkey patching) can lead to a known stack level too deep scenario as described in our blog post on the topic.

New Relic has previously updated many auto-instrumented libraries over the years to use prepend strategy. The 7.0 release makes prepend the default strategy of choice to auto-instrument over method-chaining, except when known scenarios exist that would lead to triggering stack level too deep errors. A best effort to identify conflicting external gems that would lead to this scenario was made, but there are bound to be others out in the wild that we have not identified.

In the past, we had only one way to auto-instrument for most gems and that was method-chaining. With 7.0 release, we can instrument most gems using either method-chaining or prepend and our configuration of all auto-instrumented gems has been updated to reflect this.

With the modernization of our auto-instrumentation, we have also introduced new functionality in our dependency detection mechanism to identify conflicting external gems and automatically switch from prepend strategy to method-chaining. This means you no longer have to depend on the maintainers of other gems to make changes to their gem libraries in order to facilitate using the Ruby agent in conjunction with those gems. However, we are not aware of such conflicts until our users report them to us, so only a few of our auto-instrumented libraries can auto-detect these conflicts and auto-switch to method-chaining strategies. We need your help to hear about these scenarios and to add auto-detection to future Ruby agent releases.

The SSL Certificate bundle is removed

In the early days of Ruby (1.8, 1.9, etc.), integration with OpenSSL and making HTTPS connections was not well-handled. To ensure customers would be able to consistently make HTTPS connections to New Relic's Collector servers, a selection of SSL CA Certificates were bundled and distributed with the Ruby agent. Over time, the Ruby ecosystem has stabilized and now supports system installed CA Certificates in a standard manner that largely obsoletes the need to bundle and distribute the certificate bundle. The vast majority of certificates bundled have expired or are nearing expiration, so we have decided to remove this dependency from the agent. If you're deploying a Ruby application and agent to a container or server that does not have CA certificates installed, you will need to ensure they're now installed for 7.0+ releases of the agent to make successful HTTPS connections to New Relic servers.

For more information, see Remove cert bundle #478.

Potential issue: If you're deploying to a host that does not have OpenSSL and system CA certificates installed, you may experience issues connecting to New Relic servers and experience loss of APM data.

Solution: New Relic servers require HTTPS, which uses CA certificates to initiate successful connections. These may be installed, and depending on your host, in various ways. The following are helpful links for testing the readiness of your host and installing CA certificates:

If needed, the agent can be configured to use any CA bundle by giving the path to the CA bundle file via configuration: :ca_bundle_path. Please see Custom SSL certificate for Ruby for more info.

Deprecated APIs and configuration attributes

All deprecated APIs have replacement APIs that either expand scope and/or improve robustness of the deprecated API.

Relevant pull requests are:

Denied and allowed lists enabled

Potential issue: Black/White listed attributes no longer work.

Solution : Change black to denied and white to allowed in your configuration or environment variable settings.

https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#autostart-denylisted_constants

:autostart.blacklisted_constants => :autostart.denylisted_constants
:autostart.blacklisted_executables => :autostart.denylisted_executables
:autostart.blacklisted_rake_tasks => :autostart.denylisted_rake_tasks
:strip_exception_messages.whitelist => :strip_exception_messages.allowed_classes

Active Record

Potential issue: Disabling older Active Record versions no longer works.

Solution: Change the following configuration settings:

:disable_active_record_4 => :disable_active_record_notifications
:disable_active_record_5 => :disable_active_record_notifications

httpResponseCode

Potential issue: The attribute httpResponseCode no longer appears in UI in the traces reported.

Solution: httpResponseCode was replaced with http.statusCode.

Notice Error (trace_only)

Potential issue: Passing the :trace_only option to NewRelic::Agent.notice_error no longer works.

Solution: Replace :trace_only with the :expected attribute.

Distributed Tracing APIs

Potential issue: Errors are raised in application code while calling the api methods create_distributed_trace_payload and accept_distributed_trace_payload.

Solution: Instead, please see insert_distributed_trace_headers and accept_distributed_trace_headers, respectively.

Summary .css-21sua1{background:none;border:none;width:0;padding:0;}