To collect resource monitoring and diagnostic data from the on-premises Java™ applications that are being monitored, you must configure the J2SE data collector.
Before you begin
Install one of the supported Java runtimes:
- Oracle Java Platform Standard Edition 7 (Java SE Development Kit 7)
Remember: This Java Runtime does
not support the J2SE data collector image that is configured with HTTPS protocol.
- Oracle Java Platform Standard Edition 7 (Java SE Runtime Environment 7)
Remember: This Java Runtime does not support the J2SE data collector image that
is configured with HTTPS protocol.
- Oracle Java Platform Standard Edition 8 (Java SE Development Kit 8)
- Oracle Java Platform Standard Edition 8 (Java SE Runtime Environment 8)
- IBM® SDK, Java
Technology Edition, Version 7
- IBM SDK, Java
Technology Edition, Version 8
Important: For Windows server 2016,
install JDK 8, update 131 (Java SE Development Kit 8u131), or Java SE Development Kit 7, and update 80 (JDK
7u80).
For more information about system requirements, see Software Product Compatibility Reports for J2SE data
collector.
About this task
You can configure the J2SE data collector on Windows, Linux®, and AIX® systems.The directions here are for the most current release of this agent. For
information about how to check the version of an agent in your environment, see Agent version
command. For detailed information about the agent
and data collector version list and what's new for each version, see the Change history.
Procedure
-
Copy the following files from the APM installer to a directory:
-
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.
-
Run the following command:
config.bat
config.sh
-
When you are prompted, specify the path to Java Home, and
press Enter.
For example,
- C:\Program Files\jre7
- /opt/ibm/java
-
Complete the following steps for the agent version that you use:
- For V8.1.4.0.2 and earlier, complete the following steps:
- 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
- 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
- When prompted, enter the home directory of Java application. For example, /root/J2seApp/
- 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.
- If you provide 0, enter full name of Main class of any other application.
For example, com.ibm.testApp.Main
- 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.
- Select the option to enable or disable Transaction Tracking. The default value is
Yes.
- Select the option to enable or disable Diagnostics data collection. The default value is
Yes.
- If you select Yes, then select the option to Method Trace mode. The default
value is No.
- 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:
- When prompted, enter the home directory of Java application. For example, /root/J2seApp/
- Select the application type that you want to monitor.
- Java Application
- Jetty Server
- 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.
- If you select the application type as Jetty Server, then
follow these steps:
- Enter the Jetty Home directory. For example,
/home/jetty/jetty-distribution-9.4.12.v20180830
- 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.
- 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:
For V8.1.4.0.2 and earlier versions, follow step 6 to modify dcstartup.bat or dcstartup.sh
file.
-
To modify the dcstartup.bat or dcstartup.sh file, complete the following steps:
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.
-
Complete following steps when your application is using multiple JAR
files.
-
Open the following file:
- dcstartup.bat
- dcstartup.sh
-
Set the CLASSPATH variable to the JAR files.
-
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
-
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:
-
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.
-
Enable the is.auto.update.custom_requests.xml property by setting its
value to true and save the file.
-
Run commands from step 9.
-
Stop the data collector after 10 to 15 minutes.
-
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.
-
Remove the unwanted entries and open the dc.properties file again.
-
Disable the is.auto.update.custom_requests.xml property by setting its
value to false and save the file.
-
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:
-
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>
-
Add the application-specific classes and methods.
-
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.
What to do next
Log in to the Cloud APM console to view the
data that is collected by the data collector in the dashboards. For information about using the
console, see Starting the Cloud APM console.For help with
troubleshooting, see the Troubleshooting section.