After you install an Application Real-Time Monitoring Service (ARMS) agent for a Java application, ARMS starts to monitor the Java application. Then, you can view the monitoring data of the Java application, such as the application topology, traces, abnormal transactions, slow transactions, and SQL analysis. You can install an ARMS agent manually or by using scripts. This topic shows you how to manually install an ARMS agent for a Java application.

Prerequisites

  • Ensure that the security group of the ECS instance that you use has the TCP outbound permission on the 8442, 8443, 8883, 9092, and 9093 ports. For more information about how to enable outbound permissions for ECS instances, see Add a security group rule.
    Note ARMS can access not only applications on the ECS, but also applications on other servers that can access the Internet.
  • Make sure the third-party components or frameworks that your application uses are supported by ARMS. For more information about the compatibility list, see Supported components and frameworks.
  • Check the version of the Java Development Kit (JDK). ARMS supports the following JDK versions:
    • JDK 1.7.0+
    • JDK 1.8.0_25+
      Note
      • If you deploy applications in Kubernetes clusters, we recommend that you use JDK V1.8.0_191 or later.
      • Make sure that the JDK version is not 1.8.0_25 or 1.8.0_31. Otherwise, the ARMS agent may fail to be installed. In this case, we recommend that you upgrade JDK to the latest 1.8.X.
    • JDK 11.0.8+
    Note JDK versions 1.8 and later have different probe installation packages than JDK versions 11. Download the corresponding probe installation packages or adjust the configurations of application monitoring component ack-onepilot based on different JDK versions.

Procedure

  1. Log on to the ARMS console. In the left-side navigation pane, choose application monitoring > Applications.
  2. On the Applications page, select a region in the top navigation bar, and click Access applications.
  3. In the Backend Applications section of the Integration Center panel, click Java. In the Integrate Java panel, click Manual Installation (Recommended).
  4. Download an ARMS agent.
    • Method 1: Manually download the ARMS agent. In the STEP1 section of the Integrate Java panel, download the ARMS agent based on the JDK version.
    • Method 2: Run the wget command. Download the installation package based on your region.
      Note Use a public endpoint. If you cannot download, use the VPC address.
      The following table lists the download URLs of the agent installation package (JDK version 8 or earlier) for different regions.
      Region Download URL over the Internet Download URL over a VPC
      China (Hangzhou)
      wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Shanghai)
      wget "http://arms-apm-cn-shanghai.oss-cn-shanghai.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-shanghai.oss-cn-shanghai-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Qingdao)
      wget "http://arms-apm-cn-qingdao.oss-cn-qingdao.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-qingdao.oss-cn-qingdao-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Beijing)
      wget "http://arms-apm-cn-beijing.oss-cn-beijing.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-beijing.oss-cn-beijing-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Zhangjiakou)
      wget "http://arms-apm-cn-zhangjiakou.oss-cn-zhangjiakou.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-zhangjiakou.oss-cn-zhangjiakou-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Hohhot)
      wget "http://arms-apm-cn-huhehaote.oss-cn-huhehaote.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-huhehaote.oss-cn-huhehaote-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Ulanqab)
      wget "http://arms-apm-cn-wulanchabu.oss-cn-wulanchabu.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-wulanchabu.oss-cn-wulanchabu-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Shenzhen)
      wget "http://arms-apm-cn-shenzhen.oss-cn-shenzhen.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-shenzhen.oss-cn-shenzhen-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Heyuan)
      wget "http://arms-apm-cn-heyuan.oss-cn-heyuan.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-heyuan.oss-cn-heyuan-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Guangzhou)
      wget "http://arms-apm-cn-guangzhou.oss-cn-guangzhou.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-guangzhou.oss-cn-guangzhou-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Chengdu)
      wget "http://arms-apm-cn-chengdu.oss-cn-chengdu.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-chengdu.oss-cn-chengdu-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China (Hong Kong)
      wget "http://arms-apm-cn-hongkong.oss-cn-hongkong.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-hongkong.oss-cn-hongkong-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      Singapore
      wget "http://arms-apm-ap-southeast-1.oss-ap-southeast-1.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-ap-southeast-1.oss-ap-southeast-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      Australia (Sydney)
      wget "http://arms-apm-ap-southeast-2.oss-ap-southeast-2.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-ap-southeast-2.oss-ap-southeast-2-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      Malaysia (Kuala Lumpur)
      wget "http://arms-apm-ap-southeast-3.oss-ap-southeast-3.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-ap-southeast-3.oss-ap-southeast-3-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      Indonesia (Jakarta)
      wget "http://arms-apm-ap-southeast-5.oss-ap-southeast-5.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-ap-southeast-5.oss-ap-southeast-5-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      Japan (Tokyo)
      wget "http://arms-apm-ap-northeast-1.oss-ap-northeast-1.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-ap-northeast-1.oss-ap-northeast-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      Germany (Frankfurt)
      wget "http://arms-apm-eu-central-1.oss-eu-central-1.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-eu-central-1.oss-eu-central-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      UK (London)
      wget "http://arms-apm-eu-west-1.oss-eu-west-1.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-eu-west-1.oss-eu-west-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      US (Virginia)
      wget "http://arms-apm-us-east-1.oss-us-east-1.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-us-east-1.oss-us-east-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      US (Silicon Valley)
      wget "http://arms-apm-us-west-1.oss-us-west-1.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zipwget "http://arms-apm-us-west-1.oss-us-west-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-us-west-1.oss-us-west-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      India (Mumbai)
      wget "http://arms-apm-ap-south-1.oss-ap-south-1.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-ap-south-1.oss-ap-south-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China East 1 Finance N/A
      wget "http://arms-apm-cn-hangzhou-finance.oss-cn-hzjbp-b-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China East 2 Finance N/A
      wget "http://arms-apm-cn-shanghai-finance-1.oss-cn-shanghai-finance-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China South 1 Finance N/A
      wget "http://arms-apm-cn-shenzhen-finance-1.oss-cn-shenzhen-finance-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      China North 2 Ali Gov
      wget "http://arms-apm-cn-north-2-gov-1.oss-cn-north-2-gov-1.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
      wget "http://arms-apm-cn-north-2-gov-1.oss-cn-north-2-gov-1-internal.aliyuncs.com/ArmsAgent.zip" -O ArmsAgent.zip
  5. Install the ARMS agent.
    1. Go to the directory of the installation package. Run the following command to decompress the installation package to a working directory:
      unzip ArmsAgent.zip -d /{user.workspace}/ 
      Note {user.workspace} is a sample directory. Replace it with the actual directory.
    2. Add the AppName and LicenseKey parameters.
      Section LicenseKey
      Note Replace {LicenseKey} in the sample code with the license key obtained in the STEP2 section. Replace {AppName} with your application name. The application name cannot contain Chinese characters. Replace {user.workspace} with the directory where the ARMS agent is decompressed. Replace demoApp.jar with the path to the actual JAR package.
      • Method 1: Edit the JVM parameters based on the runtime environment of your application.
        Runtime environment Procedure
        Tomcat on Linux or macOS

        Append the following configurations to the {TOMCAT_HOME}/bin/setenv.sh file:

        JAVA_OPTS="$JAVA_OPTS -javaagent:/{user.workspace}/ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} " 

        If your Tomcat does not contain the setenv.sh configuration file, open the {TOMCAT_HOME}/bin/catalina.sh file and append the preceding configurations to the JAVA_OPTS parameter. For more information, see Row 256 in the catalina.sh file.

        Tomcat on Windows Append the following configurations to the {TOMCAT_HOME}/bin/catalina.bat file:
        set "JAVA_OPTS=%JAVA_OPTS% -javaagent:/{user.workspace}/ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName}" 

        If the preceding setting does not take effect, append the following configurations to the {TOMCAT_HOME}/bin/catalina.bat file:

        set "CATALINA_OPTS=-javaagent:/{user.workspace}/arms-bootstrap-1.7.0-SNAPSHOT.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName}"
        Jetty

        Append the following configurations to the {JETTY_HOME}/start.ini configuration file:

        --exec
        -javaagent:/{user.workspace}/ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar
        -Darms.licenseKey={LicenseKey}
        -Darms.appName={AppName} 
        Spring Boot

        When you start the Spring Boot process, append the -javaagent parameter to the startup command:

        java -javaagent:/{user.workspace}/ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -jar demoApp.jar 
        Resin

        When you start the Resin process, append the following tag to the conf/resion.xml configuration file:

        <server-default>
            <jvm-arg>-javaagent:{user.workspace}/ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar</jvm-arg>
            <jvm-arg>-Darms.licenseKey={LicenseKey}</jvm-arg>
            <jvm-arg>-Darms.appName={AppName}</jvm-arg>
        </server-default> 

        Append the following tag to the conf/app-default.xml file:

        <library-loader path="{user.workspace}/ArmsAgent/plugin"/> 
        Windows

        When you run a CMD command to start the Java process, use a backslash (\) as the delimiter in the mount path of the ARMS agent.

        java -javaagent:\{user.workspace}\ArmsAgent\arms-bootstrap-1.7.0-SNAPSHOT.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -jar {user.workspace}\demoApp.jar 

        To deploy multiple instances of the same application on a server, you can differentiate the JVM processes by setting the -Darms.agentId parameter to a logical number. Example:

        java -javaagent:/{user.workspace}/ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.agentId=001 -jar demoApp.jar
      • Method 2: Append the following configurations to the arms-agent.config file:
        arms.licenseKey={LicenseKey} arms.appName={AppName}
  6. Append the following parameter to the startup script of the Java application:
    -javaagent:/{user.workspace}/ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar 
    The ARMS agent V2.7.1.4 allows you to activate Application Security when you connect your application to Application Monitoring. If you need to activate Application Security, add -Darms.appsec.enable=true to the preceding command.
    Note For information about the billing rules of Application Security, see Billing rules.
  7. Restart the Java application.

Verify the result

After about 1 minute, if your application is displayed on the Applications page and some data records are sent, your application is monitored by ARMS.

Uninstall the ARMS agent

If you no longer need to monitor your Java application by using ARMS, perform the following steps to uninstall the ARMS agent.

  1. Delete all parameters that you added in Step 7, such as {AppName} and {LicenseKey}.
  2. Restart the Java application.

Change the application name

If you forget to change the sample name Java-Demo to a custom name, you can change the application name without the need to restart the application or reinstall the ARMS agent. For more information, see How do I change the name of a common Java application on which an ARMS agent is manually installed?