Mastering Arthas: A Practical Guide to Java Runtime Debugging and Monitoring

Arthas is an open‑source Java online diagnostic tool from Alibaba, enabling developers to inspect and troubleshoot running JVM processes without restarting the application.

1. Runtime Principle

Arthas leverages the Java Instrumentation API introduced in JDK 5, which allows an external agent to attach to a JVM, monitor class loading, and modify class definitions at runtime. Starting with JDK 6, the Attach API makes it possible to load the agent dynamically on a running process.

All Arthas features—class redefinition, method tracing, heap dump, etc.—are implemented through this instrumentation mechanism.

2. Environment Installation

Download the boot jar and start Arthas:

curl -O https://arthas.aliyun.com/arthas-boot.jar
java -jar arthas-boot.jar

Show help information: java -jar arthas-boot.jar -h If the download is slow, use the Aliyun mirror:

java -jar arthas-boot.jar --repo-mirror aliyun --use-http

One‑click installation on Linux/Unix/macOS:

curl -L https://arthas.aliyun.com/install.sh | sh

After the script is saved as as.sh, run ./as.sh to enter the interactive console, or ./as.sh -h for more options.

3. Command Reference

Basic commands

help : display command help.

cls : clear the screen.

session : show current session information.

reset : restore all classes enhanced by Arthas.

version : print the Arthas version of the target JVM.

quit : exit the current Arthas client.

shutdown : stop the Arthas server and disconnect all clients.

keymap : list or customize shortcut keys.

history : print command history.

cat , echo , grep , tee , pwd : familiar Linux‑like utilities.

System commands

dashboard : real‑time system metrics panel.

thread : view thread information and stack traces.

jvm : display JVM details.

sysprop : show system properties ( SystemProperty).

sysenv : show environment variables ( SystemEnvironmentVariables).

getstatic : read a static field of a class.

ognl : evaluate an OGNL expression.

mbean : inspect MBean attributes.

vmoption : view or modify VM diagnostic options.

vmtool : use JVMTI for memory inspection, forced GC, etc.

perfcounter : display JVM performance counters.

logger : query and change logger levels.

heapdump : generate a heap dump (similar to jmap).

Class commands

sc : list loaded classes.

sm : list methods of a loaded class.

jad : decompile a loaded class.

retransform : retransform an already loaded class with a new .class file.

redefine : replace an already loaded class.

dump : dump the bytecode of a class to a directory.

classloader : show the classloader hierarchy and URLs.

Enhancement commands

monitor : monitor method execution time and count.

watch : observe method arguments, return values, and exceptions.

trace : display the call chain of a method with timing.

stack : print the call stack of the current method.

tt : record method entry/exit data for time‑travel analysis.

profiler : generate flame graphs using async‑profiler.

These commands cover most daily debugging and performance‑analysis scenarios for Java services.