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.
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.
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.
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:
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:
It's possible to force using prepend strategy by specifying it in the config file:
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.
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.
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:
- Troubleshooting SSL Certificate Errors
- Automated SSL Check
- Installing CA Certificates
- How to handle Certificates in Docker
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.
All deprecated API's have replacement API's that either expand scope and/or improve robustness of the deprecated API.
Relevant pull requests are:
- Remove references to
blacklistin codebase #479
- Remove deprecated ActiveRecord config options #480
- Remove httpResponseCode attribute #481
- Remove deprecated option from notice_error API #597
- Remove deprecated distributed trace API methods #598
Potential issue: Black/White listed attributes no longer work.
Solution : Change
allowed in your configuration or environment variable settings.
- :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
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
Potential issue: The attribute
httpResponseCode no longer appears in UI in the traces reported.
httpResponseCode was replaced with
Potential issue: Passing the
:trace\_only option to
NewRelic::Agent.notice\_error no longer works.
:trace\_only with the
Potential issue: Errors are raised in application code while calling the api methods
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.