1. Precheck

  • Make sure that the collector is deployed on a separate server without online applications.
  • Make sure that JAVA_HOME and JDK 1.6 or later have been configured.

2. Start

 Run the following command in the collector directory in Unix:
 './run.sh'
 Run the following command in the collector directory in Windows:
 'start /b java -jar javaagent-collector.jar'
			

View the collector/logs/collector.log file. If the log file displays start or success, the collector is deployed.

If an error occurs, visit the following URL to troubleshoot the error: Collect application data

Javaagent

1. Configurations before startup

  • Make sure that the JAVA_HOME environment variable has been configured. Otherwise, set the address of JAVA_HOME in attach.sh as the absolute path of JDK. Note that if you use JRE instead of JDK, you must copy tools.jar to the ${JAVA_HOME}/lib/ directory.
  • Configure javaagent.config: profiler.collector.ip = 11.23.45.67 # Specify the IP address of the collector. profiler.collector.port = 9996 # Specify the collector port. profiler.app.name = adamApp # Specify the application name. It must be less than 20 characters in length and must contain letters and digits. profiler.app.port = 8080 # Specify the startup port of the application. Although numerous ports with different functions are available for an application, you only need to configure the requested port. Configure one port regardless of the number of applications in a JVM. profiler.applicationservertype = TOMCAT # Specify the container type of the application middleware. Valid values: TOMCAT, JBOSS, and WEBLOGIC.

Optional Configurations

	Configure prefixes of the directories where the Java code to test is located. Replace the directories in the following example. Separate multiple directories with commas (,). Each directory must have at least two levels of subdirectories. We recommend that you specify no more than five directories.
	When there are changes in databases, the collector can provide specific application transformation suggestions based on the precise call stack information.
	If not all directories can be provided, you can leave this parameter unspecified. You can configure filters on the analysis page of the Alibaba Cloud ADAM console.
	`profiler.classpath.whitelist = com.alibaba.javaagent,com.alibaba.adam`
	If the preceding whitelist is specified, you can leave this parameter unspecified. You can also specify a blacklist to filter unneeded call stack information.
	`profiler.classpath.blacklist =org.apache,net.sf`
	Configure to pause data collection when the number of CPUs reaches the specified limit.
	`profiler.cpu.threshold = 85`
	Specify the interval at which system information is collected. Unit: minutes. Default value: 15.
	`profiler.sys.send.interval = 15`
	Specify the interval at which dynamic SQL information is collected. Unit: minutes. Default value: 15.
	`profiler.sql.dynamic.send.interval = 15`
			

2. Startup methods

Method 1: Monitor only once without restarting the application

Add system operation permissions to the javaagent directory. Ensure that the account used to start the agent is the same as that used to start the application. Run the following code by replacing ${pid} with the process ID of the application:

Run the following command in Unux:
`./attach.sh -p ${pid}`

Run the following command in Windows:
`java -cp "%JAVA_HOME%\lib\tools.jar;%cd%\javaagent-bootstrap.jar" com.alibaba.adam.javaagent.bootstrap.AgentAttacher -p ${pid}`
			

If the log file in the javaagent directory displays success, the collector is started. If inbound traffic is generated in the application and the collector directory contains a directory with data, the agent is started and is sending data to the collector. If an error occurs, visit the following URL to troubleshoot the error: Collect application data

  • Make sure that the obtained process ID of the application is correct.
  • Make sure that the account used to start the agent is the same as that used to start the application, and that the agent and the application have identical system operation permissions. Otherwise, the agent cannot monitor the application. If the application is started using Windows registry SYSTEM, the agent cannot be started by using Method 1 because of inconsistent account permissions.

Method 2: Start monitoring when the application restarts (recommended)

Replace ${javaagent_path} with the directory of the javaagent in the configuration file, and then restart the application.

Unix

Tomcat: Add the following text after the last CATALINA_OPTS configuration item in the catalina.sh startup file:
	CATALINA_OPTS="$CATALINA_OPTS -javaagent:${javaagent_path}/javaagent-bootstrap.jar"

JBoss: Add the following text to the last JAVA_OPTS configuration item in the run.conf startup file:
	JAVA_OPTS="$JAVA_OPTS -javaagent:${javaagent_path}/javaagent-bootstrap.jar"

Weblogic: Add the following text to the last JAVA_OPTIONS configuration item in the startWebLogic.sh startup file:
	JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:${javaagent_path}/javaagent-bootstrap.jar"

Websphere:
	Method 1: Add JAVA_OPTS="$JAVA_OPTS -javaagent:/home/admin/javaagent/javaagent-bootstrap.jar" to the configuration file.
	Method 2: Add the following text to the common Java Virtual Machine (JVM) parameters:
	name:javaagent  value:/home/admin/javaagent/javaagent-bootstrap.jar
	
Docker containers in Kubernetes clusters:
	Place the javaagent directory into a Docker image, add the corresponding javaagent configuration file, and deploy the image.
			

Windows:

Tomcat: Add the following text to the last CATALINA_OPTS configuration item in the catalina.bat startup file:
	CATALINA_OPTS="$CATALINA_OPTS -javaagent:${javaagent_path}/javaagent-bootstrap.jar"

JBoss: Add the following text to the last JAVA_OPTS configuration item in the run.conf startup file:
	JAVA_OPTS="$JAVA_OPTS -javaagent:${javaagent_path}/javaagent-bootstrap.jar"

Weblogic: Add the following text to the last JAVA_OPTIONS configuration item in the startWebLogic.cmd startup file:
	JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:${javaagent_path}/javaagent-bootstrap.jar"

Websphere:
	Method 1: Add JAVA_OPTS="$JAVA_OPTS -javaagent:/home/admin/javaagent/javaagent-bootstrap.jar" to the configuration file.
	Method 2: Add the following text to the common JVM parameters:
	name:javaagent  value:/home/admin/javaagent/javaagent-bootstrap.jar
			

After the application is started, view the application logs. If Java Agent load successfully! is displayed, the agent has been started. If an error occurs, modify the script based on the error message. If no agent information is displayed, the agent was not loaded because the configuration path is invalid.

Advantages and disadvantages

Startup method Advantage Disadvantage Scenario
Method 1 You can configure the agent without restarting the application whose data has not been collected. You must manually start the agent each time you restart the application. The account used to start the agent must be the same as that used to start the application. This method is applicable to applications that go for extended periods of time without being restarted and whose services will be affected if they are restarted.
Method 2 The agent starts automatically when you restart the application, and the agent continuously collects application data. Account permissions are not considered. When you collect the application data for the first time, you must restart the application to start the agent. This method is applicable to restartable applications or applications whose data is continuously collected.

Notes

  • When the application stops, the agent also stops regardless of which method was used to start the agent.

  • You can use the following methods to stop the agent. Method 1: Restart the application or use the ./attach.sh -p ${pid} -s command. Method 2: Remove the configurations of the javaagent and restart the application.

  • If you want to perform monitoring after the agent has been stopped, you must restart the application. Method 1: Start the agent manually after the application has been restarted. Method 2: Wait for the agent to automatically start when the application restarts.

  • JBoss clusters are divided into Community Edition and Enterprise Edition. If there is a jboss.modules.system.pkgs configuration item, you must add the com.alibaba.adam.javaagent directory and restart the application to make the monitoring take effect regardless of whether you use Method 1 or 2.

Collect data (Data of one to seven days)

  • Go to the collector directory, package the files in the data/ directory in ZIP format by application name, and upload each application profile separately. Remember that one application corresponds to one profile. Data collected for an application from different IP addresses can be packaged together, but data for different applications cannot be packaged together. Otherwise, an upload error is reported.

Application profiling