Troubleshoot APM Ruby Agent Deployment
Installation Issues
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.
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.$ gem list oracle_apm
-
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 arequire ‘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 propertyORACLE_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.