1. Installing and Configuring Oracle Application Performance Monitoring
  2. Upgrade APM Agents

16 Upgrade APM Agents

A user with Application Performance Monitoring administrator role can update to the latest version of the Agent.

Topics:

Upgrade APM Java Agent

This section discusses how you can upgrade the APM Java Agent.

Upgrade APM Java Agent

  1. Stop the server where the APM Java Agent to be upgraded is installed. Ensure you are logged in as the same user that installed the initial APM Java Agent.

  2. Download the agent install software. See the install instructions for the relevant APM Java Agent.

  3. Optionally backup the existing APM Java Agent. Note that the apmagent/config and apmagent/lib folders will be backed up automatically during the upgrade.

  4. Install and provision the APM Java Agent for your administration server. Provision the new APM Java Agent to the same destination.

    The provisioning script will search for domain home/apmagent (where domain home is the directory the user specified in the –d parameter.) You will be prompted to Overwrite, or Upgrade existing APM Java Agent.

    1. o — Overwrite - New APM Java Agent will be installed over the existing one.

    2. u — Upgrade - The APM Java Agent is upgraded to new version, and all customized properties are retained. Upgrade does the following:

      • Old agent libs will be backed up: apmagent/lib into apmagent/lib.backup

      • Old agent libs will be backed up: apmagent/config into apmagent/config.backup

      • New agent files will be extracted into apmagent, but apmagent/config files will not be replaced.

      • Certain parameters in the apmagent/config files will still be updated according to the new installation settings (like server URL, etc.)

    3. q— Quit - The script exits without modifying the installed APM Java Agent.

  5. Start the application server.

Upgrade APM .Net Agent

This section discusses how you can upgrade APM .Net Agents.

Upgrade APM .Net Agent

Before upgrading the APM .Net Agent, make sure you take a backup of the following system configuration files:

  • C:\Windows\System32\inetsrv\config\applicationHost.config

  • C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config\web.config

  • C:\Windows\Microsoft.NET\Framework\v2.0.50727\CONFIG\web.config

  • C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Config\web.config

  • C:\Windows\Microsoft.NET\Framework64\v2.0.50727\CONFIG\web.config

To upgrade the APM .Net Agent:

  1. Stop the IIS server.

    iisreset /stop

  2. Execute the APM .Net Agent installer.

    1. Ensure that the OMC.ini file is in the same directory as the ApmAgent.msi file.

    2. Run the ApmAgent.msi executable. The APM .Net Agent installation wizard guides you through the installation process.

    3. Specify the installation directory. You can use the same directory used for the previous installation, or specify a new one.

    4. Specify the host name.

    5. Click Install.

  3. Start your IIS server.

    iisreset /start

Upgrade APM Node.js Agent

This section discusses how you can upgrade APM Node.js Agent.

Upgrade APM Node.js Agent

Prerequisites:

  • Ensure that the environment variables are set appropriately.

  • Ensure that none of the files in the node_modules/oracle-apm folder are open.

  • Stop all the APM Node.js Applications.

  • Ensure you are logged in as the same user that installed the initial APM Node.js Agent.

To upgrade APM Node.js Agents:

  1. Download the latest APM Node.js Agent software and extract the contents of the ZIP file to a local or shared directory.

  2. Install the APM agent install software.

    For information on the above steps 1 and 2, see Install and Configure APM Node.js Agents.

  3. Optionally, backup the existing APM Node.js Agent from $NODE_PATH.

  4. Install and provision the APM Node.js Agent by running the provisioning script.

    APM Node.js Agent displays the list of changes made by the upgrade process, and prompts for confirmation. On confirmation, the APM Node.js Agent is upgraded to the new version, and all customized properties are retained. The oracle-apm directory and the oracle-apm-config.json file in $NODE_PATH are backed up to ${STAGE_DIR}/temp.

    Note:

    Review the hostName property, since this value will overwrite the hostName which was used by the agent prior to upgrade.

    The upgrade computes a default hostname and uses the same. To override this default, rerun the provisioning script with ORACLE_HOSTNAME argument.

The following changes occur when you choose to upgrade APM Node.js Agent:

  1. A new version of APM Node.js Agent software will be installed in the node-modules folder.

  2. Updated oracle-apm-config.json will be copied over from STAGE_DIR to node-modules/oracle-apm/data folder. Existing file will be backed up with a .backup extension. Custom properties edited previously like proxy params etc will be copied over to the new file.

  3. All .cer certificate files will be converted into the correct format and copied over to node-modules/oracle-apm/data folder.

  4. Start the Node.js applications. The required config files will be copied to the respective NODE_APP_HOME/oracle-apm/data folder.

Troubleshooting Upgrade Issues

The upgrade overwrites oracle-apm agent files in the %NODE_PATH% folder. If any file from this folder (for example, oracle-apm-config.json file) is open during the upgrade, the following npm error occurs, and the upgrade process stops. 

npm ERR! code EPERM
npm ERR! errno -4048
npm ERR! syscall rename

npm ERR! Error: EPERM: operation not permitted, rename '%NODE_PATH%\oracle-apm' -> '%NODE_PATH%\.oracle-apm.DELETE'

With the above error, the oracle-apm folder is deleted and hence, a rerun of the script is treated as a new install. Any locally modified properties are lost due to the rerun.

Workaround

Follow this workaround before attempting a rerun of the provisioning script:

  1. The backup copy of the old oracle-apm folder is available in the backup folder - ${STAGE_DIR}/temp (on Linux) and %TEMP% folder (on Windows). Copy this folder into node_modules.

  2. Ensure that none of the files from the node_modules/oracle-apm folder are open, and rerun the provisioning script.

Upgrade APM Ruby Agent

Follow these steps to upgrade the APM Ruby Agent.

Upgrade APM Ruby Agent

  1. Download the latest APM Ruby Agent from the Oracle Management Cloud UI.

  2. Install the new agent gem.

    gem install oracle_apm-1.xx.x.gem

  3. Verify that it has been added to the gem library:

    gem list oracle_apm
	oracle_apm (1.yy.y) # other old version(s)
	oracle_apm (1.xx.x) # new version

  4. Edit the application’s Gemfile and update the agent gem version specifier

    gem 'oracle_apm', '~> 1.xx.x’

  5. Restart your application server.