APM V8: Upgrade Agents to latest V8.1.4 level

Body

Objective

Upgrade of APM agents to the latest APM V8.1.4 fix pack.

APM 8.1.4 agent fix packs are periodically published. The Part numbers page is updated with the latest agent Fix Pack passport advantage part numbers.

In this blog post we will review steps to download the latest Fix Pack package, generate pre-configured agent package and then install or upgrade the agents. 

See References section at the end of this post for links to related topics.

Steps to upgrade agent

Below are the steps to upgrade APM agent to latest 8.1.4 agent Fix Pack:

1) Check customizations:

Before upgrading the agents, make sure that the customizations are made to the files that do not get overwritten by upgrade.

Refer to following KnowledgeCenter topic:

Preserving agent configuration changes

As an example, consider WebSphere MQ agent. Check the config directory (default path is /opt/ibm/apm/agent/config) files below:

Are all customizations for the agent configuration made in the mq.environment and not in the hidden .mq.environment file (note the dot at the beginning of filename).

If you have made any changes in the hidden file, move those changes to the mq.environment file. The hidden file ( .mq.environment) will be overwritten during upgrade.

2) Download the latest APM Agents 8.1.4 Passport Advantage Part:

Latest available APM agents part numbers are listed on the following knowledgecenter page:

Part numbers

For example, for MQ agent on Linux, you will download part number for advanced_agents_xlinux_8.1.4.0.n.tar, where n is the latest fix number.

3) Configure the downloaded agent package:

NOTE: Following steps use default installation path for APM server and APM agent. Modify the commands to use the install path in your environment.

3.1 Copy the downloaded agent packages to APM Server host in a temporary directory.

3.2 On APM Server host, create configuration packages:

 If you have not already generated configuration package for APM Server (onprem_config.zip, onprem_config.tar), make configuration package by running following command .

 /opt/ibm/ccm]# ./make_configuration_packages.sh

At following prompt you can save the package in the directory of your choice, e.g. /opt/ibm/ccm/depot

Enter the path to the directory where you want to store the configuration packages or accept the default value [/opt/ibm/ccm/mkcustpkg_workdir.15049]:/opt/ibm/ccm/depot

3.3 Configure the 8.1.4 agents package copied over in step 3.1:

Assuming that the agent package is copied to the /media/apm/agents path, then following command will generate the configured agent package.

/opt/ibm/ccm]# ./configure_agent_images.sh -p /opt/ibm/ccm/depot -s /media/apm/agents/

The pre-configured agent images will be saved in default directory /opt/ibm/ccm/depot. If you want to change this location, use -d option.

Use following option to print command usage details:

./configure_agent_images.sh -h

4) Install the agent from configured agent package:

4.1 Copy the pre-configured 8.1.4 agents package (step 3.3) from APM Server /opt/ibm/ccm/depot to the agent host directory.

4.2 On agent host, extract the pre-configured agent package to a directory.

Run installAPMAgents.sh command from the extracted package to install the agents. If agent is already installed, it will be upgraded.

- For example, if you install MQ agent from the package to a directory where previous version of MQ agent is already installed, you will get message such as:

Monitoring Agent for WebSphere MQ will be upgraded from version 07300400 to 07301200.

- If installed agent is already at the level of (or at a higher level) the agent in the pre-configured agent package, then the upgrade will fail and you will get following message:

 Monitoring Agent for WebSphere MQ will not be upgraded - the same version is installed.

- If you try to run installAPMAgents.sh from 'unconfigured' agent package - that is if you skip step 3) above, then you will get following error:

This installation image is not pre-configured to connect to your instance of the Monitoring Infrastructure Node. Use the '/opt/ibm/ccm/make_configuration_packages.sh' script on your IBM Monitoring server to generate a pre-configuration package. Then, extract the package on the current machine and start the extracted 'configure_agent_images.sh' script.

References

Part Numbers

Agent and data collector change history

Configuring the downloaded images

Upgrading your agents

Preserving agent configuration changes