Upgrading the Ruby Agent

AppOptics agents are no longer receiving updates. The new SolarWinds Observability libraries are regularly updated with new features and improvements. If you are still relying on the AppOptics agents and your components are supported by the new libraries, consider migrating to SolarWinds Observability.

Upgrading to the SolarWinds Observability Ruby Library

The Ruby Instrumentation Library for SolarWinds Observability is compatible with the AppOptics collector. SolarWinds Observability libraries are not compatible with AppOptics agents. Do not use a mix of SolarWinds Observability libraries and AppOptics agents to instrument applications that are part of a distributed trace.

Complete migration

SolarWinds recommends that you migrate completely from AppOptics to SolarWinds Observability. For more information about a complete migrations, see Migrate from AppOptics to SolarWinds Observability SaaS. To upgrade to the SolarWinds Observability Ruby Library as part of a complete migration, see Migrate the Ruby Library from AppOptics to SolarWinds Observability.

Partial migration

Alternatively, you can upgrade to the SolarWinds Observability Ruby Library but send data to AppOptics.

1. Remove any references to the AppOptics custom instrumentation API in your application code.

   Save a list detailing your application's usage so it can be updated for the SolarWinds Observability Ruby Library's instrumentation API.

2. Uninstall the AppOptics agent from your application by following the instructions in Uninstalling the Agent.

3. Install the SolarWinds Observability Ruby Library.

   • Code Profiling is currently not supported.

   • The AppOptics configuration file should not be reused. Instead, generate a new SolarWinds Observability Ruby Library configuration file. See Configure the Ruby Library.

4. Set a valid AppOptics service key. See the SolarWinds Observability configuration options for the new configuration file and environment variable names.

5. Set the collector configuration option to the AppOptics endpoint collector.appoptics.com:443. Use an environment variable to override the default APM collector endpoint.

6. Update to use the new instrumentation API if needed.

   The SolarWinds Observability Ruby Library has been updated to use the W3C Trace Context Headers for distributed trace propagation. This update has required a few changes to the Ruby Library SDK and affects how to receive and how to propagate trace context to external spans. The following changes are of particular note:

   • Tracing.start_trace() parameter names have been refactored. If an upstream W3C Trace Context should be continued, it should be passed in the headers parameter and consist of two identifiers, where one is the traceparent and the other is the tracestate.

     The new TraceContextHeaders module can also be used to manually inject the W3C Trace Context into outbound HTTP headers.

   • CurrentTrace module has been renamed to CurrentTraceInfo and now provides a W3C Trace Context for injection into logs as the three attributes trace_id, span_id and trace_flags.

   See Ruby Library instrumentation SDK.

Upgrade to a newer version of the legacy AppOptics Agent

To check if there are updates for the appoptics_apm gem:

1. Display installed version: gem list appoptics_apm.
2. Check for the latest version: gem search appoptics_apm --remote.
3. Upgrade: bundle update appoptics_apm or gem update appoptics_apm.

Check appoptics_apm on RubyGems for the newest version.

See Release Notes for changes.

Upgrading from TraceView

There are three major changes:

1. The gem is now called appoptics_apm, please make changes accordingly.
2. The Service Key (API Token) is now configured as an environment variable APPOPTICS_SERVICE_KEY, and not read from a config file anymore.
3. The class name for the API methods has changed from TraceView::API to AppOpticsAPM::SDK. The SDK methods have been reduced to the methods documented here. Use of log_* methods is discouraged because they can lead to broken traces, but they are still available as AppOpticsAPM::API.log_* methods.