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 Cloud APM server.

• 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.
     • The path of onprem_config.tar is provided in silent_file, for example, CONFIGPACK_PATH=/opt/ibm/ccm/mkcustpkg_workdir.7378/onprem_config.tar.
  3. 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=apm
     CONFIGPACK_PATH=/opt/ibm/ccm/mkcustpkg_workdir.7378/onprem_config.tar
     APM_KEYFILE_PASSWORD=xxx

     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 APM.
     • CONFIGPACK_PATH is the absolute path of the configuration package.
     • You need to input the password in APM_KEYFILE_PASSWORD if the password in config pack is not the default one.
  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. Build the new docker image.

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

  6. Start your Liberty application with the new docker image.
• If a proxy is set for the JVM, add the JVM_ARGS variable to the container specification in the application deployment yaml file to define the proxy properties.
  • If authentication is not required, specify the JVM_ARGS variable value as follows:

    - name: JVM_ARGS
            value: "-Dhttp.proxyHost=http_proxy_host -Dhttp.proxyPort=http_proxy_port 
    -Dhttps.proxyHost=https_proxy_host -Dhttps.proxyPort=https_proxy_port -Djava.net.useSystemProxies=true 
    -Dhttp.nonProxyHosts=non_proxy_host"

  • If a user ID and password is required to access the proxy, specify the JVM_ARGS variable value as follows:

    - name: JVM_ARGS
               value: "-Dhttp.proxyHost=http_proxy_host -Dhttp.proxyPort=http_proxy_port -Dhttp.proxyUser=http_proxy_user 
    -Dhttp.proxyPassword=http_proxy_pwd -Dhttps.proxyHost=https_proxy_host 
    -Dhttps.proxyPort=https_proxy_port -Dhttps.proxyUser=https_proxy_user 
    -Dhttps.proxyPassword=https_proxy_pwd -Djava.net.useSystemProxies=true -Dhttp.nonProxyHosts=non_proxy_host"

  Note:

  • All proxy properties that are embraced by double quotation marks ("") must be set on the same line as value: and separated by a space.
  • The -Djava.net.useSystemProxies value must be set to true.
  • Use the -Dhttp.nonProxyHosts variable to specify the IPs that are used for internal communication and the asterisk (*) can be used. If you want to designate multiple settings for the -Dhttp.nonProxyHosts variable, use the double quotation mark to surround the settings. But don’t use the double quotation mark for other varaiables, or it will bring proxy not set error.
    If there is one setting for the -Dhttp.nonProxyHosts variable, see the following example.

    - name: JVM_ARGS
               value: "-Dhttp.proxyHost=9.42.23.52 -Dhttp.proxyPort=82 -Dhttp.proxyUser=myproxy 
    -Dhttp.proxyPassword=mypwd -Dhttps.proxyHost=9.42.23.52 -Dhttps.proxyPort=82 
    -Dhttps.proxyUser=myproxy -Dhttps.proxyPassword=mypsw -Djava.net.useSystemProxies=true -Dhttp.nonProxyHosts=10.*"

    If there are multiple settings for the -Dhttp.nonProxyHosts variable, see the following example, where 10.*|localhost are surrounded by the double quotation.

    - name: JVM_ARGS
               value: "-Dhttp.proxyHost=9.42.23.52 -Dhttp.proxyPort=82 -Dhttp.proxyUser=myproxy -Dhttp.proxyPassword=mypwd 
    -Dhttps.proxyHost=9.42.23.52 -Dhttps.proxyPort=82 -Dhttps.proxyUser=myproxy -Dhttps.proxyPassword=mypsw 
    -Djava.net.useSystemProxies=true -Dhttp.nonProxyHosts=\"10.*|localhost\""

  • Liberty data collector monitoring might fail with the following error message, because the features that are installed by Cloud APM server, such as jsp-2.2 and servlet-3.0, have conflict with the dependent features of mpMetrics-1.1.

    [4/12/21 12:34:22:295 EDT] 00000036 com.ibm.ws.kernel.feature.internal.FeatureManager            E CWWKF0033E: The singleton features com.ibm.websphere.appserver.javaeeCompatible-6.0 and com.ibm.websphere.appserver.javaeeCompatible-7.0 cannot be loaded at the same time.  The configured features jsp-2.2 and mpMetrics-1.1 include one or more features that cause the conflict. Your configuration is not supported; update server.xml to remove incompatible features.

    You need to remove the following features in server.xml:

    <feature>mpMetrics-1.1</feature>
    <feature>websocket-1.1</feature>
    <feature>ibmJaxrsExt-1.0</feature>

    Then, restart Cloud APM server by running the following command:

    apm restart_all