11 Install and Configure APM Ruby Agent

Topics:

• Requirements and Installation Instructions

• Verify the APM Ruby Agent Installation

Requirements and Installation Instructions

Prerequisites

• Supported versions of the application server:

  • Ruby 2.X and Rails 3.2

  • Ruby 2.X and Rails 4.2

  • Ruby 2.X and Rails 5.X

• If the application server you are running doesn't support TLS 1.2 security protocol, refer to My Oracle Support Doc ID 2703411.1 before proceeding with the APM agent installation.

• Other considerations:

  • The machine hosting the application server should be able to establish an HTTPS connection either directly or indirectly (using a proxy server or an Oracle Management Cloud gateway) to Oracle Management Cloud. For more information about Oracle Management Cloud gateway, see Install a Gateway.

  • The HTTPS connection must use TLS 1.2 security protocol.

  • The install user of APM Ruby Agent should be the same as the application server user.

  • The application server should have read and write permissions to the APM Ruby Agent log and config directories.

Deploy the Gateway (Optional)

A gateway is not a mandatory component while deploying Oracle Application Performance Monitoring. Use the gateway in the following scenarios:

• If you have an application server that does not support Transport Layer Security (TLS) protocol 1.2.

• If you have older versions of .NET IIS servers and Java Application Servers with JDK less than 1.7 (for example, Oracle WebLogic 10.3.6)

For instructions on how to deploy the gateway, see Installing a Gateway in Installing and Managing Oracle Management Cloud Agents.

Set the Gateway Variables (Optional)

Set the values for Gateway host and port.

• If you're using a Bash shell:

  export GW_HOST=<Gateway Host Name>
  export GW_PORT=<Gateway Port>

• If you're using a C shell:

  setenv GW_HOST "<Gateway Host Name>"
  setenv GW_PORT "<Gateway Port>"

If you are using more than one gateway, use the --additional-gateways option with the provisioning script.

Download the APM Ruby Agent Software

1. On the Oracle Management Cloud home page, click the Oracle Management Cloud Navigation icon on the top-left corner to view the Management Cloud navigation pane.
2. Select Administration and Agents.
3. On the Oracle Management Cloud Agents page, click the Action Menu on the top right corner of the page and select Download Agents. The Agent Software Download page is displayed.
4. From the Agent Type dropdown list, select APM Agent.
5. Click APM Ruby Agent to start downloading the installer to a local or shared directory in your data center.
6. Create a registration key that will be used during the time of installing a new agent. Oracle Application Performance Monitoring Cloud Service verifies this key before accepting any data sent by APM Ruby Agent deployed on your on-premises hosts. For more information about creating a registration key, see Manage Registration Keys in Installing and Managing Oracle Management Cloud Agents.
7. Click Done after the download is complete.
8. Extract the contents of the installer ZIP file.

Install and Provision APM Ruby Agent

After you have downloaded and extracted the installer, install and provision the APM Ruby Agent on your Rails application server.

To install the APM Ruby Agent:

1. Navigate to the directory where you downloaded and extracted the APM Ruby Agent software. This directory contains a ruby gem called oracle_apm-<version>.gem
2. Install APM Ruby Agent Gem
   Install the gem to the Ruby installation your application will use:

   gem install oracle_apm-<version>.gem

   Example:

   gem install oracle_apm-1.36.0.gem

3. Provision Ruby Agent

   1. The same download directory contains the file provision_ruby_agent.rb. Run the following command, using the Ruby installation that your application will use:

      ruby provision_ruby_agent.rb --help

      This should print out the script's help message, which lists all the parameters the script uses.

   2. Run the provisioning script as per your installation preference:

      Installation Preference	Provisioning Script
      Basic Installation	ruby provision_ruby_agent.rb -d {rails_app_directory}
      With Gateway. If you are using more than one gateway, use the --additional-gateways option	ruby provision_ruby_agent.rb -d {rails_app_directory} --gateway-host ${GW_HOST} --gateway-port ${GW_PORT} ruby provision_ruby_agent.rb -d {rails_app_directory} --gateway-host ${GW_HOST} --gateway-port ${GW_PORT} --additional-gateways https://{gw_host_2}:{gw_port_2},https://{gw_host_3}:{gw_port_3}
      Silent installation	ruby provision_ruby_agent.rb -d {rails_app_directory} --no-prompt --regkey-file {registration_key_file_path}
      With Proxy	ruby provision_ruby_agent.rb -d {rails_app_directory} --ph {http_proxy_host} --pp {http_proxy_port}

      • -d is the absolute path of the Ruby on Rails application directory. This is the directory that contains directories such as config and log for the application.
      • --ph {http_proxy_host} (Optional) - the proxy server's host name
      • --pp {http_proxy_port} (Optional) - the proxy server's port
      • --pu {http_proxy_user} (Optional) - Authentication user for the http proxy if needed (if needed)
      • --ppw {http_proxy_password} (Optional) - Authentication password for the http proxy (if needed)
   3. When prompted, provide the value of the registration key that you've created or downloaded earlier. If you are running the provisioning script with the --no-prompt option, create a text file containing the value of the registration key, and provide the path to the file.
      Example:

      ruby provision_ruby_agent.rb -d sample_rails_app --no-prompt --regkey-file regkey.txt 

      (where regkey.txt contains a single line with the registration key.)
4. Enable the APM Ruby Agent for your application: To have the APM Ruby Agent monitor your Ruby on Rails application, add the APM Ruby Agent gem to the application Gemfile.
   1. Update the Gemfile of the application by adding gem 'oracle_apm'. Here is an example:

      source 'https://rubygems.org'
      gem 'oracle_apm'
      # Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
      gem 'rails', '4.2.6'
      # Use sqlite3 as the database for Active Record
      gem 'sqlite3'
      ...

5. Restart the Ruby on Rails Application. The next time your application is started, the APM Ruby Agent will start monitoring your application.

Provision APM Ruby Agent with a standalone installer

A standalone APM Agent installer is obtained when the Agent zip file is received via email, FTP or similar means (that is, when the agent zip file was not downloaded from an OMC server). To install using the standalone agent installer specify these additional parameters when running the provisioning script:

Oprion	Description
--tenant-id	The Oracle Management Cloud tenant name. You can get this value from the Agent Download page. Script for v1 tenant: ruby provision_ruby_agent.rb -d {rails_app_directory} --tenant-id {tenant} --omc-server-url {omc_server_url} Script for v4 tenant: ruby provision_ruby_agent.rb -d {rails_app_directory} --tenant-id {service-tenant} --omc-server-url {omc_server_url}
--omc-server-url	The URL of the Oracle Management Cloud server. If you are using gateways and have specificed --gateway-host and --gateway-port, you do not need --omc-server-url.

Verify the APM Ruby Agent Installation

You can verify if the deployment of the APM Ruby Agent is successful by examining the logs and verifying that the user interface displays the application.

APM Ruby agent logs are located in the Rails application log directory, within the apm_agent directory: <rails_app>/log/apm_agent.

As the Rails application starts up, the agent creates three log files:

• agent.log

• agent_startup.log

• agent_status.log

The agent_startup.log contains startup logs and will eventually log the following “Agent startup successfully completed”.

The agent_status.log file contains a summary of internal agent metrics showing the amount of traffic monitored, number of observations sent, and number of warnings or errors encountered among other data.

Verify Installation for multiple APM Ruby Agents:

If multiple servers are started for this Rails application, you can see a set of logs for each APM Ruby Agent. The first agent will look like the example above, and additional agents will have a number appended to the file name. For example:

• agent_2.log

• agent_startup_2.log

• agent_status_2.log