Monitoring on-premises Liberty applications

You can configure the Liberty data collector to monitor the on-premises Liberty applications running on stand-alone Docker containers, VMs or physical nodes and then send monitoring data to the Unified Agent.

Before you begin

• Ensure that you install the Unified Agent plug-ins for LWDC and OpenTracing. For more information, see Installing and configuring Unified Agent plug-ins.
• Check whether you downloaded the Liberty data collector package. For more information, see (Conditional) Downloading the Liberty data collector.

Procedure

• To configure the Liberty data collector for VMs or physical nodes, do the following steps:

  1. Go to the liberty_home/bin directory and run the following command to install the data collector:

     ./installUtility install --acceptLicense path_to_dc_package
     

     where path_to_dc_package is the full path to the .esa file that you downloaded. For example, /opt/javametrics.liberty.icam-1.2.1.esa.

     Note: The installUtility command is not applicable to Open Liberty. If you use Open Liberty, copy the javametrics.liberty.icam-1.2.1.esa file to the /opt directory and run the following commands:

     mkdir -p /opt/ol/wlp/usr/extension/lib/features/
     cd /tmp
     unzip /opt/javametrics.liberty.icam-1.2.1.esa
     mv /tmp/wlp/liberty_dc /opt/ol/wlp/usr/extension/
     mv /tmp/OSGI-INF/SUBSYSTEM.MF /opt/ol/wlp/usr/extension/lib/features/javametrics.liberty.icam-1.2.1.mf
     

  2. Run the following command to apply server configuration to the monitored application:

     ./config_unified_dc.sh [-silent <silent_file>]
     

     Note: If <silent_file> is not provided, the silent_config_liberty_dc.txt file under the same directory of config_unified_dc.sh will be used.

  3. Add the following environment variables:

     UA_LWDC_LISTENER_URL=http://<ip or host>:<port>
     UA_JAEGER_ENDPOINT=http://<ip or host>:<port>/api/traces
     

     Where

     • <ip or host> is the ip or host address of your Go application.
     • <port> is the port that you configure in Installing and configuring Unified Agent plug-ins. By default, it is 8848 for UA_LWDC_LISTENER_URL and 14268 for UA_JAEGER_ENDPOINT.

  4. Restart your Liberty application.

• To configure the Liberty data collector for standalone Docker environment, do the following steps:

  1. Create a silent_config_liberty_dc.txt silent configuration file in the same directory as your Dockerfile and add the following lines:

     JAVA_HOME=/opt/ibm/java/jre
     LIBERTY_HOME=/opt/ibm/wlp
     SERVER_NAME=*
     ADD_XMX_SIZE=True
     SERVER_TYPE=ICAM
     

     Where:

     • JAVA_HOME is the Java home that is used by liberty applications. The default value is /opt/ibm/java/jre.
     • LIBERTY_HOME is the directory where the liberty application is installed. The default value is /opt/ibm/wlp.
     • SERVER_NAME is the name of the liberty servers that are monitored by the data collector. You can separate the server names with a space character. The * character shows all the servers installed are monitored. The default value is *.
     • ADD_XMX_SIZE allows you to allocate an extra 512 M memory for all the monitored servers. The value is True or False. The default value is True.
     • SERVER_TYPE is the type of monitoring server to which the data collector is connected. The value is ICAM or APM. The default value is ICAM.

  2. Update the specific variable values according to the Liberty server settings.

  3. If you use Open Liberty, add the following lines to the Dockerfile of your Liberty application:

     COPY path_to_esa_file /opt/
     RUN mkdir -p /opt/ol/wlp/usr/extension/lib/features/
     RUN cd /tmp && unzip /opt/javametrics.liberty.icam-1.2.1.esa && mv /tmp/wlp/liberty_dc /opt/ol/wlp/usr/extension/ && mv /tmp/OSGI-INF/SUBSYSTEM.MF /opt/ol/wlp/usr/extension/lib/features/javametrics.liberty.icam-1.2.1.mf
     COPY path_to_silent_file /opt/ol/wlp/usr/extension/liberty_dc/bin/
     RUN /opt/ol/wlp/usr/extension/liberty_dc/bin/config_unified_dc.sh -silent
     

     Where:

     • path_to_esa_file is the relative path for the downloaded javametrics.liberty.icam-1.2.1.esa file to the current directory. For example, /tmp/javametrics.liberty.icam-1.2.1.esa.
     • path_to_silent_file is the relative path for the silent_config_liberty_dc.txt file to the current directory. For example, /tmp/silent_config_liberty_dc.txt.

  4. If you use WebSphere Liberty, add the following lines to the Dockerfile of your Liberty application:

     COPY path_to_esa_file /opt/
     RUN /opt/ibm/wlp/bin/installUtility install --acceptLicense /opt/javametrics.liberty.icam-1.2.1.esa
     COPY path_to_silent_file /opt/ibm/wlp/usr/extension/liberty_dc/bin/
     RUN /opt/ibm/wlp/usr/extension/liberty_dc/bin/config_unified_dc.sh -silent
     

  5. Add the following environment variables:

     UA_LWDC_LISTENER_URL=http://<ip or host>:<port>
     UA_JAEGER_ENDPOINT=http://<ip or host>:<port>/api/traces
     

     Where

     • <ip or host> is the ip or host address where you install Unified Agent in on-premises environment.
     • <port> is the port that you configure in Installing and configuring Unified Agent plug-ins. By default, it is 8848 for UA_LWDC_LISTENER_URL and 14268 for UA_JAEGER_ENDPOINT.
  6. Build the new docker image.

     docker build -t <application image name>:<image tag> .
     

  7. Start your Liberty application with the new docker image.