Practical Guide to Using Arthas for Java Debugging, Monitoring, and Hot‑Swap

Introduction

A Java developer reflects on six years of using Arthas, a powerful Java monitoring and diagnostic tool, and explains how it helped solve many real‑world debugging scenarios without relying on excessive logging or redeployment.

Typical Pain Points

Reproducing client‑side issues.

Silent exceptions and unclear ownership.

Debugging production bugs without logs or source.

Long debug sessions causing team frustration.

Risky redeployments and missing debug ports.

"Until I discovered Arthas, those seemingly unsolvable problems became trivial."

1. Executing Methods with vmtool

The vmtool command is the most frequently used Arthas feature. It allows invoking any method, inspecting parameters, return values, and even modifying data on‑the‑fly.

1.1 Scenarios

Problem

Description

Incorrect cache key after release

Invoke service method to delete the key.

Missing logs, uncertain upstream data

Invoke method to verify returned data.

Distributed config push failure

Query latest configuration via method call.

案例还有很多很多，因为真的可以拿着入参尽情的 invoke

Using vmtool dramatically speeds up issue isolation and eliminates the need for repetitive deployments.

1.2 Usage Example

In IDEA, install the Arthas plugin to generate commands. For an object‑type parameter:

vmtool -x 3 -c 76707e36 --action getInstances --className com.xxx.impl.IbCcContactConfigServiceImpl --express 'instances[0].queryIbCcContactConfig((#demo=new com.xxx.param.IbCcContactConfigParam(),#demo.setContactBizCode("12345L"),#demo))'

For primitive types:

vmtool -x 3 --action getInstances --className com.xxl.mq.admin.service.IXxlMqMessageService --express 'instances[0].delete(0)'

1.3 Limitations

Avoid ThreadLocal contexts; they are not available.

Only one Arthas server port can be used at a time.

1.4 Extensions

Use getstatic to view or modify static fields, e.g.:

getstatic com.xxx.xxx.interceptor.env.EnvIsolationInterceptor FILL_FIELD_NAME -x 3

ognl -x 3 '#[email protected]@class.getDeclaredField("ENV"),#field.setAccessible(true),#field.set(null," ")'

2. Hot Deployment (redefine & retransform)

Hot‑swap eliminates the need for full redeployments, saving hours of downtime. The ArthasHotSwap plugin integrates with IDEA for one‑click swaps.

"Many companies integrate Arthas via API for customized usage."

2.1 Scenarios

Add logging without redeploy.

Fix hard‑coded conditions on the fly.

Patch missing assignments.

Iterative verification during development.

2.2 Usage

Install the ArthasHotSwap plugin in IDEA and invoke the generated command directly from the editor.

2.3 Limitations

Cannot add new fields or methods.

Running methods must return before changes take effect.

Conflicts with other commands like watch , trace , jad , tt .

Hot deployment is powerful but should be used cautiously in production.

3. OGNL & Conditional Filtering

OGNL expressions enable precise filtering for watch , trace , stack , and monitor commands, targeting specific parameters or execution times.

3.1 Example

Watch only calls where the first argument equals a specific org ID:

watch com.xxx.controller.OrgServiceController getOrgInfo '{params,returnObj,throwExp}' 'params[0] == "orgIdxxx726"' -n 5 -x 3

Trace the same condition:

trace com.xxx.controller.OrgServiceController getOrgInfo 'params[0] == "orgIdxxx726"' -n 5 --skipJDKMethod false

3.2 Extended Usage

Combine multiple conditions, e.g., filter out null parameters or match specific strings.

trace com.xxx.controller.OrgServiceController getOrgInfo 'params[0] != null'
trace *com.xxx.controller.OrgServiceController getOrgInfo 'params[0] == 1L'
trace com.xxx.controller.OrgServiceController getOrgInfo 'params[1] != "AA"'

4. Other Useful Commands

4.1 logger

Adjust log levels at runtime:

logger -n com.xxx.controller.OrgServiceControlle
logger --name ROOT --level debug -c 4839ebd

4.2 monitor

Track method invocation counts, average latency, and success rate:

monitor com.XXXX.handler.HandlerManager process -n 10 --cycle 10

4.3 thread

Detect deadlocks and inspect thread states:

thread -b
thread -n 3

4.4 jad

Decompile classes to verify loaded bytecode, useful for NoSuchMethodError issues.

4.5 watch

Observe method arguments and return values with OGNL filters:

watch com.xxl.mq.admin.service.IXxlMqMessageService pageList '{params,returnObj,throwExp}' -n 5 -x 4

Filter by execution cost:

watch demo... primeFactors '{params, returnObj}' '#cost>200' -x 2

4.6 tt (Time Tunnel)

Replay method calls; similar capabilities to vmtool .

4.7 Less‑Used Commands

memory : view memory usage.

options : toggle global Arthas switches.

sysprop / sysenv : inspect JVM system properties.

profiler : generate flame graphs.

dashboard : real‑time metrics panel.

4.8 Arthas Plugin

The plugin can auto‑generate commands for the above operations, further simplifying workflow.

"Images are from the Arthas plugin author; both the plugin and article are excellent."

5. Limitations & Precautions

Inserting code for trace / tt may affect JIT‑compiled code and cause jitter under high concurrency.

Only one Arthas server port is allowed.

Hot‑swap is high‑risk in production; ensure thorough testing.

If the target service is unresponsive, Arthas may fail to start and require OS‑level troubleshooting.

6. Recommended Reading

Official Arthas documentation.

Arthas IDEA plugin manual (highly recommended).

7. Final Thoughts

Mastering Arthas requires continuous practice: "Reading alone gives shallow knowledge; only hands‑on experience leads to true mastery."