Master Java Debugging with Arthas: Essential Commands and Real‑World Use Cases

Introduction

Arthas is Alibaba's open‑source Java diagnostic tool that enables dynamic tracing of Java code and real‑time JVM monitoring without interrupting program execution. It supports JDK 6+, Linux, macOS, and Windows, offering a simple entry point for JVM issue investigation.

Use Cases

Identify which JAR a class was loaded from and resolve class‑related exceptions.

Determine why modified code is not executed (e.g., commit or branch issues).

Debug problems that cannot be reproduced online without adding logs.

Investigate data‑processing issues that occur only in production.

Obtain a global view of system runtime status.

Monitor real‑time JVM state.

Installation

Download the boot JAR:

wget https://alibaba.github.io/arthas/arthas-boot.jar

Start it with java -jar:

java -jar arthas-boot.jar
[INFO] Found existing java process, please choose one and hit RETURN.
* [1]: 79952 cn.test.MobileApplication
  [2]: 93872 org.jetbrains.jps.cmdline.Launcher

Enter the number of the target application and press Enter.

Common Commands

Current version: v3.1.4

1. stack

Displays the call stack of the current method.

[arthas@79952]$ version
3.1.4

[arthas@79952]$ stack com.baomidou.mybatisplus.extension.service.IService getOne
Press Q or Ctrl+C to abort.
Affect(class-cnt:202 , method-cnt:209) cost in 10761 ms.
... (output truncated) ...

Shows that OrderController.java line 500 called the getOne method.

2. jad

Decompiles the source of a loaded class.

jad cn.test.mobile.controller.order.OrderController

Decompile a specific method:

jad cn.test.mobile.controller.order.OrderController getOrderInfo
ClassLoader:
@RequestMapping(value={"getOrderInfo"}, method={RequestMethod.POST})
public Object getOrderInfo(HttpServletRequest request, @RequestBody Map map) {
    ResponseVo responseVo = new ResponseVo();
    ...
}

3. sc (Search‑Class)

Searches for loaded classes using a pattern.

sc *OrderController*
cn.test.mobile.controller.order.OrderController

Show detailed class info:

sc -d cn.test.mobile.controller.order.OrderController
class-info        cn.test.mobile.controller.order.OrderController
class-loaderHash   18b4aac2
... (additional details) ...

4. watch

Monitors method parameters and return values.

watch cn.test.mobile.controller.order.OrderController getOrderInfo "{params,returnObj}" -x 2

Observes output parameters and return objects; add -b to watch before method execution.

watch cn.test.mobile.controller.order.OrderController getOrderInfo "{params,returnObj}" -x 3 -b

5. trace

Shows the internal call path of a method with timing information.

trace -j cn.test.mobile.controller.order.OrderController getOrderInfo

trace -j cn.test.mobile.controller.order.OrderController getOrderInfo '#cost > 10'

6. jobs

Runs background asynchronous tasks.

trace -j cn.test.mobile.controller.order.OrderController getOrderInfo > test.out &

jobs
[76]*  Running trace -j cn.test.mobile.controller.order.OrderController getOrderInfo >> test.out &
execution count : 0
start time : Wed Nov 13 16:13:23 CST 2019
...

Manage jobs with kill and adjust timeout using options job-timeout.

7. logger

View and update logger levels.

logger

logger --name ROOT --level debug
update logger level success.

8. dashboard

Displays a real‑time JVM data panel, including thread states, CPU usage, and memory statistics. dashboard Use thread <id> to view detailed stack traces for a specific thread.

thread 2
"Reference Handler" Id=2 WAITING on java.lang.ref.Reference$Lock@66ad4272
    at java.lang.Object.wait(Native Method)
    ...

9. redefine

Hot‑updates already loaded classes without restarting the application.

jad --source-only cn.test.mobile.controller.order.OrderController > OrderController.java
sc -d cn.test.mobile.controller.order.OrderController | grep classLoaderHash
classLoaderHash   18b4aac2
mc -c 18b4aac2 OrderController.java -d ./
redefine -c 18b4aac2 OrderController.class
redefine success, size: 1

Other Tips

If selecting a process with java -jar arthas-boot.jar fails because the port is already in use, shut down the conflicting process (shown as process 11544) or specify a different telnet port using --telnet-port and --http-port options.