---
name: arthas-diagnosis
description: >-
  Use this skill when diagnosing Java applications, troubleshooting JVM performance issues (high CPU, memory leaks, slow methods), inspecting classes or classloaders, tracing method executions, or invoking Arthas tools via the Arthas MCP server.
---

# Arthas Java Runtime Diagnosis Skill

This skill guides the AI assistant in performing real-time Java application diagnostics and troubleshooting using the **Arthas MCP (Model Context Protocol) Server**.

## When to Use

Activate this skill when:
- Investigating Java application performance issues (CPU spikes, memory leaks, slow latency).
- Finding deadlocks, blocked threads, or high-CPU threads.
- Inspecting loaded classes, classloaders, bytecode decompilation (`jad`), or method signatures (`sm`).
- Observing live method parameters, return values, and exceptions (`watch`, `trace`, `stack`).
- Interacting with live Java objects or triggering JVM-level tools (`vmtool`, `ognl`, `dashboard`).

---

## ⚠️ Safe Production Diagnostic Rules (Safety Boundary)

1. **Limit Observation Depth & Counts**:
   - For `watch`, `trace`, `stack`, ALWAYS specify `-n <count>` (e.g., `-n 5` or `-n 10`) to prevent unbounded logging and high overhead.
   - Avoid tracing heavily invoked framework methods (e.g., `String.equals`, `HashMap.get`, high-QPS filter chains) without specific conditional filters.
2. **Caution with Heapdump & Memory Allocation**:
   - Check available disk space before triggering `heapdump`.
   - Use `--live` flag where appropriate to dump only live reachable objects and reduce file size.
3. **Session Lifecycle Management**:
   - Remember to stop/reset active trace sessions to ensure bytecode instrumentation overhead is removed once the diagnosis is complete.

---

## Standard Diagnostic Playbooks

### 1. High CPU Troubleshooting Playbook

When CPU usage is abnormal or threads are stuck:
1. **Locate Hot Threads**:
   - Call `thread -n 3` (or top 5) to identify threads consuming the most CPU time.
   - Inspect the stack trace of busy threads to identify whether they are running business code loops, JSON serialization, regex matching, or GC tasks.
2. **Check Deadlocks & Locking Contention**:
   - Call `thread -b` to automatically detect threads holding locks that block other threads.
   - Call `thread -i 1000` to calculate CPU utilization over a 1-second sampling window.
3. **Correlate with JVM Dashboard**:
   - Run `dashboard` (1 iteration) to check GC frequency, heap/non-heap utilization, and OS load.

### 2. Slow Response / Latency Tracing Playbook

When an API or method execution is unusually slow:
1. **Identify Class & Method**:
   - Confirm the target class exists: `sc -d com.example.service.OrderService`
   - Check methods: `sm com.example.service.OrderService createOrder`
2. **Trace Method Call Tree**:
   - Run `trace com.example.service.OrderService createOrder -n 5 '#cost > 50'`
   - *Tip*: Filtering by `#cost > 50` captures only executions taking longer than 50ms, minimizing noise.
3. **Inspect Call Chain Hierarchy**:
   - Run `stack com.example.dao.OrderRepository queryById -n 3` to determine which caller is triggering excessive queries.

### 3. Exception & Method Data Inspection Playbook

When debugging unexpected return values or transient exceptions:
1. **Inspect Parameters & Return Values**:
   - Run `watch com.example.service.UserService getUser '{params, returnObj, throwExp}' -x 2 -n 5`
   - `-x 2` expands object properties to depth 2.
2. **Capture Exceptions Only**:
   - Run `watch com.example.service.PaymentService pay '{params, throwExp}' -e -x 2 -n 5`
   - `-e` filters triggers to when an exception is thrown.
3. **Time-Tunnel Historical Record**:
   - Run `tt -t com.example.service.OrderService calculateDiscount -n 5`
   - Use `tt -l` to view recorded invocations and inspect specific invocation contexts.

### 4. Class & Environment Verification Playbook

When investigating `ClassNotFoundException`, `NoSuchMethodError`, or configuration discrepancies:
1. **Decompile Loaded Bytecode**:
   - Run `jad com.example.config.AppProperties` to confirm whether runtime code matches git commit source.
2. **Classloader Hierarchy**:
   - Run `classloader` or `classloader -t` to inspect classloader delegation trees.
3. **Inspect Static Variables & System Properties**:
   - Run `getstatic com.example.common.Constant HOLDER` to inspect loaded static states.
   - Run `sysprop` or `vmoption` to inspect active JVM flags.

---

## Tool Reference Summary

| Category | MCP Tool Name | Primary Purpose | Common Flags |
| :--- | :--- | :--- | :--- |
| **JVM Status** | `dashboard` | Real-time overview of CPU, memory, threads, runtime | `-n 1` (single snapshot) |
| **Thread** | `thread` | Thread stacks, CPU busy threads, deadlock detection | `-n 3`, `-b`, `-i 1000` |
| **Memory** | `memory` / `heapdump` | JVM memory spaces inspection, heap dump generation | `heapdump --live <path>` |
| **Tracing** | `trace` | Method call path & elapsed time profiling | `-n 5`, `'#cost > 100'` |
| **Observation** | `watch` | Inspect method arguments, return value, exception | `-x 2`, `-e`, `-n 5` |
| **Call Stack** | `stack` | Call path leading to current method invocation | `-n 3` |
| **Decompile** | `jad` | Decompile in-memory class bytecode | `--source-only` |
| **Class Search** | `sc` / `sm` | Search loaded classes and methods | `-d` (details) |
| **Advanced** | `vmtool` / `ognl` | Force GC, get class instances, evaluate OGNL | `--action forceGc` |