Configuring the Liberty data collector in on-premises environments (Liberty V18.* and older versions)

Edit online

To monitor the Liberty profile on Linux for System x, you can directly deploy a stand-alone data collector to your local Liberty directory without installing WebSphere® Applications agent.

Before you begin

Download the _datacollectors_linux_8.1.4.0.12.tgz data collector package from the 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.
If your firewall rules do not allow transparent outbound HTTPS connections to external hosts, you can configure data collectors to send traffic to a forward proxy. For instructions, see Configuring data collectors to communicate through a forward proxy.
The monitor-1.0 feature is required by the data collector. You can download this feature from the Liberty feature repository with the installUtility command. For instructions, see the section about downloading assets in the WebSphere Application Server Network Deployment Knowledge Center.
For the Memory Analysis dashboard to contain data, you must enable memory allocation collection for the data collector during configuration. This diagnostic feature requires IBM Health Center 3.0.8 or later. If the IBM Health Center version is not eligible, upgrade the JRE that is used by the application server to a version that contains IBM Health Center 3.0.8 or later.
Tip: To check the IBM Health Center version that is included in the JRE used by the application server, change to the bin directory within the JRE home directory and then issue java -Xhealthcenter -version.

About this task

You can choose to manually configure the data collector or to use the provided configuration script to configure the data collector.

Procedure

To manually configure the data collector, get the data collector files from the data collector package and then modify some local files for the Liberty server.
1. 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.
2. Extract files from the liberty_datacollector_8.1.4.0.tgz package to a local directory with the following command. The extracted directory will become the home directory of the data collector.
```
tar -xzf liberty_datacollector_8.1.4.0.tgz
```
  For example, to extract the files to the /opt/ibm/apm/ directory, issue the following commands:
```
cd /opt/ibm/apm
tar -xzf liberty_datacollector_8.1.4.0.tgz
```
  You can find the extracted files in the /opt/ibm/apm/liberty_dc/.gdc/7.3.0.14.08 directory. This directory is referred to as the data collector home directory (dc_home) in the following steps.
3. Navigate to the Liberty server home directory. For example, /opt/ibm/wlp/usr/servers/defaultServer.
4. Edit the jvm.options file by adding the following parameters. If the jvm.options file does not exist, create it with a text editor.
```
-agentlib:am_ibm_16=server_name
-Xbootclasspath/p:dc_home/toolkit/lib/bcm-bootstrap.jar
-Djava.security.policy=dc_home/itcamdc/etc/datacollector.policy
-Dliberty.home=liberty_home
-Xhealthcenter:level=inprocess
-Xgc:allocationSamplingGranularity=10000
-verbosegc
-Xverbosegclog:absolute_path_to_log_file,1,10000
```
  When you add the entries, take note of the following things:
  - Each entry must be on a single line.
  - Replace server_name with the name of the Liberty server.
  - Replace dc_home with the home directory of the data collector. For example, /opt/ibm/apm/liberty_dc/.gdc/7.3.0.14.08.
  - Replace liberty_home with the root of Liberty installation directory. For example, /opt/ibm/wlp.
  - If the Liberty server is working with heavy workload, add the -Xmx parameter to allocate extra 512M heap size for the data collector. For example, -Xmx1024M.
  - The -Xhealthcenter:level=inprocess and -Xgc:allocationSamplingGranularity=10000 lines are optional. Add the two lines only if you want to enable memory allocation collection, which is disabled by default. Enabling memory allocation collection is required for the Memory Analysis dashboard to contain data.
  - The -Xverbosegclog:absolute_path_to_log_file,1,10000 line is optional, which specifies the path to the redirected garbage collection log file. If not specified, logs are written into one file and rotates every 10000 allocation failures. The original stdout or stderr file (console.log) might be very large as the server runs. Add this line if you want to save the garbage collection output log files to another directory and limit the log file number and size. If the specified path is invalid, this line takes no effect and the garbage collection log file remains the stdout or stderr file.
5. Open the server.env file in the same directory and add the following path to the environment entry. If the server.env file does not exist, create it with a text editor.
```
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/lib:dc_home/toolkit/lib/lx8266:dc_home/toolkit/lib/lx8266/ttapi
```
  When you add the entries, take note of the following things:
  - Each entry must be on a single line.
  - Replace dc_home with the home directory of the data collector. For example, /opt/ibm/apm/liberty_dc/.gdc/7.3.0.14.08.
6. Modify the server.xml in the same directory to enable the monitoring feature by adding the following line to the <featureManager> section:
```
<feature>monitor-1.0</feature>
```
7. Restart the Liberty server.
To configure the data collector by responding to prompts, use the configuration script that is provided in the data collector packages.
1. 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.
2. Extract files from the liberty_datacollector_8.1.4.0.tgz package with the following command.
```
tar -xzf liberty_datacollector_8.1.4.0.tgz
```
  For example,
```
cd /opt/ibm
tar -xzf liberty_datacollector_8.1.4.0.tgz
```
  The extracted data collector files are in the liberty_dc directory.
3. Change to the liberty_dc/.gdc/7.3.0.14.08/bin directory and start the configuration script by running the following command:
```
./config_liberty_dc.sh
```
4. When prompted, enter the root of your Liberty installation directory or accept the default. For example, /opt/ibm/wlp.
5. When prompted, enter the home of JVM that is used by the application server or accept the default. For example, /opt/ibm/java.
6. The configuration program can automatically discover and list the application servers that are not configured within the specified directory. Enter the number that corresponds to the Liberty server that you want to configure. To select more than one server, separate the numbers by space or enter * to select all.
7. After the configuration program finishes updating files for all Liberty servers, manually update the JVM heap size to allocate extra 512M heap for the data collector.
8. Restart the servers for configuration to take effect.

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

To view the monitoring data for your Liberty servers, 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 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 Enabling or disabling transaction tracking and diagnostic data collection.
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.