Troubleshoot APM Ruby Agent Deployment

Check for the Startup files

To check if the APM Ruby Agent is properly installed and started, locate the agent’s log directory and look for the agent_startup.log file. If the agent is installed for a Rack-base application like Rails, the log directory will be located in the directory log/apm_agent under the application root directory. If the agent home directory was specified (ORACLE_APM_RUBY_AGENT_HOME), the log directory will be located within the agent home directory, under logs/<appname>.

If the agent_startup.log file is not present, this means that the agent startup sequence was not triggered or that an early error happened. You might want to check the following:

Check if Gem is installed:

Verify that the oracle_apm gem is present in the gem library.
```
$ gem list oracle_apm
```
should display the agent gem version you expect to run. If it is not present, install it using the gem install command. If more than one version is present, make sure to specify the right version in the Gemfile definition.
Check the Gem definition:

If the gem is present in the gem library, ensure that it is correctly referenced in the application Gemfile. For example: gem 'oracle_apm', '~> 1.27.1'

If there is no Gemfile for the Ruby process to monitor, ensure that the oracle_apm gem gets loaded. For example, adding a require ‘oracle_apm’ statement to the bootstrap sequence of your application.
Agent home

If the log directory or file cannot be found under the Rails log directory, check that the ORACLE_APM_RUBY_AGENT_HOME is defined. This is where the log would be located.
Console log

You can force the agent bootstrap logs to be logged to the console (stdout) by setting the environment property ORACLE_APM_RUBY_AGENT_CONSOLE_LOG to any value (example: true). If you do not see anything logged as you restart your application, this means that the gem was not loaded. Check that the gem is correctly defined in the Gemfile or properly loaded by your application.

Initialization Process

As the agent starts up, it logs in detail, its initialization sequence in the log file named agent_startup.log. Once the agent is initialized and ready to monitor traffic, it logs the following line:

INFO <STARTUP> Agent startup successfully completed - the agent is now operational and monitoring traffic

Configuration

If there is a typo in the YAML agent configuration file, agent startup might fail. Because configuration is processed early on during the agent startup, you might need to use the environment property ORACLE_APM_RUBY_AGENT_CONSOLE_LOG mentioned above, to force initial logging to go to the console. If there is any typo in the configuration file, error parsing the YAML configuration file will indicate which line caused the problem.
SSL

The agent communicates securely to OMC through SSL. If there is any problem establishing a secured connection, reasons will get logged in the startup log file. If you need to add a new certificate as a trusted server certificate, you can add the certificate in the agent configuration directory, in DER or PEM format with the .cer file extension. Upon restart, the agent will use this additional certificate as a trusted certificate.

Unable to get OAuth Token from IDCS Server

If the agent startup log shows that it cannot get the initial OAuth authentication token, preceded by a warning showing a failure to reach the IDCS server, check to ensure that there is no firewall blocking access to the IDCS server. If there is a firewall, you will need to allow access to the IDCS server.