Install the Ruby Library

This topic applies to version 6+ of the Ruby Library. SolarWinds no longer maintains versions prior to version 6. See SolarWinds Observability | Upgrade the Ruby Library to find out how to upgrade.

After you install the library, see Configure the Ruby Library for configuration information.

Before you start

Verify the following to ensure the library can collect and transmit data:

• The platform where your APM library will be installed is supported.

• Your application components are supported by the library.

• Your firewall configuration permits TCP/HTTPS/TLS outbound connections to otel.collector.xx-yy.cloud.solarwinds.com (or apm.collector.xx-yy.cloud.solarwinds.com when using legacy mode) port 443, where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs. See Firewall or access control requirements.

  If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Do not run other APM libraries alongside the SolarWinds Observability Ruby Library. Remove other APM libraries and agents from your Ruby application before using the SolarWinds Observability Ruby Library. See Remove other APM libraries.

Dependencies

Version 7.0.0 and later

The solarwinds_apm gem is pure-Ruby beginning with version 7.0.0 and thus can be installed on most systems.

Version 6.1.2 and earlier

The solarwinds_apm gem includes a c-extension that is available for Linux x86_64 systems and needs to compile on installation. The following must be on your system to install the gem:

• Ruby header files
• The gnu compiler
• The make commandline command

On Debian/Ubuntu:

sudo apt install ruby-dev g++ make

On RHEL/CentOS/Amazon Linux:

sudo yum install ruby-devel gcc-c++ make

On Alpine:

sudo apk add ruby-dev g++ make

Install

The solarwinds_apm gem is available on RubyGems. To install it, do one of the following:

• Run gem install solarwinds_apm

• If the application manages gems using Bundler, add the following lines to the end of your Gemfile and run bundle install:

  # application dependencies, eg
  # gem "rails", "~> 7.0.5", ">= 7.0.5.1"
  
  # end of Gemfile
  gem 'solarwinds_apm' 

Ideally all application gems are required by Bundler.require, which guarantees loading in the order they appear in the Gemfile. If Bundler.require does not require all application gems, call require 'solarwinds_apm' after all gems that need instrumentation are loaded.

The only required configuration is the service key, which can be set in the SW_APM_SERVICE_KEY environment variable or in the configuration file as :service_key. See Configuration for the complete reference.

Uninstall the library

Remove gem solarwinds_apm from the Gemfile (or gemspec file), and remove any require 'solarwinds_apm' from the code. The next time the application is started after these items are removed, the application won't be instrumented.

To remove the gem from your system entirely, after you removed the gem and require statements from your Gemfile and code, do one of the following:

• For gems managed through Bundler, run bundle clean
• For all other gems, run gem uninstall solarwinds_apm

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.