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
-
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.
-
Download the agent install software. See the install instructions for the relevant APM Java Agent.
-
Optionally backup the existing APM Java Agent. Note that the
apmagent/config
andapmagent/lib
folders will be backed up automatically during the upgrade. -
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 fordomain home/apmagent
(wheredomain home
is the directory the user specified in the–d
parameter.) You will be prompted to Overwrite, or Upgrade existing APM Java Agent.-
o — Overwrite - New APM Java Agent will be installed over the existing one.
-
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
intoapmagent/lib.backup
-
Old agent
libs
will be backed up:apmagent/config
intoapmagent/config.backup
-
New agent files will be extracted into
apmagent,
butapmagent/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.)
-
-
q— Quit - The script exits without modifying the installed APM Java Agent.
-
-
Start the application server.
Upgrade APM .Net Agent
This section discusses how you can upgrade APM .Net Agents.
Upgrade APM .Net Agent
-
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:
-
Stop the IIS server.
iisreset /stop
-
Execute the APM .Net Agent installer.
-
Ensure that the
OMC.ini
file is in the same directory as theApmAgent.msi
file. -
Run the
ApmAgent.msi
executable. The APM .Net Agent installation wizard guides you through the installation process. -
Specify the installation directory. You can use the same directory used for the previous installation, or specify a new one.
-
Specify the host name.
-
Click Install.
-
-
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
-
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:
-
Download the latest APM Node.js Agent software and extract the contents of the ZIP file to a local or shared directory.
-
Install the APM agent install software.
For information on the above steps 1 and 2, see Install and Configure APM Node.js Agents. -
Optionally, backup the existing APM Node.js Agent from
$NODE_PATH
. -
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 theoracle-apm-config.json
file in$NODE_PATH
are backed up to${STAGE_DIR}/temp
.Note:
Review the
hostName
property, since this value will overwrite thehostName
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 withORACLE_HOSTNAME
argument.
-
A new version of APM Node.js Agent software will be installed in the
node-modules
folder. -
Updated
oracle-apm-config.json
will be copied over fromSTAGE_DIR
tonode-modules/oracle-apm/data
folder. Existing file will be backed up with a.backup
extension. Custom properties edited previously likeproxy params
etc will be copied over to the new file. -
All
.cer
certificate files will be converted into the correct format and copied over tonode-modules/oracle-apm/data
folder. -
Start the Node.js applications. The required
config
files will be copied to the respectiveNODE_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:
-
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 intonode_modules.
-
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
-
Download the latest APM Ruby Agent from the Oracle Management Cloud UI.
-
Install the new agent gem.
gem install oracle_apm-1.xx.x.gem
-
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
-
Edit the application’s Gemfile and update the agent gem version specifier
gem 'oracle_apm', '~> 1.xx.x’
-
Restart your application server.