Configuring the Liberty data collector in IBM Cloud environment (Liberty V18.* and older versions)

Edit online

To monitor a Liberty profile running in the IBM® Cloud environment, you must download the data collector package from IBM Passport Advantage®, deploy the data collector to your local application files, and then push the updates to IBM Cloud.

Before you begin

It is assumed that the Liberty application is pushed to the IBM Cloud environment by using the Cloud Foundry commands. The manifest.yml file and the Liberty server home directory (which contains the server.xml file) already exist.

If your Liberty application is deployed as a WAR file, you must modify some local files to update your application by pushing a local directory that contains both the WAR file and the data collector files. An example is provided here to explain how to get a local Liberty server home directory if you only have a WAR file.

Issue the following command to run the Liberty application locally:
```
mvn install liberty:run-server
```
In the directory that contains the Liberty WAR file, a sub-directory, /liberty/wlp/usr/servers/defaultServer, is created. This directory can serve as the Liberty server home directory in the following procedure.
From the root directory that contains the Liberty WAR file, copy the entire application_name-SNAPSHOT folder to the /liberty/wlp/usr/servers/defaultServer directory.
In the /liberty/wlp/usr/servers/defaultServer directory, edit the bootstrap.properties file to modify the appLocation path. The appLocation path must be set to the relative path to the application directory in IBM Cloud.
Remove the logs and workarea folders. They do not need to be pushed to IBM Cloud.
Modify the path value in the manifest.yml file to point to the defaultServer directory.
For example, path: target/liberty/wlp/usr/servers/defaultServer.

Procedure

Complete the following steps to configure the Liberty data collector:

Download the data collector package named _datacollectors_linux_8.1.4.0.12.tgz from IBM Passport Advantage website. For detailed instructions, see Download instructions.
Configure the data collector package with the make_configuration_packages.sh and configure_agent_images.sh scripts on the system where the Cloud APM server is installed. For detailed instructions, see Configuring the downloaded images.
Run the following command to extract files from the data collector package.
```
tar -xzf _datacollectors_linux_8.1.4.0.12.tgz
```
The liberty_datacollector_8.1.4.0.tgz package is included in the extracted directory.
Extract files from the liberty_datacollector_8.1.4.0.tgz package to a temporary directory.
```
tar -xzf liberty_datacollector_8.1.4.0.tgz
```
For example,
```
cd /root/tmp
tar -xzf liberty_datacollector_8.1.4.0.tgz
```
You can find the extracted files in the liberty_dc directory within the temporary directory.
Copy the .gdc directory from the liberty_dc directory to the home directory of your Liberty server where the server.xml file is stored. The Liberty server home directory is referred to as liberty_server_home in the following steps.
```
cp -rf temp_dir/liberty_dc/.gdc liberty_server_home
```
For example,
```
cp -rf /root/tmp/liberty_dc/.gdc /opt/liberty855/wlp/usr/servers/defaultServer/
```
Copy or merge the contents of the jvm.options and server.env files from the liberty_dc/etc directory to liberty_server_home directory.
- If the jvm.options and server.env files do not exist in liberty_server_home directory, copy the two files fromtemp_dir/liberty_dc/etc to liberty_server_home.
```
cp temp_dir/liberty_dc/etc/jvm.option liberty_server_home
cp temp_dir/liberty_dc/etc/server.env liberty_server_home
```
- If the jvm.options or server.env file exists in liberty_server_home directory, merge the contents with the ones from temp_dir/liberty_dc/etc directory.

If your IBM Cloud applications cannot directly connect to the Cloud APM server due to the network or firewall settings, configure the data collector to send traffic through a forward proxy. To do it, edit the jvm.options file in one of the following ways:

If authentication is not required, add the following lines to the file:

-Dhttp.proxyHost=http_proxy_host
-Dhttp.proxyPort=http_proxy_port
-Dhttps.proxyHost=http_proxy_host
-Dhttps.proxyPort=http_proxy_port
-Djava.net.useSystemProxies=true

If a user name and password are required to access the forward proxy server, add the following lines to the file:

-Dhttp.proxyHost=http_proxy_host
-Dhttp.proxyPort=http_proxy_port
-Dhttp.proxyUser=http_proxy_user
-Dhttp.proxyPassword=http_proxy_password
-Dhttps.proxyHost=http_proxy_host
-Dhttps.proxyPort=http_proxy_port
-Dhttps.proxyUser=http_proxy_user
-Dhttps.proxyPassword=http_proxy_password
-Djava.net.useSystemProxies=true

Modify the server.xml file within the Liberty server home directory to enable the monitoring feature by adding the following line to the <featureManager> section:
```
<featureManager>
              <feature>monitor-1.0</feature>
</featureManager>
```
Modify the manifest.yml file of your Liberty application to allocate additional 512M memory.
Open a command prompt, change to the local directory that contains the manifest.yml file for the Liberty server. For example, /opt/liberty855/.
Log in to IBM Cloud and update the Liberty profile with the cf push command.

Results

The data collector is configured and is connected to the Cloud APM server. Resource monitoring, transaction tracking, and diagnostic data is enabled. However, heap collection and memory allocation collection are disabled. You can enable them with the data collector properties files if you need the data in the Heap Dump and Memory Analysis dashboards.

What to do next

If you are an IBM Cloud Public user, configure the IBM Cloud Secure Gateway to enable it to connect to the Cloud APM server. For instructions, see Configuring the IBM Cloud Secure Gateway.
To view the monitoring data for your IBM Cloud application, start the Cloud APM console. For instructions, see Starting the Cloud APM console. For information about using the Applications editor, see Managing applications.
Remember: When you want to add the Liberty data collector instance on the Application Dashboard, select Liberty Runtime instead of WebSphere Application Server from the component list.
For the Heap Dump dashboard and/or Memory Analysis dashboard to contain data, you also need to enable the data collector for heap snapshot collector and/or memory allocation collection, which can be done in the data collector .properties files. See Customizing data collector with properties files.
If the key file or the Cloud APM server changes, reconnect the data collector to the Cloud APM server. For instructions, see Reconnecting the data collector to the Cloud APM server.