Install the Ruby Library (legacy)
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
apm.collector.xx-yy.cloud.solarwinds.com
(wherexx-yy
is determined by the URL you use to access SolarWinds Observability, described in Data centers and endpoint URIs) using port443
. 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
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
The c-extension is compiled into a binary with system and Ruby version dependencies. Do not copy the library gem from one platform to another; the library must be installed directly on each different platform.
Install
Ruby
The solarwinds_apm gem is hosted on RubyGems. To install, run
gem install solarwinds_apm
or list gem 'solarwinds_apm'
at the end of your Gemfile if the application manages
gems using Bundler.
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.
Rails
Add gem 'solarwinds_apm'
to the end of the Gemfile so Rails will load the solarwinds_apm gem and instrument the application automatically.
To set additional configuration options, run the command bundle exec rails generate solarwinds_apm:install
to create a config file
config/initializers/solarwinds_apm.rb
. This config file contains a documented list of all configurations options, with most options initially commented out. See Configure the Ruby Library.
Sinatra
To instrument your Sinatra application, list gem 'solarwinds_apm'
after sinatra in your
Gemfile and use Bundler.require
during initialization. Alternatively, call require 'solarwinds_apm'
after sinatra is loaded.
The solarwinds_apm gem will automatically detect sinatra on boot and instrument key components.
If desired, replace the SolarWindsAPM.logger
with the logger you are using. For example:
SolarWindsAPM.logger = MySinatra.logger
Padrino
To instrument your Padrino application, list gem 'solarwinds_apm'
after padrino in your
Gemfile and use Bundler.require
during initialization. Alternatively, call require 'solarwinds_apm'
after padrino is loaded.
The solarwinds_apm gem automatically detects padrino on boot and instruments key components.
Fine tuning the SolarWindsAPM configuration is best done in the Padrino.before_load
block in your config/boot.rb
file. For example:
Padrino.before_load do
# The solarwinds_apm Ruby client has the ability to sanitize query literals
# from SQL statements. By default this is enabled. Disable to
# collect and report query literals to SolarWinds Observability.
SolarWindsAPM::Config[:sanitize_sql] = false
end
Grape
To instrument your Grape application, list gem 'solarwinds_apm'
after grape in your
Gemfile and use Bundler.require
during initialization. Alternatively, call require 'solarwinds_apm'
after grape is loaded.
Rails metal controllers
To instrument your Ruby on Rails metal controllers, include the gem (see Rails) and add the
following code to the bottom of your metal controller declaration.
Add a profile_method
line for every method you want to instrument.
class MetalController > ActionController::Metal
def index
self.response_body = 'Hello Metal!'
end
end
opts = {}
opts[:backtrace] = true
SolarWindsAPM::API.profile_method(MetalController, :index, opts)
See more detailed documentation in Ruby Library instrumentation SDK.
Azure App Service
If your Ruby application platform is the Azure App Service on Linux, SolarWinds recommends deploying it as a custom container, since the pre-defined stack has an open issue that prevents the library from loading. See Migrate custom software to Azure App Service using a custom container in the Microsoft Azure documentation.
You may need to configure the container port number, SSH access, and other aspects for it to run under App Service. See Configure a custom container for Azure App Service in the Microsoft Azure documentation.
When building the image for your custom container, follow the instructions on this page to install and enable the Ruby Library for your application. The Service key can be configured in the Azure portal for your App Service using application settings. After the container is deployed in App Service you should see trace data and metrics shortly.
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.