# Arthas: diagnosing a running JVM without a restart

> Alibaba's Arthas attaches to a live Java process and lets you inspect classes, trace slow calls and watch method invocations from a terminal. This article covers how it attaches, how to get a first command running, and where it stops being the right tool.

**alibaba/arthas** — Alibaba Java Diagnostic Tool Arthas/Alibaba Java诊断利器Arthas

- Repository: https://github.com/alibaba/arthas
- Website: https://arthas.aliyun.com/
- Stars: 37,561 · Forks: 7,641
- Language: Java
- License: Apache-2.0
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/alibaba-arthas

## The production debugging gap Arthas was built to close

The README states the problem plainly: production networks are often unreachable from a developer's machine, remote IDE debugging is unacceptable because it suspends all threads, and reproducing the same failure on staging is unreliable because some issues vanish after a restart. Adding log lines means a test, staging and production cycle before you learn anything.

Arthas targets that window. It attaches to a running JVM and inspects it from the outside. The README describes it as an observer that never suspends your existing threads, which is the property that makes it usable on a machine serving traffic. The audience is the engineer who owns a Java service in production: backend developers, SREs and support engineers who get a stack trace or a latency complaint and need to know which classloader loaded a jar, what a method actually returned, or which sub-call is eating the time.

## How the agent attaches and what the commands actually observe

Arthas works through a Java agent. The boot jar locates running JVMs, you pick one, and the agent is attached to that process; the interactive console then talks to the agent over telnet or websocket, which is why the README lists both local and remote diagnostics with command line and browsers as supported modes. The repository layout reflects this split: core/, client/, boot/, agent/, spy/ and tunnel-server/ are separate modules, with web-ui/ for the browser console.

The command set follows from what an agent can see. sc searches loaded classes and reports where a class was loaded from, which is how jar conflicts get resolved. jad decompiles a class so you can confirm the bytecode running in production matches the source you think you deployed. classloader statistics expose the hierarchy and possible leaks. trace follows a method into its sub-invocations to find the slow one, watch prints parameters, return values and exceptions for chosen invocations, and thread ranks threads by CPU usage. There is also a memory compiler (mc) that turns .java files into .class files in memory, and retransform, which loads external .class files to hotswap already-loaded classes. The README notes that version 4.x supports JDK 8 and above, including JDK 17, JDK 21 and JDK 25, on Linux, Mac and Windows.

## Installing Arthas and running thread and sc on a live process

The README recommends arthas-boot.jar. Download it and start it with java; it lists the JVMs it can find and asks you to choose one by number.

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

After you select a process, the console prompt appears. The first useful command is thread, which ranks threads by CPU usage and shows the stack of the busiest ones. The README gives this example invocation:

```bash
thread -n 3
```

You should see the top three CPU-consuming threads with their stacks, which is usually enough to tell a busy worker from a spinning loop. To check whether a class is loaded and where it came from, use sc with the -d flag for detail:

```bash
sc -d org.springfra
```

The README shows that prefix form, and sc accepts a partial class name, so you do not need the fully qualified name to start. On Linux, Unix and Mac there is a second install path that downloads the as.sh bootstrap script into the current directory:

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

The README says you can move as.sh anywhere or put its location in $PATH, then run as.sh for the interactive interface or as.sh -h for help. A Dockerfile is also in the repository, built on amazoncorretto:8-alpine-jdk, which downloads arthas-packaging from Maven Central into /opt/arthas and sets tini as the entrypoint.

## Where Arthas stops being the right tool

Arthas is a diagnostic session, not a monitoring system. Nothing in the README describes persistent metrics storage, alerting or historical dashboards; the dashboard, thread and monitor commands print to your terminal while you are attached. If you need long-term latency percentiles and alerts, this is the wrong layer.

There is a harder constraint. The README's FAQ reference and the project's own documentation point at JIT behaviour: when a JVM runs with -Xint, methods are interpreted and the trace and watch machinery behaves differently, so the README warns about that case. Anyone diagnosing a performance problem on an interpreter-only JVM should know that before trusting a trace result.

Cost is the other boundary. trace and watch instrument the methods you name, so every invocation passes through the instrumentation while the command is active. The README's framing of Arthas as a non-suspending observer is accurate about thread suspension, but it does not mean the instrumentation is free. Naming a method that runs thousands of times per second on a hot path is a decision to make deliberately, not a default. Finally, the attach model assumes you can reach the target JVM and that the account you use is allowed to attach to it. In locked-down environments where agent attachment is blocked by policy, Arthas has no path in.

## Arthas compared with a profiler such as async-profiler

The repository vendors async-profiler under async-profiler/, and the README lists profiler and flame graph support as a feature, so the two are not opposites: Arthas can drive a sampling profiler. The difference is in the default mode of inquiry. A sampling profiler answers where CPU time goes across the whole process by collecting stacks at intervals; it needs no knowledge of which method is suspect and it produces a flame graph you read afterwards. Arthas's trace and watch answer questions about specific methods you already suspect, with exact parameters and return values rather than statistical samples.

That makes the choice straightforward. If you do not yet know which code is slow, start with the profiler and read the flame graph. If you already know the method and need to see its arguments, its return value or which sub-call dominates, trace and watch give you a direct answer that a sampling profile cannot. Running both in the same session is possible, and for a latency investigation that is often the sequence: profile first, then trace the frame that stands out.

## Maintenance, releases and the Apache-2.0 licence

The repository is not archived. The last push was on 2026-08-13, and the most recent release in the same window is arthas-all-4.3.4, following arthas-all-4.3.3 on 2026-08-12 and arthas-all-4.3.2 on 2026-07-19. That is a steady release cadence, and the Dockerfile in the repository pins ARTHAS_VERSION to 4.3.5, which suggests the packaging image tracks releases closely. Note that the Dockerfile's default ARTHAS_VERSION and the latest tagged release do not have to match at any given moment; if you build that image, check which version the argument resolves to.

Upgrade cost is low for the boot jar path: you download a new arthas-boot.jar and attach again, and no application code changes. The as.sh script is likewise a single file to replace. The Spring Boot Starter and the MCP server are the pieces that touch your build, so those carry the real upgrade work. Arthas is licensed under Apache-2.0, with a NOTICE file in the repository root; the usual obligations for that licence apply, and if you redistribute the packaging you should read the NOTICE rather than assume it is empty. This is not legal advice.

## Conclusion

Adopt Arthas when the failing process is the only place a bug reproduces and restarting it is not an option: the attach model, sc, jad, trace and thread cover exactly that ground. Do not adopt it as an APM replacement or as a way to leave instrumentation running in production indefinitely, because every trace and watch adds observation cost to the methods you name. Before rolling it out, verify that your JIT is not running with -Xint (the README's own warning), that the target JVM accepts an attach from the account you will use, and that your team has a documented way to stop the tunnel-server or web console session when the investigation ends.

## FAQ

### What is Arthas and who is it for?

The README describes Arthas as a Java diagnostic tool open sourced by Alibaba that lets developers troubleshoot production issues without modifying code or restarting servers. It is aimed at engineers who need to inspect a running JVM they cannot debug with an IDE.

### How do I install Arthas?

The recommended path is to download arthas-boot.jar and start it with java -jar arthas-boot.jar. On Linux, Unix and Mac you can instead run the install script, which downloads the as.sh bootstrap script to the current directory.

### Which JDK versions does Arthas support?

The README states that version 4.x supports JDK 8 and above, including JDK 17, JDK 21 and JDK 25, on Linux, Mac and Windows.

### Does Arthas restart or suspend the application?

No. The README says Arthas works as an observer that never suspends your existing threads, and that it troubleshoots production issues without a JVM restart or code changes.

### Can Arthas be used remotely?

The README lists telnet and websocket support as enabling both local and remote diagnostics through the command line and browsers, and the repository includes tunnel-server and web-ui modules for that purpose.

## Sources

- [Official documentation](https://arthas.aliyun.com/)
- [Official README](https://github.com/alibaba/arthas#readme)
- [Project repository](https://github.com/alibaba/arthas)
- [Release notes](https://github.com/alibaba/arthas/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alibaba-arthas