After you install the agent for a Java application, Cloud Monitor 2.0 starts monitoring the Java application. You can view a series of monitoring data, such as application topology, call stacks, abnormal transactions, slow transactions, and SQL analysis. This topic describes how to manually install the agent for a Java application.
For applications that are deployed in a Kubernetes environment, manual agent installation is not recommended. Instead, install the agent by installing a component. For more information, see Install the Java agent for Container Service for Kubernetes (ACK) and Container Compute Service (ACS) using the ack-onepilot component.
Prerequisites
Before you begin, make sure that:
Your network meets the ARMS agent connectivity requirements
Your JDK version is one of the Supported JDK versions
The JVM maximum heap memory (
-Xmx) is at least 256 MB
Install the agent
Log on to the Cloud Monitor 2.0 console, and select a workspace. In the left navigation pane, click Integration Center.
Click the Java Application Monitor card and then click Manual Installation.
Download the agent package using one of the following methods:
From the console -- In the Java Application Monitor panel, follow the download prompts.
From the command line -- Run the
wgetcommand for your region. Select your region from the table below.
Extract the downloaded ZIP file to a working directory:
unzip AliyunJavaAgent.zip -d <working-directory>Replace
<working-directory>with the directory where you want to install the agent.Add the AppName and LicenseKey parameters.
On the Java Application Monitoring panel, obtain the LicenseKey. The AppName parameter specifies the application in ARMS to connect to. You can customize the application name. In a distributed architecture, an application can contain multiple peer instances.
ImportantThe LicenseKey is specific to each workspace. You must obtain a new LicenseKey for a new workspace.
You can add the AppName and LicenseKey in one of the following ways.
Method 1 (Recommended): In the startup script, replace
{LicenseKey}and{AppName}with the LicenseKey that you obtained from the console and the AppName of your application.Method 2: If you want to reuse the startup script for different applications, you can specify the LicenseKey and AppName by modifying the agent configuration file. To do this, perform the following steps:
NoteFor agent versions earlier than 4.4.0, this method connects the application to the default workspace.
In the version file that you unzipped in the previous step, check the Java agent version.
Modify the agent configuration file.
Agents of version 4.0.0 and later
In the agent directory, create a file named arms-agent.properties and add the following configurations. Then, add
-Dotel.javaagent.configuration-file=/path/to/arms-agent.propertiesto the startup command or add theOTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/arms-agent.propertiesenvironment variable to enable the configuration file.arms.licenseKey={LicenseKey} arms.appName={AppName}Agents earlier than version 4.0.0
In the arms-agent.config file within the agent package, add the following configurations.
arms.licenseKey={LicenseKey} arms.appName={AppName}NoteFor more information about other configuration items in the agent configuration file, see Modify the Java agent configuration file and the default reporting region.
Add the connection command to the startup command.
Replace
{user.workspace}with the directory where you unzipped the agent installation package. Replace demoApp.jar with the actual path of your JAR package.NoteIf you are using an agent version earlier than 2.7.3.5, replace AliyunJavaAgent/aliyun-java-agent.jar in this topic with ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar. We recommend that you upgrade the agent to the latest version as soon as possible.
On a Windows operating system, replace
/with\and replace the.shfile extension with.batin the script.Agents of V2.7.1.4 and later support application security. To enable application security when you connect to Application Monitoring, add
-Darms.appsec.enable=trueto the script. For more information about the billing rules for application security, see Billing.
Runtime environment
Steps
Spring Boot or other Java applications that are started using the
java -jarcommandAdd the -javaagent parameter to the startup command. Make sure that the -javaagent parameter is placed before the -jar parameter.
java -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} -jar demoApp.jarTomcat
Add the following configuration to the {TOMCAT_HOME}/bin/setenv.sh file.
JAVA_OPTS="$JAVA_OPTS -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} "If your Tomcat version does not have the setenv.sh configuration file, open the {TOMCAT_HOME}/bin/catalina.sh file and add the preceding configuration after JAVA_OPTS. For an example, see line 256 of catalina.sh.
Jetty
Add the following configuration to the {JETTY_HOME}/start.ini configuration file.
aliyun-java-agent.jar --exec -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace}To deploy multiple instances of the same application on a single server, use the -Darms.agentId parameter (a logical ID) to differentiate JVM processes. For example:
java -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} -Darms.agentId=001 -jar demoApp.jarRestart the Java application.
(Optional) Install with Docker
For Docker environments, you can refer to the following Dockerfile example to modify your Dockerfile.
# Replace {original-docker-image:tag} with your image address.
FROM {original-docker-image:tag}
# Replace the working directory as needed.
WORKDIR /root/
# Refer to the agent installation steps above to get the agent download URL for your region. Note the difference between the public endpoint and the VPC endpoint.
RUN wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/AliyunJavaAgent.zip" -O AliyunJavaAgent.zip
# Decompress the agent.
RUN unzip AliyunJavaAgent.zip -d /root/
# Write LicenseKey, AppName, and workspace to environment variables.
ENV arms_licenseKey={LicenseKey}
ENV arms_appName={AppName}
ENV arms_workspace={workspace}
# Concatenate the required startup script and append it to the JAVA_TOOL_OPTIONS environment variable.
ENV JAVA_TOOL_OPTIONS ${JAVA_TOOL_OPTIONS} '-javaagent:/root/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey='${arms_licenseKey}' -Darms.appName='${arms_appName}' -Darms.workspace='${arms_workspace}
# Check the JAVA_TOOL_OPTIONS environment variable.
RUN env | grep JAVA_TOOL_OPTIONS
# Add custom Dockerfile logic below.
# ......View monitoring details
Log on to the Cloud Monitor 2.0 console, and select a workspace. In the left navigation pane, choose All features > Application Observability > Application Monitoring.
The Application List page displays your connected applications. Click an application name to view detailed monitoring data.