Configuring J2SE monitoring

To collect resource monitoring and diagnostic data from the on-premises Java™ applications that are being monitored, you must configure the J2SE data collector.

1. Copy the following files from the APM installer to a directory:
   Important: The directory path must not have any spaces.

   • Copy the gdc.zip file from the APM installer to a directory, and extract it.
   • Copy the gdc-apd.tar.gz file from the APM installer to a directory, and extract it.
   • Provide read/write and execute permissions to the user for the j2se_dc folder. Execute permission is provided to run scripts and JAR files in the folder. Read/write permission is provided because the deep-dive diagnostics files are generated in this folder.
2. On the command line, go to DCHOME\.gdc\<toolkit_version>\bin
   Where toolkit_verion is,
   • For V8.1.4.0 and earlier, toolkit_verion is 7.3.0.5.0.
   • For V8.1.4.0.1 and later, toolkit_verion is 7.3.0.14.0.
3. Run the following command:
   • config.bat
   • config.sh
4. When you are prompted, specify the path to Java Home, and press Enter.
   For example,

   • C:\Program Files\jre7
   • /opt/ibm/java
5. Complete the following steps for the agent version that you use:
   • For V8.1.4.0.2 and earlier, complete the following steps:
     1. When you are prompted, enter the full name (qualified name) of the main class of application, and press Enter. The main class is the entry point of the application that needs to be monitored. Example: testapp.TemperatureConveter
     2. When you are prompted, enter a distinct application alias name, and press Enter. The name that you enter here is used to create the instance name on the APM dashboard.

        The dcstartup.bat file is generated at the following location: DCHOME\.gdc\toolkit_verion\runtime\j2seapplication_alias.hostname.application_alias. This file is the script to run your application along with the data collector.

        The dcstartup.sh file is generated at the following location: DCHOME/.gdc/toolkit_verion/runtime/j2seapplication_alias.hostname.application_alias. This file is the script to run your application along with the data collector.

   • For V8.1.4.0.3 to V8.1.4.0.5, complete the following steps
     1. When prompted, enter the home directory of Java application. For example, /root/J2seApp/
     2. Select a Java application from the list that is provided to you and then Exit.
        • com.ibm.SampleApplication
        • com.ibm.DBApplication
        • com.ibm.SpringBootApplication

        Select any application that is provided in the list or provide 0 to select any other application that is not in the list.

        1. If you provide 0, enter full name of Main class of any other application. For example, com.ibm.testApp.Main
        2. If you select any option from the provided list, alias name is created based on the class name. If the alias name exceeds the character limit, then provide the alias name within the character limit.
           Important: The maximum character limit for alias name is calculated in such a way that alias_name + host_name does not exceed 24 characters.
     3. Select the option to enable or disable Transaction Tracking. The default value is Yes.
     4. Select the option to enable or disable Diagnostics data collection. The default value is Yes.
        1. If you select Yes, then select the option to Method Trace mode. The default value is No.
     5. If you select an option from the list that is provided in Step b, copy the startup script <DCHOME>/j2se_dc/.gdc/toolkit_version/runtime/j2se<application_alias>.<hostname>.<application_alias> to the location of your choice.
   • For V8.1.4.0.6 and later, complete the following steps:
     1. When prompted, enter the home directory of Java application. For example, /root/J2seApp/
     2. Select the application type that you want to monitor.
        • Java Application
        • Jetty Server
     3. If you select the application type as Java Application, then follow the steps that are mentioned in section V8.1.4.0.3 to V8.1.4.0.5 of Step 5.
     4. If you select the application type as Jetty Server, then follow these steps:
        1. Enter the Jetty Home directory. For example, /home/jetty/jetty-distribution-9.4.12.v20180830
        2. Enter the Alias name. If the alias name exceeds the character limit, then provide the alias name within the character limit.
           Important: If you select the application type as Java Application and any option from the list in Step b of section V8.1.4.0.3 to V8.1.4.0.5, then copy the startup script <DCHOME>/j2se_dc/.gdc/toolkit_version/runtime/j2se<application_alias>.<hostname>.<application_alias> to the location of your choice.
     5. If the selected type is Jetty Server, then dcstartup.bat/dcstartup.sh is copied into the given Jetty Home directory.
   • For V8.1.4.0.7, complete the following steps:
     • If you configure J2SE data collector by using the Open JDK version 9 or later and when you enter the path to Java Home, a warning displays with the content as follows:
       Warning:

       
       WARNING: An illegal reflective access operation has occurred
       WARNING: Illegal reflective access by jnr.posix.JavaLibCHelper 
       (file:/root/testopen/preconf-13march/j2se_dc/.gdc/7.3.0.14.0/ bin/lib/jython.jar)to method sun.nio.ch.SelChImpl.getFD()
       WARNING: Please consider reporting this to the maintainers of jnr.posix.JavaLibCHelper
       WARNING: Use --illegal-access=warn to enable warnings of next illegal reflective access operations
       WARNING: All illegal access operations will be denied in next release Mar 15, 2019 11:35:06 AM 
       org.python.netty.util.internal.PlatformDependent <clinit>
       INFO: Your platform does not provide complete lowlevel API for accessing direct buffers reliably. 
       Unless explicitly requested, heap buffer is always preferred 
       to avoid potential system unstability.

       However, the J2SE data collector works correctly and you can ignore the warning.

For V8.1.4.0.2 and earlier versions, follow step 6 to modify dcstartup.bat or dcstartup.sh file.

6. To modify the dcstartup.bat or dcstartup.sh file, complete the following steps:
   • If the application classes and JAR files are bundled in a single JAR file, complete the following steps:
     1. Open the following file:
        • dcstartup.bat
        • dcstartup.sh
     2. Replace -cp .:$classpath:$Classpath $ITCAM_JVM_OPTS full name of the main class with $ITCAM_JVM_OPTS -jar Application jar file and save the file.
   • If the application is using multiple JAR files, complete the following steps:
     1. Open the following file:
        • dcstartup.bat
        • dcstartup.sh
     2. Set the CLASSPATH variable to the JAR files.
     3. Replace -cp .:$classpath:$Classpath $ITCAM_JVM_OPTS full name of the main class with -cp .:$classpath:$Classpath $ITCAM_JVM_OPTS -jar Application jar file and save the file.

        The application JAR file must contain the main application class.

   Note: To modify dcstartup.bat or dcstartup.sh file for V8.1.4.0.3 to V8.1.4.0.5 and V8.1.4.0.6 to later (If the Application type is selected as Java Application) versions, follow step 7.
7. Complete following steps when your application is using multiple JAR files.
   1. Open the following file:
      • dcstartup.bat
      • dcstartup.sh
   2. Set the CLASSPATH variable to the JAR files.
   3. For V8.1.4.0.7, if you configure the J2SE data collector with Java 9 or 10 and if you use the SSL connection for APM connectivity, then the Transaction Tracking data is not displayed. To resolve the issue, you can add the flag --add-modules java.xml.bind to the last line of dcstartup.bat or dcstartup.sh file.

      For example,

      • If the Application is a jar file, then update the last line as follows:

        PathToJava --add-modules java.xml.bind --add-opens=
        jdk.management/com.sun.management.internal=
        ALL-UNNAMED -jar $Classpath $ITCAM_JVM_OPTS AppJarName.jar

      • If the Application is not bundled in a jar file, then update the last line as follows:

        PathToJava --add-modules java.xml.bind --add-opens=
        jdk.management/com.sun.management.internal=ALL-UNNAMED -cp 
        .:$classpath:$Classpath $ITCAM_JVM_OPTS FullyQualifiedClassName 
        

8. To enable deep-dive diagnostics monitoring, edit the custom_request.xml with the J2SE specific classes and methods that you want to monitor. You can do so by two ways: manual and automated process.
   
   To automatically populate the custom_request.xml with the J2SE application-specific classes and methods:
   1. Go to the <DCHOME>/j2se_dc/.gdc/7.3.0.14.0/runtime/j2se<application_alias>.<hostname>.<application_alias>/ directory and open the dc.properties file.
   2. Enable the is.auto.update.custom_requests.xml property by setting its value to true and save the file.
   3. Run commands from step 9.
   4. Stop the data collector after 10 to 15 minutes.
   5. Check whether the DCHOME>/j2se_dc/.gdc/7.3.0.14.0/runtime/j2se<application_alias>.<hostname>.<application_alias>/custom/custom_requests.xml is populated with the custom methods and classes.
   6. Remove the unwanted entries and open the dc.properties file again.
   7. Disable the is.auto.update.custom_requests.xml property by setting its value to false and save the file.
   8. Run commands from step 9.
      Note: If some of the custom methods from the application are not auto-discovered, then you need to add the custom methods manually.
   To manually populate the custom_request.xml:
   1. Go to <DCHOME>/j2se_dc/.gdc/7.3.0.14.0/runtime/j2se<application_alias>.<hostname>.<application_alias>/custom/custom_requests.xml and edit the custom_request.xml.
      For example,

      <edgeRequest>
      
      <requestName>truncateDb</requestName>
      
      <Matches>testApp.JDBC.DBManager</Matches>
      
      <type>application</type>
      
      <methodName>truncateDb</methodName>
      
      </edgeRequest>

   2. Add the application-specific classes and methods.
9. Run the following command:
   • dcstartup.bat
   • dcstartup.sh
   Note: If the selected application type is Jetty Server, then run the dcstartup.bat/dcstartup.sh present in the Jetty Home directory.
   The J2SE application is started along with the configured data collector.