Documentation forSolarWinds Observability

Troubleshooting the Ruby Library

If you are not receiving traces and metrics in the Traces Explorer or Metrics Explorer, these are some options to troubleshoot.

Resolve a 'Tracing disabled' message

The message Missing SolarWindsAPM libraries. Tracing disabled. means that the solarwinds_apm gem could not load the core c-extension that is downloaded and linked during gem install. This c-extension is only available for Linux platforms (see Services supported platforms).

Another cause could be that gem install solarwinds_apm or bundle install was run as root and the application is run by a non-root user.

Despite this message, your application will run normally, but no metrics or traces will be collected. If the application is running on a Linux platform, contact support. See Support for assistance collecting metrics and traces.

Troubleshoot missing metrics and traces

The most likely cause is an unconfigured Service key. Look in your logs to see if there is a message stating SW_APM_SERVICE_KEY not set. Cannot submit data. or stating Server responded: Invalid API key

The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when adding the new service.

It is a required configuration and should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

For details about setting your Service key for your Ruby application, see SW_APM_SERVICE_KEY.

If your Service key is correctly configured, look at the response headers in your app.

If your response headers do not contain an X-Trace header, then the instrumentation is in noop mode. Verify that gem 'solarwinds_apm' is the last entry in your Gemfile. If you are not running a Rails app, solarwinds_apm is required after any gems that need instrumentation.

If there is an X-Trace header, it's value should be similar to 2B9000C789406646F4EFE825D9240D46C46B95C29CBEBD615BA2951E2F01. If this header ends with 1 the request is traced; if it ends with a 0 only metrics are sent. If the header always ends with a 0, then there may be a problem with the sampling rate, either the local one or the one reflected by the collector.

Allow application access through a proxy or firewall

The library currently can't send data using a proxy. If your server is behind a firewall, you may not be able to connect to the SolarWinds APM collector. See Firewall or access control requirements.

Review library logs

For Rails and Padrino, the library uses the respective applications logger, otherwise the solarwinds_apm gem logs to STDERR. This behavior can be changed by assigning the SolarWindsAPM.logger to a different logger (for example: SolarWindsAPM.logger = MyApp.logger) during initialization.

Get more verbose logs

Use export SW_APM_DEBUG_LEVEL=6 to set the logging to maximum verbosity level. The levels are:

6 debug high
5 debug medium
4 debug low
3 info (default)
2 warn
1 error
0 fatal
-1 disabled

Test the setup

If everything seems set up correctly the following sequence can be tried:

bundle exec irb
require 'solarwinds_apm'
target = {}
SolarWindsAPM::SDK.start_trace_with_target(:test, nil, target) {}
target

It should return something like {"X-Trace"=>"2B3669083F409E053615860A12EE0D5BAA4B8F8975D3015AEAD723FC9B01"}. If the string ends with 01, the trace will show up in Traces Explorer. If it ends with 00, nothing was sampled.

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.