To analyze your Java applications for database migration, deploy a collector and configure a Java agent using Alibaba Cloud Advanced Database & Application Migration (ADAM). The collector receives call stack data from Java agents attached to your applications, which ADAM then uses to generate migration recommendations.
The deployment has two parts:
Collector — a standalone service that receives data from Java agents
Java agent — a lightweight component attached to your Java applications that sends call stack data to the collector
Complete both parts before collecting data.
Prerequisites
Before you begin, make sure that:
The collector server is dedicated — no online applications are running on it
JAVA_HOMEis set and JDK 1.6 or later is installed on the collector server(Method 1 only) The account used to start the Java agent matches the account used to start the application
Deploy the collector
Run the following command in the directory where the collector is installed.
Unix:
./run.shWindows:
start /b java -jar javaagent-collector.jarVerify: Open collector/logs/collector.log. If the log contains startup or success, the collector is running.
If you encounter errors, see Application Collector FAQ.
Configure the Java agent
Step 1: Set up the environment
Make sure JAVA_HOME is configured. If JAVA_HOME is not configured, set the value of JAVA_HOME in the attach.sh file to the absolute path of JDK. If you use JRE instead of JDK, manually copy tools.jar to ${JAVA_HOME}/lib/.
Step 2: Edit javaagent.config
Set the required parameters:
| Parameter | Description | Example |
|---|---|---|
profiler.collector.ip | IP address of the collector | 11.23.45.67 |
profiler.collector.port | Collector port | 9996 |
profiler.app.name | Application name. Must be fewer than 20 characters and contain only letters and digits. | adamApp |
profiler.app.port | Application startup port. Configure one port per JVM regardless of the number of applications in the JVM. | 8080 |
profiler.applicationservertype | Container type of the application middleware. Valid values: TOMCAT, JBOSS, WEBLOGIC. | TOMCAT |
Optional parameters:
| Parameter | Default | Description |
|---|---|---|
profiler.classpath.whitelist | — | Prefixes of directories containing the Java code to be tested. Separate multiple entries with commas. Each directory must have at least two subdirectory levels. Specify no more than five directories. If databases are changed, the collector uses precise call stack data from these directories to suggest application configuration updates. If you cannot specify directories here, configure filters on the ADAM console analysis page instead. |
profiler.classpath.blacklist | — | Denylist to filter out unnecessary call stack information. Can be omitted if the allowlist is set. |
profiler.cpu.threshold | — | CPU utilization limit (%). Data collection pauses when this limit is reached. Example: 85 |
profiler.sys.send.interval | 15 | Interval (in minutes) for collecting system information. |
profiler.sql.dynamic.send.interval | 15 | Interval (in minutes) for collecting dynamic SQL information. |
Start the Java agent
Choose a startup method based on whether you can restart the application.
Choose your startup method
| Method 1: Attach without restart | Method 2: Start with application (recommended) | |
|---|---|---|
| When to use | The application has been running without a restart for a long time, and restarting it would affect your business. | The application can be restarted, and you want continuous data collection without manual intervention. |
| How it starts | Manually attach the agent to the running process. | Add the agent to the application startup script, then restart. |
| On each restart | Must manually reattach the agent after every restart. | Agent starts automatically with the application. |
| Account requirement | The account starting the agent must match the account that started the application. | No account permission concerns. |
Method 1: Attach without restarting
Add system operation permissions to the javaagent directory, then run the following command with ${pid} replaced by the process ID of the application.
Unix:
./attach.sh -p ${pid}Windows:
java -cp "%JAVA_HOME%\lib\tools.jar;%cd%\javaagent-bootstrap.jar" com.alibaba.adam.javaagent.bootstrap.AgentAttacher -p ${pid}Verify: Check the log file in the javaagent directory for a success message. If inbound traffic reaches the application and the collector directory contains a data subdirectory, the agent has started and is sending data.
Make sure the process ID is correct and that the account starting the agent matches the account that started the application. If the application was started as a system user via Windows Registry, Method 1 will fail due to account permission differences — use Method 2 instead.
Method 2: Start with application (recommended)
Replace ${javaagent_path} with the actual path to the javaagent directory in the configuration file, then restart the application.
Unix
| Middleware | Startup file | Configuration |
|---|---|---|
| Tomcat | catalina.sh | Add to the last CATALINA_OPTS item: CATALINA_OPTS="$CATALINA_OPTS -javaagent:${javaagent_path}/javaagent-bootstrap.jar" |
| JBoss | run.conf | Add to the last JAVA_OPTS item: JAVA_OPTS="$JAVA_OPTS -javaagent:${javaagent_path}/javaagent-bootstrap.jar" |
| WebLogic | startWebLogic.sh | Add to the last JAVA_OPTIONS item: JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:${javaagent_path}/javaagent-bootstrap.jar" |
| WebSphere | Config file (option 1) | JAVA_OPTS="$JAVA_OPTS -javaagent:/home/admin/javaagent/javaagent-bootstrap.jar" |
| WebSphere | Common JVM parameters (option 2) | name:javaagent value:/home/admin/javaagent/javaagent-bootstrap.jar |
| Docker containers in Kubernetes clusters | Docker image | Place the javaagent directory into the Docker image, add the corresponding config file, and deploy the image. |
Windows
| Middleware | Startup file | Configuration |
|---|---|---|
| Tomcat | catalina.bat | Add to the last CATALINA_OPTS item: CATALINA_OPTS="$CATALINA_OPTS -javaagent:${javaagent_path}/javaagent-bootstrap.jar" |
| JBoss | run.conf | Add to the last JAVA_OPTS item: JAVA_OPTS="$JAVA_OPTS -javaagent:${javaagent_path}/javaagent-bootstrap.jar" |
| WebLogic | startWebLogic.cmd | Add to the last JAVA_OPTIONS item: JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:${javaagent_path}/javaagent-bootstrap.jar" |
| WebSphere | Same as Unix | Same as Unix |
Verify: After the application starts, check the application logs for Java Agent load successfully!. If no agent information appears, the configuration path is invalid and the agent was not loaded. If an error occurs, update the script based on the error message.
Stop and resume monitoring
When the application stops: The agent stops regardless of which method was used.
Stop the agent:
Method 1: Run
./attach.sh -p ${pid} -s, or restart the application.Method 2: Remove the
-javaagentconfiguration from the startup script, then restart the application.
Resume monitoring after the agent stops: Restart the application.
Method 1: Manually start the agent after the application restarts.
Method 2: The agent starts automatically when the application restarts.
JBoss clusters: For both Community Edition and Enterprise Edition clusters, if the
jboss.modules.system.pkgsconfiguration item exists, addcom.alibaba.adam.javaagentto that item and restart the application before monitoring takes effect, regardless of which method you use.
Collect data
Run the collector for 1 to 7 days to gather sufficient data.
When ready to upload:
Go to the
data/directory in the collector installation directory.Compress the collected files in ZIP format, organized by application name.
Upload each application's ZIP file separately — one profile per application.
Packaging rules:
Data from different IP addresses for the same application can be combined into one ZIP file.
Data for different applications must not be combined into one ZIP file. Mixing applications causes an upload error.