Managing APM Agents

A user with Application Performance Monitoring administrator role can remove APM Agents or update to the latest version of the agent.

Topics:

Upgrading APM Java Agents

This section discusses how you can upgrade APM Java Agents.

Prerequisite:

Stop the server where the APM Java Agent to be upgraded is installed.

To upgrade APM Java Agents:
  1. Download the latest master installer, AgentInstall.zip.
  2. Extract the contents of the ZIP file to a local or shared directory.
  3. Download the agent install software.
    For information on the above steps 1 to 3, see Downloading the Master Installer for APM Java Agent.
  4. Optionally backup the existing APM Java Agent.
  5. Install and provision the APM Java agent for your administration server. Provision the new APM Java Agent to the same destination. Ensure you are logged in as the same user that installed the initial APM Java Agent.
    You will be prompted to Overwrite, or Upgrade existing APM Java Agent.
    1. Overwrite - New APM Java Agent will be installed over the existing one.

    2. Upgrade - The APM Java Agent is upgraded to new version, and all customized properties are retained. Both lib and config directories in apmagent are backed up to lib.backup and config.backup respectively.

Removing APM Java Agents

This section provides information about disabling and removing APM Java Agents.

To disable and remove APM Java Agents from a WebLogic domain, complete the following tasks:
  • Task 1: Disable the APM Java Agent in the WebLogic Server Domain

  • Task 2: Delete the APM Java Agent Software from the WebLogic Server Domain

  • Task 3: Remove APM Java Agent References from Oracle Management Cloud

Task 1: Disable the APM Java Agent in the WebLogic Server Domain

  1. Stop the WebLogic Server:
    % cd $DOMAIN_HOME/bin
    % ./stopWebLogic.sh
  2. Remove the edited version of the startWebLogic.sh script, and replace it with the original script that was backed up before you installed the APM Java Agent:
    % mv startWebLogic.sh.orig startWebLogic.sh
  3. Restart the WebLogic Server:
    % cd $DOMAIN_HOME
    % nohup ./startWebLogic.sh >& startup.log &

    Note:

    Note that in the above script you are using the $DOMAIN_HOME version of startWebLogic.sh, even though you had earlier edited the $DOMAIN_HOME/bin version. Invoking this script from one level higher will in fact invoke the script from a lower level.

Task 2: Delete the APM Java Agent Software from the WebLogic Server Domain

  1. Remove the directory where the APM Java Agent files were extracted:
    % cd $DOMAIN_HOME
    % rm -r apmagent
  2. Remove the directory where you initially extracted the APM Java Agent installation software. For example:
    % cd $DOMAIN_HOME
    % rm -r apm_agent

Task 3: Remove APM Java Agent References from Oracle Management Cloud

  1. On the Oracle Management Cloud Agents page, click APM Agents on the left navigation pane.
  2. On the APM Agents page, select the APM Java Agent that you want to remove. Use the Search feature to search for a specific APM Java Agent.
  3. On the right side of the page, click the Actions menu and select Remove.

Removing APM .Net Agent

This section provides information about disabling and removing APM .Net Agents.

A administrator can remove APM .Net Agents by completing the following tasks:
  • Task 1: Remove APM .Net Agent

  • Task 2: Remove APM .NET Agent References from Oracle Management Cloud

Task 1: Remove APM .Net Agent

  1. You can remove APM .Net Agent in any of the following ways:
    • Navigate to the installation directory and run the following command:

      msiexec /x ApmAgent.msi

      OR

    • Navigate to the Control Panel and remove Oracle APM .NET Agent.

Task 2: Remove APM .NET Agent References from Oracle Management Cloud

  1. On the Oracle Management Cloud Agents page, click APM Agents on the left navigation pane.
  2. On the APM Agents page, select the APM .Net Agent that you want to remove. Use the Search feature to search for a specific APM .Net Agent.
  3. On the right side of the page, click the Actions menu and select Remove.

Upgrading APM Node.js Agents

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

Prerequisites

  • Ensure that the environment variables are set appropriately as listed in Preparing to Deploy APM Node.js Agent.

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

  • Stop the server where the APM Node.js Agent to be upgraded is installed.

  • 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 master installer, AgentInstall.zip.
  2. Extract the contents of the ZIP file to a local or shared directory.
  3. Download the agent install software.
    For information on the above steps 1 to 3, see Downloading the Master Installer for APM Node.js Agent.
  4. Optionally, backup the existing APM Node.js Agent.
  5. Install and provision the APM Node.js agent by running the provisioning script. For instructions on installation, see Installing and Provisioning APM Node.js Agent.
    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 apmagent 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.

Removing APM Node.js Agents

This section provides information about disabling and removing APM Node.jsAgents.

To disable and remove APM Node.js Agents, complete the following tasks:
  • Task 1: Remove the APM Node.js Agent from the application

  • Task 2: Delete APM Node.js files from the Application folder

  • Task 3: Uninstall APM Node.js Agent

Task 1: Remove the APM Node.js Agent from the application

  1. Navigate to the NODE_APP_HOME folder.
  2. Open the .js file that serves as the application’s entry point.
  3. In the .js file, search for the line that starts with require('oracle-apm'); and delete it.
    Code with Node.js Agent enabled:
    require('oracle-apm'); //Newly added require for Oracle APM instrumentation
      
    var express = require('express');
    var app = express();
     
    app.get('/', function (req, res) {
      res.send('Hello World!');
    });
     
    app.listen(3000, function () {
      console.log('Example app listening on port 3000!');
    });
    Code after removing APM Node.js Agent
    var express = require('express');
    var app = express();
     
    app.get('/', function (req, res) {
      res.send('Hello World!');
    });
     
    app.listen(3000, function () {
      console.log('Example app listening on port 3000!');
    });

Task 2: Delete APM Node.js files from the Application folder

  1. Navigate to the NODE_APP_HOME folder.
  2. Remove the directory oracle-apm where APM Node.js agent was installed
    cd $NODE_APP_HOME
    rm -r oracle-apm

Task 3: Uninstall APM Node.js Agent

  1. Set the environment variable PATH to include $Node_Home/bin.
  2. Run the following command to uninstall APM Node.js agent:
    npm uninstall -g oracle-apm