Installation (legacy agent)

The following content pertains to installation for the legacy AppOptics Ruby Agent.

Overview

There are two parts to enabling instrumentation for a Ruby appplication:

1. Install and require the appoptics_apm gem (see the sections below for details on how to install and enable the agent for a particular framework.)
2. Set the APPOPTICS_SERVICE_KEY system environment variable (see Configuration).

Dependencies

The appoptics_apm gem includes a c-extension that is available for Linux x86_64 systems and needs to compile on install. Therefore you’ll need to have the following on your system in order 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

Ruby

• The appoptics_apm gem is hosted on RubyGems, making installation as simple as gem install appoptics_apm or adding gem 'appoptics_apm' to the end of your Gemfile if the application manages gems via bundler.
• Ideally all application gems are required by Bundler.require, which guarantees loading in the order they appear in the Gemfile. Otherwise make sure to require 'appoptics_apm' only after all gems that need instrumentation are loaded.

Rails

• Rails will load the appoptics_apm gem and do instrumentation automatically if gem 'appoptics_apm' is added at the end of the Gemfile.
• Optionally the command bundle exec rails generate appoptics_apm:install, will create a config file config/initializers/appoptics_apm.rb containing the complete list of configurations options including documentation. Most options are initially commented out. See also configure.

Sinatra

• You can instrument your Sinatra application by listing gem 'appoptics_apm' after sinatra in your Gemfile and use Bundler.require during initialization or calling require 'appoptics_apm' after sinatra is loaded. With this, the appoptics_apm gem automatically detects sinatra on boot and instruments key components.
• You may want to replace the AppOpticsAPM.logger with whichever logger you are using AppOpticsAPM.logger = MySinatra.logger

Padrino

• You can instrument your Padrino application by listing gem 'appoptics_apm' after padrino in your Gemfile and use Bundler.require during initialization or calling require 'appoptics_apm' after padrino is loaded. With this, the appoptics_apm gem automatically detects padrino on boot and instruments key components.

• Fine tuning the AppOpticsAPM configuration is best done in the Padrino.before_load block in your config/boot.rb file. e.g:

  Padrino.before_load do
  
    # The appoptics_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 AppOptics.
    AppOpticsAPM::Config[:sanitize_sql] = false
  end

Grape

• You can instrument your Grape application by listing gem 'appoptics_apm' after grape in your Gemfile and use Bundler.require during initialization or calling require 'appoptics_apm' after grape is loaded.

Rails Metal Controllers

• You can instrument your ruby on rails metal controllers by including the gem as described above and then adding 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
  AppOpticsAPM::API.profile_method(MetalController, :index, opts)

  See more detailed documentation in sdk.

Heroku

Ensure that the AppOptics add-on is attached to your Heroku application, then follow the Ruby agent steps to install and enable the agent.

Azure App Service

If your Ruby application platform is Azure App Service on Linux, we recommend deploying it as a custom container because the pre-defined stack currently has an issue that prevents the agent from loading. Note that you may want to configure the container port number, SSH access and other aspects for it to run under App Service.

When building the image for your custom container, simply follow the instructions on this page to install and enable the Ruby agent 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.

Uninstalling the Agent

• Remove gem appoptics_apm from the Gemfile (or gemspec file) as well as any require 'appoptics_apm' in the code. This has the effect that the code won’t get instrumented the next time the application is started.
• To also remove the gem from your system either run bundle clean for gems managed through bundler or otherwise gem uninstall appoptics_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.