Attach the Application Real-Time Monitoring Service (ARMS) Java agent to your application to collect traces, application topology, abnormal and slow transaction data, and SQL analysis.
For applications deployed in Container Service for Kubernetes (ACK) clusters, install the ack-onepilot component instead. See Automatically install an ARMS agent in ACK or Automatically install an ARMS agent in an open-source Kubernetes cluster.
Prerequisites
Before you begin, make sure that:
Your network meets the ARMS agent connectivity requirements
Your JDK version is supported by Application Monitoring
The JVM maximum heap memory (
-Xmx) is at least 256 MB
Install the ARMS agent
Step 1: Download the agent
Log on to the ARMS console.
In the left-side navigation pane, click Integration Center.
Click the Java Application Monitor card, then select 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.
Step 2: Extract the agent package
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, for example, /opt/arms.
Step 3: Configure the license key and application name
The ARMS agent requires two parameters to report data:
| Parameter | Description | Where to find it |
|---|---|---|
LicenseKey | Authenticates the agent with your ARMS account | Copy from the Java Application Monitor panel, or call the DescribeTraceLicenseKey API |
AppName | Identifies your application in the ARMS console. In a distributed architecture, multiple peer instances share the same name. | Choose a name, for example, order-service |
Pass these parameters in one of two ways:
Option A: Pass as JVM arguments (recommended)
Add -Darms.licenseKey and -Darms.appName directly in the startup command. See Step 4 for the full command.
Option B: Use a configuration file
This approach is useful when multiple applications share a single startup script.
First, check the agent version in the version file inside the extracted directory.
ARMS agent V4.0.0 or later:
Create a file named arms-agent.properties in the agent directory:
arms.licenseKey=<your-license-key>
arms.appName=<your-app-name>Then add one of the following to your startup command:
JVM argument:
-Dotel.javaagent.configuration-file=/path/to/arms-agent.propertiesEnvironment variable:
OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/arms-agent.properties
ARMS agent earlier than V4.0.0:
Edit the arms-agent.config file in the agent directory:
arms.licenseKey=<your-license-key>
arms.appName=<your-app-name>For details on other agent parameters, see Modify ARMS agent parameters and data reporting regions.
Step 4: Add the agent to your startup command
Add the -javaagent option to your startup command. The syntax varies by runtime environment.
Replace the following placeholders with your actual values:
| Placeholder | Description | Example |
|---|---|---|
<working-directory> | Directory where you extracted the agent | /opt/arms |
<your-license-key> | Your ARMS license key | a]xxxxxx@xxxxxxxx |
<your-app-name> | Application name for ARMS | order-service |
Spring Boot or java -jar
Place -javaagent before the -jar argument:
java -javaagent:/<working-directory>/AliyunJavaAgent/aliyun-java-agent.jar \
-Darms.licenseKey=<your-license-key> \
-Darms.appName=<your-app-name> \
-jar demoApp.jarTomcat
Add the following line to {TOMCAT_HOME}/bin/setenv.sh:
JAVA_OPTS="$JAVA_OPTS -javaagent:/<working-directory>/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey=<your-license-key> -Darms.appName=<your-app-name>"If setenv.sh does not exist, append the same configuration to the JAVA_OPTS parameter in {TOMCAT_HOME}/bin/catalina.sh. See catalina.sh line 256 for reference.
Jetty
Append the following to {JETTY_HOME}/start.ini:
--exec
-javaagent:/<working-directory>/AliyunJavaAgent/aliyun-java-agent.jar
-Darms.licenseKey=<your-license-key>
-Darms.appName=<your-app-name>Multiple instances on the same server
To run multiple instances of the same application on one server, add -Darms.agentId with a unique value to differentiate JVM processes:
java -javaagent:/<working-directory>/AliyunJavaAgent/aliyun-java-agent.jar \
-Darms.licenseKey=<your-license-key> \
-Darms.appName=<your-app-name> \
-Darms.agentId=001 \
-jar demoApp.jarFor agent versions earlier than V2.7.3.5, replace
AliyunJavaAgent/aliyun-java-agent.jarwithArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar. Upgrade to the latest version at your earliest convenience.On Windows, replace
/with\in paths and use.batfiles instead of.shfiles.To enable Application Security (available from V2.7.1.4), add
-Darms.appsec.enable=true. See Application Security billing for pricing.
Step 5: Restart the application
Restart your Java application for the agent to take effect.
(Optional) Install with Docker
Use the following Dockerfile as a template to install the ARMS agent in a Docker image:
# Replace <your-base-image:tag> with your image
FROM <your-base-image:tag>
WORKDIR /root/
# Download the agent (use the URL for your region; see Step 1)
RUN wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/AliyunJavaAgent.zip" -O AliyunJavaAgent.zip
RUN unzip AliyunJavaAgent.zip -d /root/
# Set credentials as environment variables
ENV arms_licenseKey=<your-license-key>
ENV arms_appName=<your-app-name>
# Inject the agent via JAVA_TOOL_OPTIONS
ENV JAVA_TOOL_OPTIONS ${JAVA_TOOL_OPTIONS} '-javaagent:/root/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey='${arms_licenseKey}' -Darms.appName='${arms_appName}
# Verify the environment variable
RUN env | grep JAVA_TOOL_OPTIONS
# Add your application-specific instructions below
# ...Verify the installation
After you restart the application, the agent starts reporting data within about one minute.
In the ARMS console, choose Application Monitoring > Application List.
Confirm that your application appears in the list and that data records are being sent.
If your application does not appear after a few minutes, check the following:
| Issue | Action |
|---|---|
| Incorrect credentials | Verify that the LicenseKey and AppName values match the values in the ARMS console. |
| Wrong agent path | Confirm that the -javaagent path points to the correct aliyun-java-agent.jar file. |
| Application not restarted | Restart the application after adding the agent configuration. |
| Network connectivity | Verify that the server can reach the ARMS endpoint over the network. See Network configurations. |
| Agent startup failure | Check the application startup logs for ARMS agent initialization messages. Look for lines containing ArmsAgent or arms-agent. If no agent log entries appear, the -javaagent argument may not have been loaded. |
For more troubleshooting guidance, see the Application Monitoring FAQ.