Master Java Troubleshooting with Arthas: Installation, Commands, and Real‑World Examples

Preface

Before using Arthas, diagnosing Java production issues required many commands (jps, jstack, jmap, etc.) which were cumbersome. Arthas simplifies common problems like CPU spikes, high load, memory leaks, allowing quick diagnosis and faster resolution.

1. Introduction to Arthas

Arthas is an open‑source Java diagnostic tool released by Alibaba in September 2018. It supports JDK 6+ and provides an interactive command‑line interface with Tab completion. By the time of writing it has received over 17 000 stars on GitHub.

2. Typical Use Cases

Arthas can be used to:

Get a global view of the JVM’s runtime status.

Identify which class or method is consuming CPU.

Detect thread deadlocks or blocking.

Locate long‑running code paths.

Find the JAR that loaded a particular class and troubleshoot ClassNotFoundException.

Verify whether recent code changes have taken effect.

Debug production issues without adding log statements.

Monitor real‑time JVM metrics.

3. How to Use Arthas

3.1 Installation

Download the arthas-boot.jar from the official GitHub repository (or the Gitee mirror) and make it executable.

## github download
wget https://alibaba.github.io/arthas/arthas-boot.jar
## or Gitee download
wget https://arthas.gitee.io/arthas-boot.jar
## print help
java -jar arthas-boot.jar -h

3.2 Running

Start Arthas with java -jar arthas-boot.jar. After the logo appears, select the target Java process (PID) either interactively or by passing the PID on the command line.

## interactive mode
java -jar arthas-boot.jar
[INFO] Found existing java process, please choose one and hit RETURN.
* [1]: 11616 com.Arthas
  [2]: 8676
  ...

## direct mode
java -jar arthas-boot.jar <pid>

You can list Java processes with ps or jps.

# list processes
jps -mlvV
# filter
jps -mlvV | grep <pattern>

After the Arthas console starts, you can execute diagnostic commands.

3.3 Web Console

Arthas also provides a Web Console accessible at http://127.0.0.1:8563/, which mirrors the command‑line interface.

3.4 Common Commands

Command

Description

dashboard

Real‑time system metrics panel

thread

Show thread stack and CPU usage

watch

Observe method input/output and exceptions

trace

Trace method call chain with timing

stack

Display call stack of a method

tt

Time‑travel tunnel for method invocations

monitor

Periodically collect method execution statistics

jvm

Show JVM information

vmoption

View or modify JVM diagnostic options

sc

Show loaded class information

sm

Show methods of a class

jad

Decompile a loaded class

classloader

Inspect classloader hierarchy

heapdump

Generate a heap dump (similar to jmap)

3.5 Exit

Use the shutdown command to exit Arthas and automatically reset any enhanced classes.

4. Practical Operations

Below are typical workflows for common problems.

4.1 Global Monitoring

Run dashboard to get an overview of threads, memory, GC and environment.

4.2 CPU Spike Diagnosis

Use thread to list all threads and their CPU usage. The thread with the highest CPU can be inspected further with thread <id>.

4.3 Thread‑Pool Status

Identify thread states (RUNNABLE, TIMED_WAITING, WAITING, BLOCKED) and detect threads blocked due to a full pool.

4.4 Deadlock Detection

Execute thread -b to list threads involved in a deadlock.

4.5 Decompilation

Use jad com.Arthas to view source code of a loaded class. Options such as --source-only limit output to source.

jad --source-only com.Arthas
jad --source-only com.Arthas mysql

4.6 Field Inspection

Show class fields with sc -d -f com.Arthas.

sc -d -f com.Arthas

4.7 Method Inspection

List methods using sm com.Arthas.

sm com.Arthas

4.8 Variable Observation

Query static variables with ognl '@com.Arthas@hashSet', check size, add elements, etc.

ognl '@[email protected]()'
ognl '@[email protected]("test")'

4.9 Performance Analysis

Use trace to find slow methods, monitor to collect periodic statistics, and watch to view parameters and return values.

trace com.UserController getUser
monitor -c 5 com.UserServiceImpl get
watch com.Arthas addHashSet '{params[0],returnObj}'

4.10 Time‑Travel Tunnel

Start recording with tt -t com.UserServiceImpl check, list records with tt -l, view a specific record with tt -i 1001, and replay with tt -i 1001 -p.

References

Arthas GitHub: https://github.com/alibaba/arthas

Official documentation: https://alibaba.github.io/arthas